Zen

Translation

type: paragraph
The type of the function's return value is determined by the [@boost:/doc/html/boost_asio/reference/async_result.html `net::async_result`] customization point, which comes with specializations for common library types such as `std::future` and may also be specialized for user-defined types. The body of the initiating function calls the [@boost:/doc/html/boost_asio/reference/async_initiate.html `net::async_initiate`] helper to capture the arguments and forward them to the specialization of `async_result`. An additional "initiation function" object is provided which `async_result` may use to immediately launch the operation, or defer the launch of the operation until some point in the future (this is called "lazy execution"). The initiation function object receives the internal completion handler which matches the signature expected by the initiating function:
870/8700 · 870

Sign in to save translations.

English Chinese (Simplified Han script) Actions
The function [@boost:/doc/html/boost_asio/reference/bind_allocator.html `net::bind_allocator`] can be used when the caller wants to assign a custom allocator to the operation.
The function [@boost:/doc/html/boost_asio/reference/bind_allocator.html `net::bind_allocator`] can be used when the caller wants to assign a custom allocator to the operation.
A completion token's associated cancellation_slot can be used to cancel single operations. This is often passed through by the completion token such as [@boost:/doc/html/boost_asio/reference/use_awaitable.html `net::use_awaitable`] or [@boost:/doc/html/boost_asio/reference/yield_context.html `net::yield_context`] .
A completion token's associated cancellation_slot can be used to cancel single operations. This is often passed through by the completion token such as [@boost:/doc/html/boost_asio/reference/use_awaitable.html `net::use_awaitable`] or [@boost:/doc/html/boost_asio/reference/yield_context.html `net::yield_context`] .
The available [@boost:/doc/html/boost_asio/reference/cancellation_type.html cancellation types] are listed below.
The available [@boost:/doc/html/boost_asio/reference/cancellation_type.html cancellation types] are listed below.
# `terminal`
# `terminal`
# `partial`
# `partial`
# `total`
# `total`
Networking prescribes facilities to determine the context in which handlers run. Every I/O object refers to an __ExecutionContext__ for obtaining the __Executor__ instance used to invoke completion handlers. An executor determines where and how completion handlers are invoked. Executors obtained from an instance of __io_context__ offer a basic guarantee: handlers will only be invoked from threads which are currently calling [@boost:/doc/html/boost_asio/reference/io_context/run/overload1.html `net::io_context::run`].
Networking prescribes facilities to determine the context in which handlers run. Every I/O object refers to an __ExecutionContext__ for obtaining the __Executor__ instance used to invoke completion handlers. An executor determines where and how completion handlers are invoked. Executors obtained from an instance of __io_context__ offer a basic guarantee: handlers will only be invoked from threads which are currently calling [@boost:/doc/html/boost_asio/reference/io_context/run/overload1.html `net::io_context::run`].
The __AsyncReadStream__ and __AsyncWriteStream__ concepts define requirements for ['asynchronous streams]: a portable I/O abstraction that exchanges data asynchronously using buffer sequences to represent bytes and `error_code` to report any failures. An ['asynchronous stream algorithm] is written as a templated initiating function template accepting a stream object meeting the named requirements for asynchronous reading, writing, or both. This example shows an algorithm which writes some text to an asynchronous stream:
The __AsyncReadStream__ and __AsyncWriteStream__ concepts define requirements for ['asynchronous streams]: a portable I/O abstraction that exchanges data asynchronously using buffer sequences to represent bytes and `error_code` to report any failures. An ['asynchronous stream algorithm] is written as a templated initiating function template accepting a stream object meeting the named requirements for asynchronous reading, writing, or both. This example shows an algorithm which writes some text to an asynchronous stream:
Concurrency
Concurrency
I/O objects such as sockets and streams [*are not thread-safe]. Although it is possible to have more than one operation outstanding (for example, a simultaneous asynchronous read and asynchronous write) the stream object itself may only be accessed from one thread at a time. This means that member functions such as move constructors, destructors, or initiating functions must not be called concurrently. Usually this is accomplished with synchronization primitives such as a [@https://en.cppreference.com/w/cpp/thread/mutex `mutex`], but concurrent network programs need a better way to access shared resources, since acquiring ownership of a mutex could block threads from performing uncontended work. For efficiency, networking adopts a model of using threads without explicit locking by requiring all access to I/O objects to be performed within a [@boost:/doc/html/boost_asio/overview/core/strands.html ['strand]].
I/O objects such as sockets and streams [*are not thread-safe]. Although it is possible to have more than one operation outstanding (for example, a simultaneous asynchronous read and asynchronous write) the stream object itself may only be accessed from one thread at a time. This means that member functions such as move constructors, destructors, or initiating functions must not be called concurrently. Usually this is accomplished with synchronization primitives such as a [@https://en.cppreference.com/w/cpp/thread/mutex `mutex`], but concurrent network programs need a better way to access shared resources, since acquiring ownership of a mutex could block threads from performing uncontended work. For efficiency, networking adopts a model of using threads without explicit locking by requiring all access to I/O objects to be performed within a [@boost:/doc/html/boost_asio/overview/core/strands.html ['strand]].
Universal Model
Universal Model
Because completion handlers cause an inversion of the flow of control, sometimes other methods of attaching a continuation are desired. Networking provides the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf ['Universal Model for Asynchronous Operations]], providing a customizable means for transforming the signature of the initiating function to use other types of objects and methods in place of a completion handler callback. For example to call to write a string to a socket asynchronously, using a `std::future` to receive the number of bytes transferred thus looks like this:
Because completion handlers cause an inversion of the flow of control, sometimes other methods of attaching a continuation are desired. Networking provides the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf ['Universal Model for Asynchronous Operations]], providing a customizable means for transforming the signature of the initiating function to use other types of objects and methods in place of a completion handler callback. For example to call to write a string to a socket asynchronously, using a `std::future` to receive the number of bytes transferred thus looks like this:
This functionality is enabled by passing the variable [@boost:/doc/html/boost_asio/reference/use_future.html `net::use_future`] (of type [@boost:/doc/html/boost_asio/reference/use_future_t.html `net::use_future_t<>`]) in place of the completion handler. The same `async_write` function overload can work with a [@https://en.wikipedia.org/wiki/Fiber_(computer_science) ['fiber]] launched with [@boost:/doc/html/boost_asio/reference/spawn/overload1.html `asio::spawn`]:
This functionality is enabled by passing the variable [@boost:/doc/html/boost_asio/reference/use_future.html `net::use_future`] (of type [@boost:/doc/html/boost_asio/reference/use_future_t.html `net::use_future_t<>`]) in place of the completion handler. The same `async_write` function overload can work with a [@https://en.wikipedia.org/wiki/Fiber_(computer_science) ['fiber]] launched with [@boost:/doc/html/boost_asio/reference/spawn/overload1.html `asio::spawn`]:
In both of these cases, an object with a specific type is used in place of the completion handler, and the return value of the initiating function is transformed from `void` to `std::future<std::size_t>` or `std::size_t`. The handler is sometimes called a __CompletionToken__ when used in this context. The return type transformation is supported by customization points in the initiating function signature. Here is the signature for [@boost:/doc/html/boost_asio/reference/async_write/overload1.html `net::async_write`]:
In both of these cases, an object with a specific type is used in place of the completion handler, and the return value of the initiating function is transformed from `void` to `std::future<std::size_t>` or `std::size_t`. The handler is sometimes called a __CompletionToken__ when used in this context. The return type transformation is supported by customization points in the initiating function signature. Here is the signature for [@boost:/doc/html/boost_asio/reference/async_write/overload1.html `net::async_write`]:
Note that a `spawn` function itself has a completion signature, but we're ignoring it's result in the example by using `asio::detached`.
Note that a `spawn` function itself has a completion signature, but we're ignoring it's result in the example by using `asio::detached`.
The type of the function's return value is determined by the [@boost:/doc/html/boost_asio/reference/async_result.html `net::async_result`] customization point, which comes with specializations for common library types such as `std::future` and may also be specialized for user-defined types. The body of the initiating function calls the [@boost:/doc/html/boost_asio/reference/async_initiate.html `net::async_initiate`] helper to capture the arguments and forward them to the specialization of `async_result`. An additional "initiation function" object is provided which `async_result` may use to immediately launch the operation, or defer the launch of the operation until some point in the future (this is called "lazy execution"). The initiation function object receives the internal completion handler which matches the signature expected by the initiating function:
The type of the function's return value is determined by the [@boost:/doc/html/boost_asio/reference/async_result.html `net::async_result`] customization point, which comes with specializations for common library types such as `std::future` and may also be specialized for user-defined types. The body of the initiating function calls the [@boost:/doc/html/boost_asio/reference/async_initiate.html `net::async_initiate`] helper to capture the arguments and forward them to the specialization of `async_result`. An additional "initiation function" object is provided which `async_result` may use to immediately launch the operation, or defer the launch of the operation until some point in the future (this is called "lazy execution"). The initiation function object receives the internal completion handler which matches the signature expected by the initiating function:
This transformed, internal handler is responsible for the finalizing step that delivers the result of the operation to the caller. For example, when using `net::use_future` the internal handler will deliver the result by calling [@https://en.cppreference.com/w/cpp/thread/promise/set_value `std::promise::set_value`] on the promise object returned by the initiating function.
This transformed, internal handler is responsible for the finalizing step that delivers the result of the operation to the caller. For example, when using `net::use_future` the internal handler will deliver the result by calling [@https://en.cppreference.com/w/cpp/thread/promise/set_value `std::promise::set_value`] on the promise object returned by the initiating function.
Using Networking
Using Networking
Most library stream algorithms require a __socket__, __ssl_stream__, or other __Stream__ object that has already established communication with a remote peer. This example is provided as a reminder of how to work with sockets:
Most library stream algorithms require a __socket__, __ssl_stream__, or other __Stream__ object that has already established communication with a remote peer. This example is provided as a reminder of how to work with sockets:
Throughout this documentation identifiers with the following names have special meaning:
Throughout this documentation identifiers with the following names have special meaning:
Global Variables
Global Variables
Name
Name
Description
Description
[@boost:/doc/html/boost_asio/reference/io_context.html [*`ioc`]]
[@boost:/doc/html/boost_asio/reference/io_context.html [*`ioc`]]
A variable of type __io_context__ which is running on one separate thread, and upon which an __executor_work_guard__ object has been constructed.
A variable of type __io_context__ which is running on one separate thread, and upon which an __executor_work_guard__ object has been constructed.
[@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html [*`sock`]]
[@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html [*`sock`]]
A variable of type [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `tcp::socket`] which has already been connected to a remote host.
A variable of type [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html `tcp::socket`] which has already been connected to a remote host.
[@boost:/doc/html/boost_asio/reference/ssl__stream.html [*`ssl_sock`]]
[@boost:/doc/html/boost_asio/reference/ssl__stream.html [*`ssl_sock`]]
A variable of type [@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream<tcp::socket>`] which is already connected and has handshaked with a remote host.
A variable of type [@boost:/doc/html/boost_asio/reference/ssl__stream.html `net::ssl::stream<tcp::socket>`] which is already connected and has handshaked with a remote host.
[link beast.ref.boost__beast__websocket__stream [*`ws`]]
[link beast.ref.boost__beast__websocket__stream [*`ws`]]
A variable of type [link beast.ref.boost__beast__websocket__stream `websocket::stream<tcp::socket>`] which is already connected with a remote host.
A variable of type [link beast.ref.boost__beast__websocket__stream `websocket::stream<tcp::socket>`] which is already connected with a remote host.
English Chinese (Simplified Han script) Actions
An asynchronous operation begins with a call to an [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html ['initiating function]], which starts the operation and returns to the caller immediately. This ['outstanding] asynchronous operation proceeds concurrently without blocking the caller. When the externally observable side effects are fully established, a movable function object known as a [@boost:/doc/html/boost_asio/reference/CompletionHandler.html ['completion handler]] provided in the initiating function call is queued for execution with the results, which may include the error code and other specific information. An asynchronous operation is said to be ['completed] after the completion handler is queued. The code that follows shows how some text may be written to a socket asynchronously, invoking a lambda when the operation is complete:
An asynchronous operation begins with a call to an [@boost:/doc/html/boost_asio/reference/asynchronous_operations.html ['initiating function]], which starts the operation and returns to the caller immediately. This ['outstanding] asynchronous operation proceeds concurrently without blocking the caller. When the externally observable side effects are fully established, a movable function object known as a [@boost:/doc/html/boost_asio/reference/CompletionHandler.html ['completion handler]] provided in the initiating function call is queued for execution with the results, which may include the error code and other specific information. An asynchronous operation is said to be ['completed] after the completion handler is queued. The code that follows shows how some text may be written to a socket asynchronously, invoking a lambda when the operation is complete:
Every completion handler (also referred to as a [@https://en.wikipedia.org/wiki/Continuation ['continuation]]) has both an [@boost:/doc/html/boost_asio/overview/core/allocation.html ['associated allocator]] returned by [@boost:/doc/html/boost_asio/reference/get_associated_allocator.html `net::get_associated_allocator`], , an [@boost:/doc/html/boost_asio/reference/associated_cancellation_slot.html ['associated cancellation slot]] returned by [@boost:/doc/html/boost_asio/reference/associated_cancellation_slot.html `net::get_associated_cancellation_slot`]. and an [@boost:/doc/html/boost_asio/reference/associated_executor.html ['associated executor]] returned by [@boost:/doc/html/boost_asio/reference/get_associated_executor.html `net::get_associated_executor`]. These associations may be specified intrusively:
Every completion handler (also referred to as a [@https://en.wikipedia.org/wiki/Continuation ['continuation]]) has both an [@boost:/doc/html/boost_asio/overview/core/allocation.html ['associated allocator]] returned by [@boost:/doc/html/boost_asio/reference/get_associated_allocator.html `net::get_associated_allocator`], , an [@boost:/doc/html/boost_asio/reference/associated_cancellation_slot.html ['associated cancellation slot]] returned by [@boost:/doc/html/boost_asio/reference/associated_cancellation_slot.html `net::get_associated_cancellation_slot`]. and an [@boost:/doc/html/boost_asio/reference/associated_executor.html ['associated executor]] returned by [@boost:/doc/html/boost_asio/reference/get_associated_executor.html `net::get_associated_executor`]. These associations may be specified intrusively:
Or these associations may be specified non-intrusively, by specializing the class templates [@boost:/doc/html/boost_asio/reference/associated_allocator.html `net::associated_allocator`] , [@boost:/doc/html/boost_asio/reference/associated_cancellation_slot.html `net::associated_cancellation_slot`] and [@boost:/doc/html/boost_asio/reference/associated_executor.html `net::associated_executor`]:
Or these associations may be specified non-intrusively, by specializing the class templates [@boost:/doc/html/boost_asio/reference/associated_allocator.html `net::associated_allocator`] , [@boost:/doc/html/boost_asio/reference/associated_cancellation_slot.html `net::associated_cancellation_slot`] and [@boost:/doc/html/boost_asio/reference/associated_executor.html `net::associated_executor`]:
The function [@boost:/doc/html/boost_asio/reference/bind_executor.html `net::bind_executor`] may be used when the caller wants to change the executor of a completion handler.
The function [@boost:/doc/html/boost_asio/reference/bind_executor.html `net::bind_executor`] may be used when the caller wants to change the executor of a completion handler.
The allocator is used by the implementation to obtain any temporary storage necessary to perform the operation. Temporary allocations are always freed before the completion handler is invoked. The executor is a cheaply copyable object providing the algorithm used to invoke the completion handler. Unless customized by the caller, a completion handler defaults to using `std::allocator<void>` and the executor of the corresponding I/O object.
The allocator is used by the implementation to obtain any temporary storage necessary to perform the operation. Temporary allocations are always freed before the completion handler is invoked. The executor is a cheaply copyable object providing the algorithm used to invoke the completion handler. Unless customized by the caller, a completion handler defaults to using `std::allocator<void>` and the executor of the corresponding I/O object.
The function [@boost:/doc/html/boost_asio/reference/bind_allocator.html `net::bind_allocator`] can be used when the caller wants to assign a custom allocator to the operation.
The function [@boost:/doc/html/boost_asio/reference/bind_allocator.html `net::bind_allocator`] can be used when the caller wants to assign a custom allocator to the operation.
A completion token's associated cancellation_slot can be used to cancel single operations. This is often passed through by the completion token such as [@boost:/doc/html/boost_asio/reference/use_awaitable.html `net::use_awaitable`] or [@boost:/doc/html/boost_asio/reference/yield_context.html `net::yield_context`] .
A completion token's associated cancellation_slot can be used to cancel single operations. This is often passed through by the completion token such as [@boost:/doc/html/boost_asio/reference/use_awaitable.html `net::use_awaitable`] or [@boost:/doc/html/boost_asio/reference/yield_context.html `net::yield_context`] .
The available [@boost:/doc/html/boost_asio/reference/cancellation_type.html cancellation types] are listed below.
The available [@boost:/doc/html/boost_asio/reference/cancellation_type.html cancellation types] are listed below.
# `terminal`
# `terminal`
I/O objects such as sockets and streams [*are not thread-safe]. Although it is possible to have more than one operation outstanding (for example, a simultaneous asynchronous read and asynchronous write) the stream object itself may only be accessed from one thread at a time. This means that member functions such as move constructors, destructors, or initiating functions must not be called concurrently. Usually this is accomplished with synchronization primitives such as a [@https://en.cppreference.com/w/cpp/thread/mutex `mutex`], but concurrent network programs need a better way to access shared resources, since acquiring ownership of a mutex could block threads from performing uncontended work. For efficiency, networking adopts a model of using threads without explicit locking by requiring all access to I/O objects to be performed within a [@boost:/doc/html/boost_asio/overview/core/strands.html ['strand]].
I/O objects such as sockets and streams [*are not thread-safe]. Although it is possible to have more than one operation outstanding (for example, a simultaneous asynchronous read and asynchronous write) the stream object itself may only be accessed from one thread at a time. This means that member functions such as move constructors, destructors, or initiating functions must not be called concurrently. Usually this is accomplished with synchronization primitives such as a [@https://en.cppreference.com/w/cpp/thread/mutex `mutex`], but concurrent network programs need a better way to access shared resources, since acquiring ownership of a mutex could block threads from performing uncontended work. For efficiency, networking adopts a model of using threads without explicit locking by requiring all access to I/O objects to be performed within a [@boost:/doc/html/boost_asio/overview/core/strands.html ['strand]].
Universal Model
Universal Model
Because completion handlers cause an inversion of the flow of control, sometimes other methods of attaching a continuation are desired. Networking provides the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf ['Universal Model for Asynchronous Operations]], providing a customizable means for transforming the signature of the initiating function to use other types of objects and methods in place of a completion handler callback. For example to call to write a string to a socket asynchronously, using a `std::future` to receive the number of bytes transferred thus looks like this:
Because completion handlers cause an inversion of the flow of control, sometimes other methods of attaching a continuation are desired. Networking provides the [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf ['Universal Model for Asynchronous Operations]], providing a customizable means for transforming the signature of the initiating function to use other types of objects and methods in place of a completion handler callback. For example to call to write a string to a socket asynchronously, using a `std::future` to receive the number of bytes transferred thus looks like this:
This functionality is enabled by passing the variable [@boost:/doc/html/boost_asio/reference/use_future.html `net::use_future`] (of type [@boost:/doc/html/boost_asio/reference/use_future_t.html `net::use_future_t<>`]) in place of the completion handler. The same `async_write` function overload can work with a [@https://en.wikipedia.org/wiki/Fiber_(computer_science) ['fiber]] launched with [@boost:/doc/html/boost_asio/reference/spawn/overload1.html `asio::spawn`]:
This functionality is enabled by passing the variable [@boost:/doc/html/boost_asio/reference/use_future.html `net::use_future`] (of type [@boost:/doc/html/boost_asio/reference/use_future_t.html `net::use_future_t<>`]) in place of the completion handler. The same `async_write` function overload can work with a [@https://en.wikipedia.org/wiki/Fiber_(computer_science) ['fiber]] launched with [@boost:/doc/html/boost_asio/reference/spawn/overload1.html `asio::spawn`]:
In both of these cases, an object with a specific type is used in place of the completion handler, and the return value of the initiating function is transformed from `void` to `std::future<std::size_t>` or `std::size_t`. The handler is sometimes called a __CompletionToken__ when used in this context. The return type transformation is supported by customization points in the initiating function signature. Here is the signature for [@boost:/doc/html/boost_asio/reference/async_write/overload1.html `net::async_write`]:
In both of these cases, an object with a specific type is used in place of the completion handler, and the return value of the initiating function is transformed from `void` to `std::future<std::size_t>` or `std::size_t`. The handler is sometimes called a __CompletionToken__ when used in this context. The return type transformation is supported by customization points in the initiating function signature. Here is the signature for [@boost:/doc/html/boost_asio/reference/async_write/overload1.html `net::async_write`]:
Note that a `spawn` function itself has a completion signature, but we're ignoring it's result in the example by using `asio::detached`.
Note that a `spawn` function itself has a completion signature, but we're ignoring it's result in the example by using `asio::detached`.
The type of the function's return value is determined by the [@boost:/doc/html/boost_asio/reference/async_result.html `net::async_result`] customization point, which comes with specializations for common library types such as `std::future` and may also be specialized for user-defined types. The body of the initiating function calls the [@boost:/doc/html/boost_asio/reference/async_initiate.html `net::async_initiate`] helper to capture the arguments and forward them to the specialization of `async_result`. An additional "initiation function" object is provided which `async_result` may use to immediately launch the operation, or defer the launch of the operation until some point in the future (this is called "lazy execution"). The initiation function object receives the internal completion handler which matches the signature expected by the initiating function:
The type of the function's return value is determined by the [@boost:/doc/html/boost_asio/reference/async_result.html `net::async_result`] customization point, which comes with specializations for common library types such as `std::future` and may also be specialized for user-defined types. The body of the initiating function calls the [@boost:/doc/html/boost_asio/reference/async_initiate.html `net::async_initiate`] helper to capture the arguments and forward them to the specialization of `async_result`. An additional "initiation function" object is provided which `async_result` may use to immediately launch the operation, or defer the launch of the operation until some point in the future (this is called "lazy execution"). The initiation function object receives the internal completion handler which matches the signature expected by the initiating function:

Loading…

User avatar admin

String added in the repository
The type of the function's return value is determined by the [@boost:/doc/html/boost_asio/reference/async_result.html `net::async_result`] customization point, which comes with specializations for common library types such as `std::future` and may also be specialized for user-defined types. The body of the initiating function calls the [@boost:/doc/html/boost_asio/reference/async_initiate.html `net::async_initiate`] helper to capture the arguments and forward them to the specialization of `async_result`. An additional "initiation function" object is provided which `async_result` may use to immediately launch the operation, or defer the launch of the operation until some point in the future (this is called "lazy execution"). The initiation function object receives the internal completion handler which matches the signature expected by the initiating function:
The type of the function's return value is determined by the [@boost:/doc/html/boost_asio/reference/async_result.html `net::async_result`] customization point, which comes with specializations for common library types such as `std::future` and may also be specialized for user-defined types. The body of the initiating function calls the [@boost:/doc/html/boost_asio/reference/async_initiate.html `net::async_initiate`] helper to capture the arguments and forward them to the specialization of `async_result`. An additional "initiation function" object is provided which `async_result` may use to immediately launch the operation, or defer the launch of the operation until some point in the future (this is called "lazy execution"). The initiation function object receives the internal completion handler which matches the signature expected by the initiating function:
06/05/2026
Browse all string changes

Things to check

Unchanged translation

Source and translation are identical.

Reset

Glossary

English Chinese (Simplified Han script)
No related strings found in the glossary.

String information

Source string description
type: paragraph
Unit identifier
58057
Source string location
string ID 348
String age
06/05/2026
Last updated
06/05/2026
Source string age
06/05/2026
Translation file QuickBook file
doc/qbk/03_core/1_refresher_zh_Hans.qbk, string 38