summaryrefslogtreecommitdiffstatshomepage
path: root/3rdparty/asio/src/doc/overview/basics.qbk
diff options
context:
space:
mode:
Diffstat (limited to '3rdparty/asio/src/doc/overview/basics.qbk')
-rw-r--r--3rdparty/asio/src/doc/overview/basics.qbk106
1 files changed, 0 insertions, 106 deletions
diff --git a/3rdparty/asio/src/doc/overview/basics.qbk b/3rdparty/asio/src/doc/overview/basics.qbk
deleted file mode 100644
index c867563840a..00000000000
--- a/3rdparty/asio/src/doc/overview/basics.qbk
+++ /dev/null
@@ -1,106 +0,0 @@
-[/
- / Copyright (c) 2003-2016 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:basics Basic Asio Anatomy]
-
-Asio may be used to perform both synchronous and asynchronous operations on I/O
-objects such as sockets. Before using Asio it may be useful to get a conceptual
-picture of the various parts of Asio, your program, and how they work together.
-
-As an introductory example, let's consider what happens when you perform a
-connect operation on a socket. We shall start by examining synchronous
-operations.
-
-[$sync_op.png]
-
-[*Your program] will have at least one [*io_context] object. The [*io_context]
-represents [*your program]'s link to the [*operating system]'s I/O services.
-
- asio::io_context io_context;
-
-To perform I/O operations [*your program] will need an [*I/O object] such as a
-TCP socket:
-
- asio::ip::tcp::socket socket(io_context);
-
-When a synchronous connect operation is performed, the following sequence of
-events occurs:
-
-1. [*Your program] initiates the connect operation by calling the [*I/O
-object]:
-
- socket.connect(server_endpoint);
-
-2. The [*I/O object] forwards the request to the [*io_context].
-
-3. The [*io_context] calls on the [*operating system] to perform the connect
-operation.
-
-4. The [*operating system] returns the result of the operation to the
-[*io_context].
-
-5. The [*io_context] translates any error resulting from the operation into an
-object of type `asio::error_code`. An `error_code` may be compared with
-specific values, or tested as a boolean (where a `false` result means that no
-error occurred). The result is then forwarded back up to the [*I/O object].
-
-6. The [*I/O object] throws an exception of type `asio::system_error` if the
-operation failed. If the code to initiate the operation had instead been
-written as:
-
- asio::error_code ec;
- socket.connect(server_endpoint, ec);
-
-then the `error_code` variable `ec` would be set to the result of the
-operation, and no exception would be thrown.
-
-When an asynchronous operation is used, a different sequence of events occurs.
-
-[$async_op1.png]
-
-1. [*Your program] initiates the connect operation by calling the [*I/O
-object]:
-
- socket.async_connect(server_endpoint, your_completion_handler);
-
-where `your_completion_handler` is a function or function object with the
-signature:
-
- void your_completion_handler(const asio::error_code& ec);
-
-The exact signature required depends on the asynchronous operation being
-performed. The reference documentation indicates the appropriate form for each
-operation.
-
-2. The [*I/O object] forwards the request to the [*io_context].
-
-3. The [*io_context] signals to the [*operating system] that it should start an
-asynchronous connect.
-
-Time passes. (In the synchronous case this wait would have been contained
-entirely within the duration of the connect operation.)
-
-[$async_op2.png]
-
-4. The [*operating system] indicates that the connect operation has completed
-by placing the result on a queue, ready to be picked up by the [*io_context].
-
-5. [*Your program] must make a call to `io_context::run()` (or to one of the
-similar [*io_context] member functions) in order for the result to be
-retrieved. A call to `io_context::run()` blocks while there are unfinished
-asynchronous operations, so you would typically call it as soon as you have
-started your first asynchronous operation.
-
-6. While inside the call to `io_context::run()`, the [*io_context] dequeues the
-result of the operation, translates it into an `error_code`, and then passes it
-to [*your completion handler].
-
-This is a simplified picture of how Asio operates. You will want to delve
-further into the documentation if your needs are more advanced, such as
-extending Asio to perform other types of asynchronous operations.
-
-[endsect]