1[/
2 / Copyright (c) 2003-2021 Christopher M. Kohlhoff (chris at kohlhoff dot com)
3 /
4 / Distributed under the Boost Software License, Version 1.0. (See accompanying
5 / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
6 /]
7
8[section:basics Basic Boost.Asio Anatomy]
9
10Boost.Asio may be used to perform both synchronous and asynchronous operations on I/O
11objects such as sockets. Before using Boost.Asio it may be useful to get a conceptual
12picture of the various parts of Boost.Asio, your program, and how they work together.
13
14As an introductory example, let's consider what happens when you perform a
15connect operation on a socket. We shall start by examining synchronous
16operations.
17
18[$boost_asio/sync_op.png]
19
20[*Your program] will have at least one [*I/O execution context], such as an
21`boost::asio::io_context` object, `boost::asio::thread_pool` object, or
22`boost::asio::system_context`. This [*I/O execution context] represents [*your
23program]'s link to the [*operating system]'s I/O services.
24
25  boost::asio::io_context io_context;
26
27To perform I/O operations [*your program] will need an [*I/O object] such as a
28TCP socket:
29
30  boost::asio::ip::tcp::socket socket(io_context);
31
32When a synchronous connect operation is performed, the following sequence of
33events occurs:
34
351. [*Your program] initiates the connect operation by calling the [*I/O
36object]:
37
38  socket.connect(server_endpoint);
39
402. The [*I/O object] forwards the request to the [*I/O execution context].
41
423. The [*I/O execution context] calls on the [*operating system] to perform the
43connect operation.
44
454. The [*operating system] returns the result of the operation to the
46[*I/O execution context].
47
485. The [*I/O execution context] translates any error resulting from the
49operation into an object of type `boost::system::error_code`. An `error_code` may be
50compared with specific values, or tested as a boolean (where a `false` result
51means that no error occurred). The result is then forwarded back up to the
52[*I/O object].
53
546. The [*I/O object] throws an exception of type `boost::system::system_error` if the
55operation failed. If the code to initiate the operation had instead been
56written as:
57
58  boost::system::error_code ec;
59  socket.connect(server_endpoint, ec);
60
61then the `error_code` variable `ec` would be set to the result of the
62operation, and no exception would be thrown.
63
64When an asynchronous operation is used, a different sequence of events occurs.
65
66[$boost_asio/async_op1.png]
67
681. [*Your program] initiates the connect operation by calling the [*I/O
69object]:
70
71  socket.async_connect(server_endpoint, your_completion_handler);
72
73where `your_completion_handler` is a function or function object with the
74signature:
75
76  void your_completion_handler(const boost::system::error_code& ec);
77
78The exact signature required depends on the asynchronous operation being
79performed. The reference documentation indicates the appropriate form for each
80operation.
81
822. The [*I/O object] forwards the request to the [*I/O execution context].
83
843. The [*I/O execution context] signals to the [*operating system] that it
85should start an asynchronous connect.
86
87Time passes. (In the synchronous case this wait would have been contained
88entirely within the duration of the connect operation.)
89
90[$boost_asio/async_op2.png]
91
924. The [*operating system] indicates that the connect operation has completed
93by placing the result on a queue, ready to be picked up by the [*I/O execution
94context].
95
965. When using an `io_context` as the [*I/O execution context], [*your program]
97must make a call to `io_context::run()` (or to one of the similar `io_context`
98member functions) in order for the result to be retrieved. A call to
99`io_context::run()` blocks while there are unfinished asynchronous operations,
100so you would typically call it as soon as you have started your first
101asynchronous operation.
102
1036. While inside the call to `io_context::run()`, the [*I/O execution context]
104dequeues the result of the operation, translates it into an `error_code`, and
105then passes it to [*your completion handler].
106
107This is a simplified picture of how Boost.Asio operates. You will want to delve
108further into the documentation if your needs are more advanced, such as
109extending Boost.Asio to perform other types of asynchronous operations.
110
111[endsect]
112