couchbase 3.0.0-universal-darwin-19 → 3.0.1-universal-darwin-19

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

@@ -1,220 +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:handler_tracking Handler Tracking]
-
-To aid in debugging asynchronous programs, Asio provides support for handler
-tracking. When enabled by defining `ASIO_ENABLE_HANDLER_TRACKING`, Asio
-writes debugging output to the standard error stream. The output records
-asynchronous operations and the relationships between their handlers.
-
-[teletype]
-This feature is useful when debugging and you need to know how your
-asynchronous operations are chained together, or what the pending asynchronous
-operations are. As an illustration, here is the output when you run the HTTP
-Server example, handle a single request, then shut down via Ctrl+C:
-
-  @asio|1512254357.979980|0*1|signal_set@0x7ffeaaaa20d8.async_wait
-  @asio|1512254357.980127|0*2|socket@0x7ffeaaaa20f8.async_accept
-  @asio|1512254357.980150|.2|non_blocking_accept,ec=asio.system:11
-  @asio|1512254357.980162|0|resolver@0x7ffeaaaa1fd8.cancel
-  @asio|1512254368.457147|.2|non_blocking_accept,ec=system:0
-  @asio|1512254368.457193|>2|ec=system:0
-  @asio|1512254368.457219|2*3|socket@0x55cf39f0a238.async_receive
-  @asio|1512254368.457244|.3|non_blocking_recv,ec=system:0,bytes_transferred=141
-  @asio|1512254368.457275|2*4|socket@0x7ffeaaaa20f8.async_accept
-  @asio|1512254368.457293|.4|non_blocking_accept,ec=asio.system:11
-  @asio|1512254368.457301|<2|
-  @asio|1512254368.457310|>3|ec=system:0,bytes_transferred=141
-  @asio|1512254368.457441|3*5|socket@0x55cf39f0a238.async_send
-  @asio|1512254368.457502|.5|non_blocking_send,ec=system:0,bytes_transferred=156
-  @asio|1512254368.457511|<3|
-  @asio|1512254368.457519|>5|ec=system:0,bytes_transferred=156
-  @asio|1512254368.457544|5|socket@0x55cf39f0a238.close
-  @asio|1512254368.457559|<5|
-  @asio|1512254371.385106|>1|ec=system:0,signal_number=2
-  @asio|1512254371.385130|1|socket@0x7ffeaaaa20f8.close
-  @asio|1512254371.385163|<1|
-  @asio|1512254371.385175|>4|ec=asio.system:125
-  @asio|1512254371.385182|<4|
-  @asio|1512254371.385202|0|signal_set@0x7ffeaaaa20d8.cancel
-
-Each line is of the form:
-
-  <tag>|<timestamp>|<action>|<description>
-
-The `<tag>` is always `@asio`, and is used to identify and extract the handler
-tracking messages from the program output.
-
-The `<timestamp>` is seconds and microseconds from 1 Jan 1970 UTC.
-
-The `<action>` takes one of the following forms:
-
-[variablelist
-  [
-    [>n]
-    [The program entered the handler number `n`. The `<description>` shows the
-    arguments to the handler.]
-  ]
-  [
-    [<n]
-    [The program left handler number `n`.]
-  ]
-  [
-    [!n]
-    [The program left handler number n due to an exception.]
-  ]
-  [
-    [~n]
-    [The handler number `n` was destroyed without having been invoked. This is
-    usually the case for any unfinished asynchronous operations when the
-    `io_context` is destroyed.]
-  ]
-  [
-    [n*m]
-    [The handler number `n` created a new asynchronous operation with completion
-    handler number `m`. The `<description>` shows what asynchronous operation
-    was started.]
-  ]
-  [
-    [n]
-    [The handler number `n` performed some other operation. The `<description>`
-    shows what function was called. Currently only `close()` and `cancel()`
-    operations are logged, as these may affect the state of pending
-    asynchronous operations.]
-  ]
-  [
-    [.n]
-    [The implementation performed a system call as part of the asynchronous
-    operation for which handler number `n` is the completion handler. The
-    `<description>` shows what function was called and its results. These
-    tracking events are only emitted when using a reactor-based
-    implementation.]
-  ]
-]
-
-Where the `<description>` shows a synchronous or asynchronous operation, the
-format is `<object-type>@<pointer>.<operation>`. For handler entry, it shows a
-comma-separated list of arguments and their values.
-
-As shown above, Each handler is assigned a numeric identifier. Where the
-handler tracking output shows a handler number of 0, it means that the action
-was performed outside of any handler.
-
-[heading Visual Representations]
-
-The handler tracking output may be post-processed using the included
-[^handlerviz.pl] tool to create a visual representation of the handlers
-(requires the GraphViz tool [^dot]).
-[c++]
-
-[heading Custom Tracking]
-
-Handling tracking may be customised by defining the
-`ASIO_CUSTOM_HANDLER_TRACKING` macro to the name of a header file
-(enclosed in `""` or `<>`). This header file must implement the following
-preprocessor macros:
-
-[table
-  [[Macro] [Description]]
-  [
-    [`ASIO_INHERIT_TRACKED_HANDLER`]
-    [Specifies a base class for classes that implement asynchronous operations.
-    When used, the macro immediately follows the class name, so it must have
-    the form `: public my_class`.]
-  ]
-  [
-    [`ASIO_ALSO_INHERIT_TRACKED_HANDLER`]
-    [Specifies a base class for classes that implement asynchronous operations.
-    When used, the macro follows other base classes, so it must have the form
-    `, public my_class`.]
-  ]
-  [
-    [`ASIO_HANDLER_TRACKING_INIT(args)`]
-    [An expression that is used to initialise the tracking mechanism.]
-  ]
-  [
-    [`ASIO_HANDLER_CREATION(args)`]
-    [An expression that is called on creation of an asynchronous operation.
-    `args` is a parenthesised function argument list containing the owning
-    execution context, the tracked handler, the name of the object type, a
-    pointer to the object, the object's native handle, and the operation name.]
-  ]
-  [
-    [`ASIO_HANDLER_COMPLETION(args)`]
-    [An expression that is called on completion of an asynchronous operation.
-    `args` is a parenthesised function argument list containing the tracked
-    handler.]
-  ]
-  [
-    [`ASIO_HANDLER_INVOCATION_BEGIN(args)`]
-    [An expression that is called immediately before a completion handler is
-    invoked. `args` is a parenthesised function argument list containing the
-    arguments to the completion handler.]
-  ]
-  [
-    [`ASIO_HANDLER_INVOCATION_END`]
-    [An expression that is called immediately after a completion handler is
-    invoked.]
-  ]
-  [
-    [`ASIO_HANDLER_OPERATION(args)`]
-    [An expression that is called when some synchronous object operation is
-    called (such as `close()` or `cancel()`). `args` is a parenthesised
-    function argument list containing the owning execution context, the name
-    of the object type, a pointer to the object, the object's native handle,
-    and the operation name.]
-  ]
-  [
-    [`ASIO_HANDLER_REACTOR_REGISTRATION(args)`]
-    [An expression that is called when an object is registered with the
-    reactor. `args` is a parenthesised function argument list containing the
-    owning execution context, the object's native handle, and a unique
-    registration key.]
-  ]
-  [
-    [`ASIO_HANDLER_REACTOR_DEREGISTRATION(args)`]
-    [An expression that is called when an object is deregistered from the
-    reactor. `args` is a parenthesised function argument list containing the
-    owning execution context, the object's native handle, and a unique
-    registration key.]
-  ]
-  [
-    [`ASIO_HANDLER_REACTOR_READ_EVENT`]
-    [A bitmask constant used to identify reactor read readiness events.]
-  ]
-  [
-    [`ASIO_HANDLER_REACTOR_WRITE_EVENT`]
-    [A bitmask constant used to identify reactor write readiness events.]
-  ]
-  [
-    [`ASIO_HANDLER_REACTOR_ERROR_EVENT`]
-    [A bitmask constant used to identify reactor error readiness events.]
-  ]
-  [
-    [`ASIO_HANDLER_REACTOR_EVENTS(args)`]
-    [An expression that is called when an object registered with the reactor
-    becomes ready. `args` is a parenthesised function argument list containing
-    the owning execution context, the unique registration key, and a bitmask of
-    the ready events.]
-  ]
-  [
-    [`ASIO_HANDLER_REACTOR_OPERATION(args)`]
-    [An expression that is called when the implementation performs a system
-    call as part of a reactor-based asynchronous operation. `args` is a
-    parenthesised function argument list containing the tracked handler, the
-    operation name, the error code produced by the operation, and (optionally)
-    the number of bytes transferred.]
-  ]
-]
-
-[heading See Also]
-
-[link asio.examples.cpp11_examples.handler_tracking Custom handler tracking
-example].
-
-[endsect]

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

@@ -1,305 +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:implementation Platform-Specific Implementation Notes]
-
-This section lists platform-specific implementation details, such as the
-default demultiplexing mechanism, the number of threads created internally, and
-when threads are created.
-
-
-[heading Linux Kernel 2.4]
-
-Demultiplexing mechanism:
-
-* Uses `select` for demultiplexing. This means that the number of file
-descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
-
-Threads:
-
-* Demultiplexing using `select` is performed in one of the threads that calls
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
-
-[heading Linux Kernel 2.6]
-
-Demultiplexing mechanism:
-
-* Uses `epoll` for demultiplexing.
-
-Threads:
-
-* Demultiplexing using `epoll` is performed in one of the threads that calls
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
-
-
-[heading Solaris]
-
-Demultiplexing mechanism:
-
-* Uses [^/dev/poll] for demultiplexing.
-
-Threads:
-
-* Demultiplexing using [^/dev/poll] is performed in one of the threads that
-calls `io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
-
-
-[heading QNX Neutrino]
-
-Demultiplexing mechanism:
-
-* Uses `select` for demultiplexing. This means that the number of file
-descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
-
-Threads:
-
-* Demultiplexing using `select` is performed in one of the threads that calls
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
-
-
-[heading Mac OS X]
-
-Demultiplexing mechanism:
-
-* Uses `kqueue` for demultiplexing.
-
-Threads:
-
-* Demultiplexing using `kqueue` is performed in one of the threads that calls
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
-
-
-[heading FreeBSD]
-
-Demultiplexing mechanism:
-
-* Uses `kqueue` for demultiplexing.
-
-Threads:
-
-* Demultiplexing using `kqueue` is performed in one of the threads that calls
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
-
-
-[heading AIX]
-
-Demultiplexing mechanism:
-
-* Uses `select` for demultiplexing. This means that the number of file
-descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
-
-Threads:
-
-* Demultiplexing using `select` is performed in one of the threads that calls
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
-
-
-[heading HP-UX]
-
-Demultiplexing mechanism:
-
-* Uses `select` for demultiplexing. This means that the number of file
-descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
-
-Threads:
-
-* Demultiplexing using `select` is performed in one of the threads that calls
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
-
-
-[heading Tru64]
-
-Demultiplexing mechanism:
-
-* Uses `select` for demultiplexing. This means that the number of file
-descriptors in the process cannot be permitted to exceed `FD_SETSIZE`.
-
-Threads:
-
-* Demultiplexing using `select` is performed in one of the threads that calls
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* At most `min(64,IOV_MAX)` buffers may be transferred in a single operation.
-
-
-[heading Windows 95, 98 and Me]
-
-Demultiplexing mechanism:
-
-* Uses `select` for demultiplexing.
-
-Threads:
-
-* Demultiplexing using `select` is performed in one of the threads that calls
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* For sockets, at most 16 buffers may be transferred in a single operation.
-
-
-[heading Windows NT, 2000, XP, 2003, Vista, 7 and 8]
-
-Demultiplexing mechanism:
-
-* Uses overlapped I/O and I/O completion ports for all asynchronous socket
-operations except for asynchronous connect.
-
-* Uses `select` for emulating asynchronous connect.
-
-Threads:
-
-* Demultiplexing using I/O completion ports is performed in all threads that call
-`io_context::run()`, `io_context::run_one()`, `io_context::poll()` or
-`io_context::poll_one()`.
-
-* An additional thread per `io_context` is used to trigger timers. This thread
-is created on construction of the first `basic_deadline_timer` or
-`basic_waitable_timer` objects.
-
-* An additional thread per `io_context` is used for the `select`
-demultiplexing. This thread is created on the first call to `async_connect()`.
-
-* An additional thread per `io_context` is used to emulate asynchronous host
-resolution. This thread is created on the first call to either
-`ip::tcp::resolver::async_resolve()` or `ip::udp::resolver::async_resolve()`.
-
-Scatter-Gather:
-
-* For sockets, at most 64 buffers may be transferred in a single operation.
-
-* For stream-oriented handles, only one buffer may be transferred in a single
-operation.
-
-[heading Windows Runtime]
-
-Asio provides limited support for the Windows Runtime. It requires that the
-language extensions be enabled. Due to the restricted facilities exposed by the
-Windows Runtime API, the support comes with the following caveats:
-
-* The core facilities such as the `io_context`, `strand`, buffers, composed
-  operations, timers, etc., should all work as normal.
-
-* For sockets, only client-side TCP is supported.
-
-* Explicit binding of a client-side TCP socket is not supported.
-
-* The `cancel()` function is not supported for sockets. Asynchronous
-  operations may only be cancelled by closing the socket.
-
-* Operations that use `null_buffers` are not supported.
-
-* Only `tcp::no_delay` and `socket_base::keep_alive` options are supported.
-
-* Resolvers do not support service names, only numbers. I.e. you must
-  use "80" rather than "http".
-
-* Most resolver query flags have no effect.
-
-Demultiplexing mechanism:
-
-* Uses the `Windows::Networking::Sockets::StreamSocket` class to implement
-  asynchronous TCP socket operations.
-
-Threads:
-
-* Event completions are delivered to the Windows thread pool and posted to the
-  `io_context` for the handler to be executed.
-
-* An additional thread per `io_context` is used to trigger timers. This thread
-  is created on construction of the first timer objects.
-
-Scatter-Gather:
-
-* For sockets, at most one buffer may be transferred in a single operation.
-
-
-[endsect]