couchbase 4.2.0 → 4.2.1

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/model/completion_tokens.qbk

@@ -0,0 +1,239 @@
+[/
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:completion_tokens Completion Tokens]
+
+[$completion_token_model.png [width 436px]]
+
+A key goal of Asio's asynchronous model is to support multiple composition
+mechanisms. This is achieved via a ['completion token], which the user passes
+to an asynchronous operation's initiating function to customise the API surface
+of the library. By convention, the completion token is the final argument to an
+asynchronous operation's initiating function.
+
+For example, if the user passes a lambda (or other function object) as the
+completion token, the asynchronous operation behaves as previously described:
+the operation begins, and when the operation completes the result is passed to
+the lambda.
+
+  socket.async_read_some(buffer,
+      [](error_code e, size_t)
+      {
+        // ...
+      }
+    );
+
+When the user passes the [link asio.reference.use_future use_future] completion
+token, the operation behaves as though implemented in terms of a `promise` and
+`future` pair. The initiating function does not just launch the operation, but
+also returns a future that may be used to await the result.
+
+  future<size_t> f =
+    socket.async_read_some(
+        buffer, use_future
+      );
+  // ...
+  size_t n = f.get();
+
+Similarly, when the user passes the [link asio.reference.use_awaitable
+use_awaitable] completion token, the initiating function behaves as though it
+is an `awaitable`-based coroutine [footnote The [link asio.reference.awaitable
+awaitable] class template is included with the Asio library as a return type
+for C++20 coroutines. These coroutines can be trivially implemented in terms of
+other `awaitable`-based coroutines.]. However, in this case the initiating
+function does not launch the asynchronous operation directly. It only returns
+the `awaitable`, which in turn launches the operation when it is co_await-ed.
+
+  awaitable<void> foo()
+  {
+    size_t n =
+      co_await socket.async_read_some(
+          buffer, use_awaitable
+        );
+
+    // ...
+  }
+
+Finally, the [link asio.reference.yield_context yield_context] completion token
+causes the initiating function to behave as a synchronous operation within the
+context of a stackful coroutine. It not only begins the asynchronous operation,
+but blocks the stackful coroutine until it is complete. From the point of the
+stackful coroutine, it is a synchronous operation.
+
+  void foo(asio::yield_context yield)
+  {
+    size_t n = socket.async_read_some(buffer, yield);
+
+    // ...
+  }
+
+All of these uses are supported by a single implementation of the
+`async_read_some` initiating function.
+
+To achieve this, an asynchronous operation must first specify a ['completion
+signature] (or, possibly, signatures) that describes the arguments that will be
+passed to its completion handler.
+
+Then, the operation's initiating function takes the completion signature,
+completion token, and its internal implementation and passes them to the
+['async_result] trait. The `async_result` trait is a customisation point that
+combines these to first produce a concrete completion handler, and then launch
+the operation.
+
+[$completion_token_transform.png [width 856px]]
+ 
+To see this in practice, let's use a detached thread to adapt a synchronous
+operation into an asynchronous one:[footnote For illustrative purposes only.
+Not recommended for real world use!]
+
+  template <
+      completion_token_for<void(error_code, size_t)> /*< The `completion_token_for`
+                                                         concept checks whether
+                                                         the user-supplied
+                                                         completion token will
+                                                         satisfy the specified
+                                                         completion signature.
+                                                         For older versions of
+                                                         C++, simply use `typename`
+                                                         here instead. >*/
+        CompletionToken>
+  auto async_read_some(
+      tcp::socket& s,
+      const mutable_buffer& b,
+      CompletionToken&& token)
+  {
+    auto init = []( /*< Define a function object that contains the code to
+                        launch the asynchronous operation. This is passed the
+                        concrete completion handler, followed by any additional
+                        arguments that were passed through the `async_result`
+                        trait. >*/
+        auto completion_handler,
+        tcp::socket* s,
+        const mutable_buffer& b)
+    {
+      std::thread( /*< The body of the function object spawns a new thread to
+                       perform the operation. >*/
+          [](
+              auto completion_handler,
+              tcp::socket* s,
+              const mutable_buffer& b
+            )
+          {
+            error_code ec;
+            size_t n = s->read_some(b, ec);
+            std::move(completion_handler)(ec, n); /*< Once the operation
+                                                      completes, the completion
+                                                      handler is passed the
+                                                      result. >*/
+          },
+          std::move(completion_handler),
+          s,
+          b
+        ).detach();
+    };
+
+    return async_result< /*< The `async_result` trait is passed the (decayed)
+                             completion token type, and the completion
+                             signatures of the asynchronous operation. >*/
+        decay_t<CompletionToken>,
+        void(error_code, size_t)
+      >::initiate(
+          init, /*< Call the trait’s `initiate` member function, first passing
+                    the function object that launches the operation. >*/
+          std::forward<CompletionToken>(token), /*< Next comes the forwarded
+                                                    completion token. The trait
+                                                    implementation will convert
+                                                    this into a concrete
+                                                    completion handler. >*/
+          &s, /*< Finally, pass any additional arguments for the function
+                  object. Assume that these may be decay-copied and moved by the
+                  trait implementation. >*/
+          b
+        );
+  }
+
+In practice we should call the [link asio.reference.async_initiate
+async_initiate] helper function, rather than use the `async_result` trait
+directly. The `async_initiate` function automatically performs the necessary
+decay and forward of the completion token, and also enables backwards
+compatibility with legacy completion token implementations.
+
+  template <
+      completion_token_for<void(error_code, size_t)>
+        CompletionToken>
+  auto async_read_some(
+      tcp::socket& s,
+      const mutable_buffer& b,
+      CompletionToken&& token)
+  {
+    auto init = /* ... as above ... */;
+
+    return async_initiate<
+        CompletionToken,
+        void(error_code, size_t)
+      >(init, token, &s, b);
+  }
+
+We can think of the completion token as a kind of proto completion handler. In
+the case where we pass a function object (like a lambda) as the completion
+token, it already satisfies the completion handler requirements. The
+async_result primary template handles this case by trivially forwarding the
+arguments through:
+
+  template <class CompletionToken, completion_signature... Signatures>
+  struct async_result
+  {
+    template <
+        class Initiation,
+        completion_handler_for<Signatures...> CompletionHandler,
+        class... Args>
+    static void initiate(
+        Initiation&& initiation,
+        CompletionHandler&& completion_handler,
+        Args&&... args)
+    {
+      std::forward<Initiation>(initiation)(
+          std::forward<CompletionHandler>(completion_handler),
+          std::forward<Args>(args)...);
+    }
+  };
+
+We can see here that this default implementation avoids copies of all
+arguments, thus ensuring that eager initiation is as efficient as possible.
+
+On the other hand, a lazy completion token (such as `use_awaitable` above) may
+capture these arguments for deferred launching of the operation. For example, a
+specialisation for a trivial [link asio.reference.deferred deferred] token
+(that simply packages the operation for later) might look something like this:
+
+  template <completion_signature... Signatures>
+  struct async_result<deferred_t, Signatures...>
+  {
+    template <class Initiation, class... Args>
+    static auto initiate(Initiation initiation, deferred_t, Args... args)
+    {
+      return [
+          initiation = std::move(initiation),
+          arg_pack = std::make_tuple(std::move(args)...)
+        ](auto&& token) mutable
+      {
+        return std::apply(
+            [&](auto&&... args)
+            {
+              return async_result<decay_t<decltype(token)>, Signatures...>::initiate(
+                  std::move(initiation),
+                  std::forward<decltype(token)>(token),
+                  std::forward<decltype(args)>(args)...
+                );
+            },
+            std::move(arg_pack)
+          );
+      };
+    }
+  };
+
+[endsect]

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/model/executors.qbk

@@ -0,0 +1,55 @@
+[/
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:executors Executors]
+
+Every asynchronous agent has an associated ['executor]. An agent's executor
+determines how the agent's completion handlers are queued and ultimately run.
+
+Example uses of executors include:
+
+* Coordinating a group of asynchronous agents that operate on shared data
+  structures, ensuring that the agents' completion handlers never run
+  concurrently[footnote In Asio, this kind of executor is called a [link
+  asio.overview.core.strands strand].].
+
+* Ensuring that agents are run on specified execution resource (e.g. a CPU)
+  that is proximal to data or an event source (e.g. a NIC).
+
+* Denoting a group of related agents, and so enabling dynamic thread pools to
+  make smarter scheduling decisions (such as moving the agents between
+  execution resources as a unit).
+
+* Queuing all completion handlers to run on a GUI application thread, so that
+  they may safely update user interface elements.
+
+* Returning an asynchronous operation's default executor as-is, to run
+  completion handlers as close as possible to the event that triggered the
+  operation's completion.
+
+* Adapting an asynchronous operation's default executor, to run code before and
+  after every completion handler, such as logging, user authorisation, or
+  exception handling.
+
+* Specifying a priority for an asynchronous agent and its completion handlers.
+
+The asynchronous operations within an asynchronous agent use the agent's
+associated executor to:
+
+* Track the existence of the work that the asynchronous operation represents,
+  while the operation is outstanding.
+
+* Enqueue the completion handler for execution on completion of an operation.
+
+* Ensure that completion handlers do not run re-entrantly, if doing so might
+  lead to inadvertent recursion and stack overflow.
+
+Thus, an asynchronous agent's associated executor represents a policy of how,
+where, and when the agent should run, specified as a cross-cutting concern to
+the code that makes up the agent.
+
+[endsect]

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/model/higher_levels.qbk

@@ -0,0 +1,40 @@
+[/
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:higher_levels Higher Level Abstractions]
+
+[$higher_level_model.png [width 940px]]
+
+The asynchronous model presented in this section provides a basis for defining
+higher level abstractions. Asio builds on this core model to provide additional
+facilities, such as:
+
+* I/O objects such as [link asio.overview.networking sockets] and [link
+  asio.overview.timers timers] that expose asynchronous operations on top of
+  this model.
+
+* Concrete executors, such as the [link asio.reference.io_context io_context]
+  executor, [link asio.reference.thread_pool thread_pool] executor, and the
+  [link asio.reference.strand strand] adapter which guarantees non-concurrent
+  execution of completion handlers.
+
+* Completion tokens that facilitate different composition mechanisms, such as
+  [link asio.overview.composition.cpp20_coroutines C++ coroutines], [link
+  asio.overview.composition.spawn stackful coroutines], [link
+  asio.overview.composition.futures futures], and [link
+  asio.reference.deferred deferred operations].
+
+* High level support for C++ coroutines that combines support executors and
+  cancellation slots to allow for [link
+  asio.overview.composition.cpp20_coroutines.co_ordinating_parallel_coroutines
+  easy coordination of concurrent asynchronous agents].
+
+To allow users to more easily write their own asynchronous operations that
+adhere to this model, Asio also provides the helper function [link
+asio.reference.async_compose async_compose].
+
+[endsect]

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/model/library_elements.qbk

@@ -0,0 +1,102 @@
+[/
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:library_elements Supporting Library Elements]
+
+The Asio asynchronous model is enabled by the library elements listed in the
+table below.
+
+[table
+  [
+    [Library Element]
+    [Description]
+  ]
+  [
+    [
+      `completion_signature` concept
+    ]
+    [
+      Defines valid completion signature forms.
+    ]
+  ]
+  [
+    [
+      `completion_handler_for` concept
+    ]
+    [
+      Determines whether a completion handler is callable with a given set of
+      completion signatures.
+    ]
+  ]
+  [
+    [
+      [link asio.reference.async_result async_result] trait
+    ]
+    [
+      Converts a completion signature and completion token into a concrete
+      completion handler, and launches the operation.
+    ]
+  ]
+  [
+    [
+      [link asio.reference.async_initiate async_initiate] function
+    ]
+    [
+      Helper function to simplify use of the `async_result` trait.
+    ]
+  ]
+  [
+    [
+      `completion_token_for` concept
+    ]
+    [
+      Determines whether a completion token produces a completion handler for a
+      given set of completion signatures.
+    ]
+  ]
+  [
+    [
+      [link asio.reference.associator associator] trait
+    ]
+    [
+      Automatically propagates all associators through layers of abstraction.
+    ]
+  ]
+  [
+    [
+      [link asio.reference.associated_executor associated_executor] trait,
+      `associated_executor_t` type alias, and [link
+      asio.reference.get_associated_executor get_associated_executor] function
+    ]
+    [
+      Defines an asynchronous agent’s associated executor.
+    ]
+  ]
+  [
+    [
+      [link asio.reference.associated_allocator associated_allocator] trait,
+      `associated_allocator_t` type alias, and [link
+      asio.reference.get_associated_allocator get_associated_allocator] function
+    ]
+    [
+      Defines an asynchronous agent’s associated allocator.
+    ]
+  ]
+  [
+    [
+      [link asio.reference.associated_cancellation_slot
+      associated_cancellation_slot] trait, `associated_cancellation_slot_t`
+      type alias, and [link asio.reference.get_associated_cancellation_slot
+      get_associated_cancellation_slot] function
+    ]
+    [
+      Defines an asynchronous agent’s associated cancellation slot.
+    ]
+  ]
+]
+
+[endsect]

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/model.qbk

@@ -0,0 +1,40 @@
+[/
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:model Asynchronous Model]
+
+This section presents a high-level overview of the asynchronous model at the
+core of the Asio library. This model enshrines asynchronous operations as the
+fundamental building block of asynchronous composition, but in a way that
+decouples them from the composition mechanism. The asynchronous operations in
+Asio support callbacks, futures (both eager and lazy), fibers, coroutines, and
+approaches yet to be imagined. This allows the application programmer to select
+an approach based on appropriate trade-offs.
+
+* [link asio.overview.model.async_ops Asynchronous Operations]
+* [link asio.overview.model.async_agents Asynchronous Agents]
+* [link asio.overview.model.associators Associated Characteristics and Associators]
+* [link asio.overview.model.child_agents Child Agents]
+* [link asio.overview.model.executors Executors]
+* [link asio.overview.model.allocators Allocators]
+* [link asio.overview.model.cancellation Cancellation]
+* [link asio.overview.model.completion_tokens Completion Tokens]
+* [link asio.overview.model.library_elements Supporting Library Elements]
+* [link asio.overview.model.higher_levels Higher Level Abstractions]
+
+[include model/async_ops.qbk]
+[include model/async_agents.qbk]
+[include model/associators.qbk]
+[include model/child_agents.qbk]
+[include model/executors.qbk]
+[include model/allocators.qbk]
+[include model/cancellation.qbk]
+[include model/completion_tokens.qbk]
+[include model/library_elements.qbk]
+[include model/higher_levels.qbk]
+
+[endsect]

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/other_protocols.qbk

@@ -1,5 +1,5 @@
 [/
- / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
  /
  / Distributed under the Boost Software License, Version 1.0. (See accompanying
  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/parallel_group.qbk

@@ -0,0 +1,65 @@
+[/
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:parallel_group Co-ordinating Parallel Operations]
+
+[note This is an experimental feature.]
+
+The [link asio.reference.experimental__make_parallel_group
+`experimental::make_parallel_group`] function may be used to launch work that
+is performed in parallel, and wait for one or all of the operations to
+complete. A `parallel_group` implements automatic cancellation of incomplete
+operations. For example:
+
+  experimental::make_parallel_group(
+      [&](auto token)
+      {
+        return stream.async_read_some(asio::buffer(data), token);
+      },
+      [&](auto token)
+      {
+        return timer.async_wait(token);
+      }
+    ).async_wait(
+      experimental::wait_for_one(),
+      [](
+          std::array<std::size_t, 2> completion_order,
+          asio::error_code ec1, std::size_t n1,
+          asio::error_code ec2
+      )
+      {
+        // ...
+      }
+    );
+
+The conditions for completion of the group may be specified using one of the
+four provided function objects [link asio.reference.experimental__wait_for_all
+`wait_for_all`], [link asio.reference.experimental__wait_for_one
+`wait_for_one`], [link asio.reference.experimental__wait_for_one_success
+`wait_for_one_success`], [link asio.reference.experimental__wait_for_one_error
+`wait_for_one_error`], or with a custom function.
+
+The `parallel_group` facility can also be combined with [link
+asio.reference.deferred `deferred`] as follows:
+
+  experimental::make_parallel_group(
+      stream.async_read_some(asio::buffer(data), deferred),
+      timer.async_wait(experimental::deferred)
+    ).async_wait(
+      // ...
+    );
+
+Note: for maximum flexibility, `parallel_group` does not propagate the
+executor automatically to the operations within the group.
+
+[heading See Also]
+
+[link asio.reference.experimental__make_parallel_group experimental::make_parallel_group],
+[link asio.reference.experimental__parallel_group experimental::parallel_group],
+[link asio.examples.cpp14_examples.parallel_groups Parallel Groups examples (C++14)].
+
+[endsect]

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/pipes.qbk

@@ -0,0 +1,38 @@
+[/
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:pipes Pipes]
+
+Asio provides support for portable anonymous pipes on POSIX and Windows (when
+I/O completion ports are available). For example, to create and use a
+connected pair of pipe objects:
+
+  asio::readable_pipe read_end(my_io_context);
+  asio::writable_pipe write_end(my_io_context);
+  asio::connect_pipe(read_end, write_end);
+
+  write_end.async_write_some(my_write_buffer,
+      [](asio::error_code e, size_t n)
+      {
+        // ...
+      });
+
+  read_end.async_read_some(my_read_buffer,
+      [](asio::error_code e, size_t n)
+      {
+        // ...
+      });
+
+[heading See Also]
+
+[link asio.reference.basic_readable_pipe basic_readable_pipe],
+[link asio.reference.basic_writable_pipe basic_writable_pipe],
+[link asio.reference.connect_pipe connect_pipe],
+[link asio.reference.readable_pipe readable_pipe],
+[link asio.reference.writable_pipe writable_pipe].
+
+[endsect]

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/posix.qbk

@@ -1,5 +1,5 @@
 [/
- / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ / Copyright (c) 2003-2022 Christopher M. Kohlhoff (chris at kohlhoff dot com)
  /
  / Distributed under the Boost Software License, Version 1.0. (See accompanying
  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)