couchbase 4.2.0 → 4.2.2

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

@@ -0,0 +1,41 @@
+[/
+ / 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:futures Futures]
+
+The `asio::use_future` completion token provides first-class support for
+returning a `std::future` from an asynchronous operation's initiating function.
+
+To use `asio::use_future`, pass it to an asynchronous operation instead of
+a completion handler. For example:
+
+  std::future<std::size_t> length =
+    my_socket.async_read_some(my_buffer, asio::use_future);
+
+Where a completion signature has the form:
+
+  void handler(asio::error_code ec, result_type result);
+
+the initiating function returns a `std::future` templated on `result_type`.
+In the above example, this is `std::size_t`. If the asynchronous operation
+fails, the `error_code` is converted into a `system_error` exception and
+passed back to the caller through the future.
+
+Where a completion signature has the form:
+
+  void handler(asio::error_code ec);
+
+the initiating function returns `std::future<void>`. As above, an error
+is passed back in the future as a `system_error` exception.
+
+[heading See Also]
+
+[link asio.reference.use_future use_future],
+[link asio.reference.use_future_t use_future_t],
+[link asio.examples.cpp11_examples.futures Futures example (C++11)].
+
+[endsect]

package/deps/couchbase-cxx-client/third_party/asio/asio/src/doc/overview/handler_tracking.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/implementation.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/iostreams.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/line_based.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/model/allocators.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:allocators Allocators]
+
+Every asynchronous agent has an associated ['allocator]. An agent's allocator
+is an interface used by the agent's asynchronous operations to obtain
+['per-operation stable memory] resources (POSMs). This name reflects the fact
+that the memory is per-operation because the memory is only retained for the
+lifetime of that operation, and stable, because the memory is guaranteed to be
+available at that location throughout the operation.
+
+Asynchronous operations may utilise POSMs in a number of different ways:
+
+* The operation doesn't require any POSMs. For example, the operation wraps an
+  existing API that performs its own memory management, or is copying the long
+  lived state into existing memory like a circular buffer.
+
+* The operation uses a single, fixed-size POSM for as long as the operation is
+  outstanding. For example, the operation stores some state in a linked list.
+
+* The operation uses a single, runtime-sized POSM. For example, the operation
+  stores a copy of a user-supplied buffer, or a runtime-sized array of iovec
+  structures.
+
+* The operation uses multiple POSMs concurrently. For example, a fixed size
+  POSM for a linked list plus a runtime-sized POSM for a buffer.
+
+* The operation uses multiple POSMs serially, which may vary in size.
+
+Associated allocators allow users to treat POSM optimisation as a cross-cutting
+concern to the composition of asynchronous operations. Furthermore, using
+allocators as the interface to obtain POSMs grant substantial flexibility to
+both the implementers and users of asynchronous operations:
+
+* Users can ignore the allocator and accept whatever default strategy is
+  employed by the application.
+
+* Implementers can ignore the allocator, especially if the operation is not
+  considered performance-sensitive.
+
+* Users can co-locate POSMs for related asynchronous operations, for better
+  locality of reference. 
+
+* For compositions that involve serial POSMs of different sizes, memory usage
+  need only be as great as the currently extant POSM. For example, consider a
+  composition that contains a short-lived operation that uses large POSMs
+  (connection establishment and handshake) followed by a long-lived operation
+  that uses small POSMs (transferring data to and from the peer).
+
+As noted previously, all resources must be released prior to calling the
+completion handler. This enables memory to be recycled for subsequent
+asynchronous operations within an agent. This allows applications with
+long-lived asynchronous agents to have no hot-path memory allocations, even
+though the user code is unaware of associated allocators.
+
+[heading See Also]
+
+[link asio.overview.core.allocation Custom Memory Allocation].
+
+[endsect]

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

@@ -0,0 +1,78 @@
+[/
+ / 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:associators Associated Characteristics and Associators]
+
+An asynchronous agent has ['associated characteristics] that specify how
+asynchronous operations should behave when composed as part of that agent, such
+as:
+
+* An allocator, which determines how the agent's asynchronous operations obtain
+  memory resources.
+
+* A cancellation slot, which determines how the agent's asynchronous operations
+  support cancellation.
+
+* An executor, which determines how the agent's completion handlers will be
+  queued and run.
+
+When an asynchronous operation is run within an asynchronous agent, its
+implementation may query these associated characteristics and use them to
+satisfy the requirements or preferences they represent. The asynchronous
+operation performs these queries by applying ['associator] traits to the
+completion handler. Each characteristic has a corresponding associator trait.
+
+An associator trait may be specialised for concrete completion handler types to:
+
+* accept the default characteristic supplied by the asynchronous operation,
+  returning this default as-is
+
+* return an unrelated implementation of the characteristic, or
+
+* adapt the supplied default to introduce additional behaviour required by the
+  completion handler.
+
+[heading Specification of an Associator]
+
+Given an associator trait named[footnote The associator traits are named
+[link asio.reference.associated_allocator `associated_allocator`],
+[link asio.reference.associated_executor `associated_executor`], and
+[link asio.reference.associated_cancellation_slot
+`associated_cancellation_slot`].] `associated_R`, having:
+
+* a source value `s` of type `S`, in this case the completion handler and its
+  type,
+
+* a set of type requirements (or a concept) `R` that define the syntactic and
+  semantic requirements of the associated characteristic, and
+
+* a candidate value `c` of type `C` that meets the type requirements `R`, which
+  represents a default implementation of the associated characteristic,
+  supplied by the asynchronous operation
+
+the asynchronous operation uses the associator trait to compute:
+
+* the type `associated_R<S, C>::type`, and
+
+* the value `associated_R<S, C>::get(s, c)`
+
+that meet the requirements defined in `R`. For convenience, these are also
+accessible via type alias `associated_R_t<S, C>` and free function
+`get_associated_R(s, c)`, respectively.
+
+The trait's primary template is specified such that:
+
+* if `S::R_type` is well-formed, defines a nested type alias type as
+  `S::R_type`, and a static member function get that returns `s.get_R()`
+
+* otherwise, if `associator<associated_R, S, C>::type` is well-formed and
+  denotes a type, inherits from `associator<associated_R, S, C>`
+
+* otherwise, defines a nested type alias type as `C`, and a static member
+  function get that returns `c`.
+
+[endsect]

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

@@ -0,0 +1,35 @@
+[/
+ / 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:async_agents Asynchronous Agents]
+
+[$async_agent_model.png [width 931px]]
+
+An ['asynchronous agent] is a sequential composition of asynchronous
+operations. Every asynchronous operation is considered to run as a part of an
+asynchronous agent, even if that agent contains only that single operation. An
+asynchronous agent is an entity that may perform work concurrently with other
+agents. Asynchronous agents are to asynchronous operations as threads are to
+synchronous operations.
+
+However, an asynchronous agent is a purely notional construct that allows us to
+reason about the context for, and composition of, asynchronous operations in a
+program. The name “asynchronous agent” does not appear in the library, nor is
+it important which concrete mechanism[footnote Such as chains of lambdas,
+coroutines, fibers, state machines, etc.] is used to compose the asynchronous
+operations in an agent.
+
+We can visualise an asynchronous agent as follows:
+ 
+[$async_agent_chain.png [width 738px]]
+
+Asynchronous agents alternately wait for an asynchronous operation to complete,
+and then run a completion handler for that operation. Within the context of an
+agent, these completion handlers represent indivisible units of schedulable
+work.
+
+[endsect]

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

@@ -0,0 +1,81 @@
+[/
+ / 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:async_ops Asynchronous Operations]
+
+[$async_op_model.png [width 421px]]
+
+An ['asynchronous operation] is the basic unit of composition in the Asio
+asynchronous model. Asynchronous operations represent work that is launched and
+performed in the background, while the user's code that initiated the work can
+continue with other things.
+
+Conceptually, the lifecycle of an asynchronous operation can be described in
+terms of the following events and phases:
+
+[$async_op_phases.png [width 861px]]
+
+An ['initiating function] is a function which may be called by the user to
+start an asynchronous operation.
+
+A ['completion handler] is a user-provided, move-only function object that will
+be invoked, at most once, with the result of the asynchronous operation. The
+invocation of the completion handler tells the user about something that has
+already happened: the operation completed, and the side effects of the
+operation were established.
+
+The initiating function and completion handler are incorporated into the user's
+code as follows:
+
+[$async_op_init_complete.png [width 496px]]
+
+Synchronous operations, being embodied as single functions, have several
+inherent semantic properties as a consequence. Asynchronous operations adopt
+some of these semantic properties from their synchronous counterparts, in order
+to facilitate flexible and efficient composition.
+
+[table
+  [
+    [Property of synchronous operations]
+    [Equivalent property of asynchronous operations]
+  ]
+  [
+    [
+      When a synchronous operation is generic (i.e. a template) the return type
+      is deterministically derived from the function and its arguments.
+    ]
+    [
+      When an asynchronous operation is generic, the completion handler's
+      arguments' types and order are deterministically derived from the
+      initiating function and its arguments.
+    ]
+  ]
+  [
+    [
+      If a synchronous operation requires a temporary resource (such as memory,
+      a file descriptor, or a thread), this resource is released before
+      returning from the function.
+    ]
+    [
+      If an asynchronous operation requires a temporary resource (such as
+      memory, a file descriptor, or a thread), this resource is released before
+      calling the completion handler.
+    ]
+  ]
+]
+
+The latter is an important property of asynchronous operations, in that it
+allows a completion handler to initiate further asynchronous operations without
+overlapping resource usage. Consider the trivial (and relatively common) case
+of the same operation being repeated over and over in a chain:
+
+[$async_op_trivial_chain.png [width 375px]]
+
+By ensuring that resources are released before the completion handler runs, we
+avoid doubling the peak resource usage of the chain of operations.
+
+[endsect]

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

@@ -0,0 +1,33 @@
+[/
+ / 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:cancellation Cancellation]
+
+In Asio, many objects, such as sockets and timers, support object-wide
+cancellation of outstanding asynchronous operations via their close or cancel
+member functions. However, certain asynchronous operations also support
+individual, targeted cancellation. This per-operation cancellation is enabled
+by specifying that every asynchronous agent has an associated ['cancellation
+slot].
+
+To support cancellation, an asynchronous operation installs a cancellation
+handler into the agent's slot. The cancellation handler is a function object
+that will be invoked when a cancellation signal is emitted by the user into the
+slot. Since a cancellation slot is associated with a single agent, the slot
+holds at most one handler at a time, and installing a new handler will
+overwrite any previously installed handler. Thus, the same slot is reused for
+subsequent asynchronous operations within the agent.
+
+Cancellation is particularly useful when an asynchronous operation contains
+multiple child agents. For example, one child agent may be complete and the
+other is then cancelled, as its side effects are no longer required.
+
+[heading See Also]
+
+[link asio.overview.core.cancellation Per-Operation Cancellation].
+
+[endsect]

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

@@ -0,0 +1,56 @@
+[/
+ / 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:child_agents Child Agents]
+
+The asynchronous operations within an agent may themselves be implemented in
+terms of child agents.[footnote In Asio these asynchronous operations are
+referred to as ['composed operations].] As far as the parent agent is
+concerned, it is waiting for the completion of a single asynchronous operation.
+The asynchronous operations that constitute the child agent run in sequence,
+and when the final completion handler runs the parent agent is resumed.
+
+[$async_child_agent_chain.png [width 802px]]
+
+As with individual asynchronous operations, the asynchronous operations built
+on child agents must release their temporary resources prior to calling the
+completion handler. We may also think of these child agents as resources that
+end their lifetimes before the completion handler is invoked.
+
+When an asynchronous operation creates a child agent, it may propagate[footnote
+Typically, by specialising the associator trait and forwarding to the outer
+completion handler.] the associated characteristics of the parent agent to the
+child agent. These associated characteristics may then be recursively
+propagated through further layers of asynchronous operations and child agents.
+This stacking of asynchronous operations replicates another property of
+synchronous operations.
+
+[table
+  [
+    [Property of synchronous operations]
+    [Equivalent property of asynchronous operations]
+  ]
+  [
+    [
+      Compositions of synchronous operations may be refactored to use child
+      functions that run on the same thread (i.e. are simply called) without
+      altering functionality.
+    ]
+    [
+      Asynchronous agents may be refactored to use asynchronous operations and
+      child agents that share the associated characteristics of the parent
+      agent, without altering functionality.
+    ]
+  ]
+]
+
+Finally, some asynchronous operations may be implemented in terms of multiple
+child agents that run concurrently. In this case, the asynchronous operation
+may choose to selectively propagate the associated characteristics of the
+parent agent.
+
+[endsect]