couchbase 3.0.0.alpha.4-universal-darwin-19 → 3.0.2-universal-darwin-19

data/ext/third_party/asio/asio/src/doc/overview/strands.qbk

@@ -1,114 +0,0 @@
-[/
- / Copyright (c) 2003-2020 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:strands Strands: Use Threads Without Explicit Locking]
-
-A strand is defined as a strictly sequential invocation of event handlers (i.e.
-no concurrent invocation). Use of strands allows execution of code in a
-multithreaded program without the need for explicit locking (e.g. using
-mutexes).
-
-Strands may be either implicit or explicit, as illustrated by the following
-alternative approaches:
-
-* Calling io_context::run() from only one thread means all event handlers
-  execute in an implicit strand, due to the io_context's guarantee that handlers
-  are only invoked from inside run().
-
-* Where there is a single chain of asynchronous operations associated with a
-  connection (e.g. in a half duplex protocol implementation like HTTP) there is
-  no possibility of concurrent execution of the handlers. This is an implicit
-  strand.
-
-* An explicit strand is an instance of `strand<>` or `io_context::strand`. All
-  event handler function objects need to be bound to the strand using
-  `asio::bind_executor()` or otherwise posted/dispatched through the strand
-  object.
-
-In the case of composed asynchronous operations, such as `async_read()` or
-`async_read_until()`, if a completion handler goes through a strand, then all
-intermediate handlers should also go through the same strand. This is needed to
-ensure thread safe access for any objects that are shared between the caller
-and the composed operation (in the case of `async_read()` it's the socket,
-which the caller can `close()` to cancel the operation).
-
-To achieve this, all asynchronous operations obtain the handler's associated
-executor by using the `get_associated_executor` function. For example:
-
-  asio::associated_executor_t<Handler> a = asio::get_associated_executor(h);
-
-The associated executor must satisfy the Executor requirements. It will be used
-by the asynchronous operation to submit both intermediate and final handlers
-for execution.
-
-The executor may be customised for a particular handler type by specifying a
-nested type `executor_type` and member function `get_executor()`:
-
-  class my_handler
-  {
-  public:
-    // Custom implementation of Executor type requirements.
-    typedef my_executor executor_type;
-
-    // Return a custom executor implementation.
-    executor_type get_executor() const noexcept
-    {
-      return my_executor();
-    }
-
-    void operator()() { ... }
-  };
-
-In more complex cases, the `associated_executor` template may be partially
-specialised directly:
-
-  struct my_handler
-  {
-    void operator()() { ... }
-  };
-
-  namespace asio {
-
-    template <class Executor>
-    struct associated_executor<my_handler, Executor>
-    {
-      // Custom implementation of Executor type requirements.
-      typedef my_executor type;
-
-      // Return a custom executor implementation.
-      static type get(const my_handler&,
-          const Executor& = Executor()) noexcept
-      {
-        return my_executor();
-      }
-    };
-
-  } // namespace asio
-
-The `asio::bind_executor()` function is a helper to bind a specific executor
-object, such as a strand, to a completion handler. This binding automatically
-associates an executor as shown above. For example, to bind a strand to a
-completion handler we would simply write:
-
-  my_socket.async_read_some(my_buffer,
-      asio::bind_executor(my_strand,
-        [](error_code ec, size_t length)
-        {
-          // ...
-        }));
-
-[heading See Also]
-
-[link asio.reference.associated_executor associated_executor],
-[link asio.reference.get_associated_executor get_associated_executor],
-[link asio.reference.bind_executor bind_executor],
-[link asio.reference.strand strand],
-[link asio.reference.io_context__strand io_context::strand],
-[link asio.tutorial.tuttimer5 tutorial Timer.5],
-[link asio.examples.cpp03_examples.http_server_3 HTTP server 3 example].
-
-[endsect]

data/ext/third_party/asio/asio/src/doc/overview/streams.qbk

@@ -1,62 +0,0 @@
-[/
- / Copyright (c) 2003-2020 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:streams Streams, Short Reads and Short Writes]
-
-Many I/O objects in Asio are stream-oriented. This means that:
-
-* There are no message boundaries. The data being transferred is a continuous
-  sequence of bytes.
-
-* Read or write operations may transfer fewer bytes than requested. This is
-  referred to as a short read or short write.
-
-Objects that provide stream-oriented I/O model one or more of the following
-type requirements:
-
-* `SyncReadStream`, where synchronous read operations are performed using a
-  member function called `read_some()`.
-
-* `AsyncReadStream`, where asynchronous read operations are performed using a
-  member function called `async_read_some()`.
-
-* `SyncWriteStream`, where synchronous write operations are performed using a
-  member function called `write_some()`.
-
-* `AsyncWriteStream`, where asynchronous write operations are performed using a
-  member function called `async_write_some()`.
-
-Examples of stream-oriented I/O objects include `ip::tcp::socket`,
-`ssl::stream<>`, `posix::stream_descriptor`, `windows::stream_handle`, etc.
-
-Programs typically want to transfer an exact number of bytes. When a short read
-or short write occurs the program must restart the operation, and continue to
-do so until the required number of bytes has been transferred. Asio provides
-generic functions that do this automatically: `read()`, `async_read()`,
-`write()` and `async_write()`.
-
-[heading Why EOF is an Error]
-
-* The end of a stream can cause `read`, `async_read`, `read_until` or
-  `async_read_until` functions to violate their contract. E.g.
-  a read of N bytes may finish early due to EOF.
-
-* An EOF error may be used to distinguish the end of a stream from a successful
-  read of size 0.
-
-[heading See Also]
-
-[link asio.reference.async_read async_read()],
-[link asio.reference.async_write async_write()],
-[link asio.reference.read read()],
-[link asio.reference.write write()],
-[link asio.reference.AsyncReadStream AsyncReadStream],
-[link asio.reference.AsyncWriteStream AsyncWriteStream],
-[link asio.reference.SyncReadStream SyncReadStream],
-[link asio.reference.SyncWriteStream SyncWriteStream].
-
-[endsect]

data/ext/third_party/asio/asio/src/doc/overview/sync_op.dot

@@ -1,67 +0,0 @@
-digraph g
-{
-  graph
-    [
-      nodesep="0.6"
-    ];
-
-  edge
-    [
-      fontname="Helvetica",
-      fontsize=10,
-      labelfontname="Helvetica",
-      labelfontsize=10
-    ];
-
-  node
-    [
-      fontname="Helvetica",
-      fontsize=10,
-      shape=box
-    ];
-
-  edge
-    [
-      arrowhead="open"
-    ]
-
-  // Program elements.
-  {
-    operating_system [ label="Operating System", shape=ellipse ];
-    io_context [ label="io_context" ];
-    io_object [ label="I/O Object\ne.g. socket" ];
-    your_program [ label="Your Program" ];
-  }
-
-  // Owning relationships.
-  {
-    edge [ arrowtail="diamond" ];
-    your_program:w -> io_object:nw;
-    your_program:se -> io_context:ne;
-  }
-
-  // Non-owning relationships;
-  {
-    io_object:sw -> io_context:w;
-  }
-
-  // Actions.
-  {
-    edge [ style="dashed", color="#808080" ];
-
-    // Forward actions.
-    {
-      your_program:sw -> io_object:n [ label="1" ];
-      io_object:s -> io_context:nw [ label="2" ];
-      io_context:sw -> operating_system:nw [ label="3" ];
-    }
-
-    // Reverse actions.
-    {
-      edge [ arrowhead="none", arrowtail="open" ];
-      io_context:se -> operating_system:ne [ label="4" ];
-      io_object:se -> io_context:n [ label="5" ];
-      your_program:s -> io_object:ne [ label="6" ];
-    }
-  }
-}

data/ext/third_party/asio/asio/src/doc/overview/threads.qbk

@@ -1,67 +0,0 @@
-[/
- / Copyright (c) 2003-2020 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:threads Threads and Asio]
-
-[heading Thread Safety]
-
-In general, it is safe to make concurrent use of distinct objects, but unsafe
-to make concurrent use of a single object. However, types such as `io_context`
-provide a stronger guarantee that it is safe to use a single object
-concurrently.
-
-[heading Thread Pools]
-
-Multiple threads may call `io_context::run()` to set up a pool of threads from
-which completion handlers may be invoked. This approach may also be used with
-`post()` as a means to perform arbitrary computational tasks across a thread
-pool.
-
-Note that all threads that have joined an `io_context`'s pool are considered
-equivalent, and the `io_context` may distribute work across them in an
-arbitrary fashion.
-
-[heading Internal Threads]
-
-The implementation of this library for a particular platform may make use of
-one or more internal threads to emulate asynchronicity. As far as possible,
-these threads must be invisible to the library user. In particular, the threads:
-
-* must not call the user's code directly; and
-
-* must block all signals.
-
-This approach is complemented by the following guarantee:
-
-* Asynchronous completion handlers will only be called from threads that are
-  currently calling `io_context::run()`.
-
-Consequently, it is the library user's responsibility to create and manage all
-threads to which the notifications will be delivered.
-
-The reasons for this approach include:
-
-* By only calling `io_context::run()` from a single thread, the user's code can
-  avoid the development complexity associated with synchronisation. For
-  example, a library user can implement scalable servers that are
-  single-threaded (from the user's point of view).
-
-* A library user may need to perform initialisation in a thread shortly after
-  the thread starts and before any other application code is executed. For
-  example, users of Microsoft's COM must call `CoInitializeEx` before any other
-  COM operations can be called from that thread.
-
-* The library interface is decoupled from interfaces for thread creation and
-  management, and permits implementations on platforms where threads are not
-  available.
-
-[heading See Also]
-
-[link asio.reference.io_context io_context],
-[link asio.reference.post post].
-
-[endsect]

data/ext/third_party/asio/asio/src/doc/overview/timers.qbk

@@ -1,52 +0,0 @@
-[/
- / Copyright (c) 2003-2020 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:timers Timers]
-
-Long running I/O operations will often have a deadline by which they must have
-completed. These deadlines may be expressed as absolute times, but are often
-calculated relative to the current time.
-
-As a simple example, to perform a synchronous wait operation on a timer using a
-relative time one may write:
-
-  io_context i;
-  ...
-  deadline_timer t(i);
-  t.expires_from_now(boost::posix_time::seconds(5));
-  t.wait();
-
-More commonly, a program will perform an asynchronous wait operation on a
-timer:
-
-  void handler(asio::error_code ec) { ... }
-  ...
-  io_context i;
-  ...
-  deadline_timer t(i);
-  t.expires_from_now(boost::posix_time::milliseconds(400));
-  t.async_wait(handler);
-  ...
-  i.run();
-
-The deadline associated with a timer may also be obtained as a relative time:
-
-  boost::posix_time::time_duration time_until_expiry
-    = t.expires_from_now();
-
-or as an absolute time to allow composition of timers:
-
-  deadline_timer t2(i);
-  t2.expires_at(t.expires_at() + boost::posix_time::seconds(30));
-
-[heading See Also]
-
-[link asio.reference.basic_deadline_timer basic_deadline_timer],
-[link asio.reference.deadline_timer deadline_timer],
-[link asio.tutorial.tuttimer1 timer tutorials].
-
-[endsect]

data/ext/third_party/asio/asio/src/doc/overview/windows.qbk

@@ -1,126 +0,0 @@
-[/
- / Copyright (c) 2003-2020 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:windows Windows-Specific Functionality]
-
-[link asio.overview.windows.stream_handle Stream-Oriented HANDLEs]
-
-[link asio.overview.windows.random_access_handle Random-Access HANDLEs]
-
-[link asio.overview.windows.object_handle Object HANDLEs]
-
-[section:stream_handle Stream-Oriented HANDLEs]
-
-Asio contains classes to allow asynchronous read and write operations to be
-performed on Windows `HANDLE`s, such as named pipes.
-
-For example, to perform asynchronous operations on a named pipe, the following
-object may be created:
-
-  HANDLE handle = ::CreateFile(...);
-  windows::stream_handle pipe(my_io_context, handle);
-
-These are then used as synchronous or asynchronous read and write streams. This
-means the objects can be used with any of the [link asio.reference.read
-read()], [link asio.reference.async_read async_read()], [link
-asio.reference.write write()], [link asio.reference.async_write
-async_write()], [link asio.reference.read_until read_until()] or [link
-asio.reference.async_read_until async_read_until()] free functions.
-
-The kernel object referred to by the `HANDLE` must support use with I/O
-completion ports (which means that named pipes are supported, but anonymous
-pipes and console streams are not).
-
-[heading See Also]
-
-[link asio.reference.windows__stream_handle windows::stream_handle].
-
-[heading Notes]
-
-Windows stream `HANDLE`s are only available at compile time when targeting
-Windows and only when the I/O completion port backend is used (which is the
-default). A program may test for the macro `ASIO_HAS_WINDOWS_STREAM_HANDLE` to
-determine whether they are supported.
-
-[endsect]
-
-[/-----------------------------------------------------------------------------]
-
-[section:random_access_handle Random-Access HANDLEs]
-
-Asio provides Windows-specific classes that permit asynchronous read and write
-operations to be performed on HANDLEs that refer to regular files.
-
-For example, to perform asynchronous operations on a file the following object
-may be created:
-
-  HANDLE handle = ::CreateFile(...);
-  windows::random_access_handle file(my_io_context, handle);
-
-Data may be read from or written to the handle using one of the
-`read_some_at()`, `async_read_some_at()`, `write_some_at()` or
-`async_write_some_at()` member functions. However, like the equivalent
-functions (`read_some()`, etc.) on streams, these functions are only required
-to transfer one or more bytes in a single operation. Therefore free functions
-called [link asio.reference.read_at read_at()], [link
-asio.reference.async_read_at async_read_at()], [link asio.reference.write_at
-write_at()] and [link asio.reference.async_write_at async_write_at()] have been
-created to repeatedly call the corresponding [^[**]_some_at()] function until
-all data has been transferred.
-
-[heading See Also]
-
-[link asio.reference.windows__random_access_handle windows::random_access_handle].
-
-[heading Notes]
-
-Windows random-access `HANDLE`s are only available at compile time when
-targeting Windows and only when the I/O completion port backend is used (which
-is the default). A program may test for the macro
-`ASIO_HAS_WINDOWS_RANDOM_ACCESS_HANDLE` to determine whether they are
-supported.
-
-[endsect]
-
-[/-----------------------------------------------------------------------------]
-
-[section:object_handle Object HANDLEs]
-
-Asio provides Windows-specific classes that permit asynchronous wait operations
-to be performed on HANDLEs to kernel objects of the following types:
-
-* Change notification
-* Console input
-* Event
-* Memory resource notification
-* Process
-* Semaphore
-* Thread
-* Waitable timer
-
-For example, to perform asynchronous operations on an event, the following
-object may be created:
-
-  HANDLE handle = ::CreateEvent(...);
-  windows::object_handle file(my_io_context, handle);
-
-The `wait()` and `async_wait()` member functions may then be used to wait until
-the kernel object is signalled.
-
-[heading See Also]
-
-[link asio.reference.windows__object_handle windows::object_handle].
-
-[heading Notes]
-
-Windows object `HANDLE`s are only available at compile time when targeting
-Windows. Programs may test for the macro `ASIO_HAS_WINDOWS_OBJECT_HANDLE` to
-determine whether they are supported.
-
-[endsect]
-
-[endsect]