Exit Zen
7
string ID 65
type: heading
English
Buffers
7/100 · 7
8
string ID 67
type: paragraph
English
A [@https://en.wikipedia.org/wiki/Data_buffer ['buffer]] holds a contiguous sequence of bytes used when performing I/O. The types [@boost:/doc/html/boost_asio/reference/const_buffer.html `net::const_buffer`] and [@boost:/doc/html/boost_asio/reference/mutable_buffer.html `net::mutable_buffer`] represent these memory regions as type-safe pointer/size pairs:
357/3570 · 357
9
string ID 79
type: paragraph
English
`const_buffer` and `mutable_buffer` are preferred over `std::span<byte>`
72/720 · 72
10
string ID 92
type: paragraph
English
The concepts __ConstBufferSequence__ and __MutableBufferSequence__ describe bidirectional ranges whose value type is convertible to `const_buffer` and `mutable_buffer` respectively. These sequences allow transacting with multiple buffers in a single function call, a technique called [@https://en.wikipedia.org/wiki/Vectored_I/O ['scatter/gather I/O]]. Buffers and buffer sequences are non-owning; copies produce shallow references and not duplicates of the underlying memory. Each of these statements declares a buffer sequence:
529/5290 · 529
11
string ID 104
type: paragraph
English
The functions [@boost:/doc/html/boost_asio/reference/buffer_size.html `net::buffer_size`] and [@boost:/doc/html/boost_asio/reference/buffer_copy.html `net::buffer_copy`] determine the total number of bytes in a buffer sequence, and transfer some or all of bytes from one buffer sequence to another respectively. The function `buffer_size` is a customization point: user defined overloads in foreign namespaces are possible, and callers should invoke `buffer_size` without namespace qualification. The functions [@boost:/doc/html/boost_asio/reference/buffer_sequence_begin.html `net::buffer_sequence_begin`] and [@boost:/doc/html/boost_asio/reference/buffer_sequence_end.html `net::buffer_sequence_end`] are used to obtain a pair of iterators for traversing the sequence. Beast provides a set of buffer sequence types and algorithms such as [link beast.ref.boost__beast__buffers_cat `buffers_cat`], [link beast.ref.boost__beast__buffers_front `buffers_front`], [link beast.ref.boost__beast__buffers_prefix `buffers_prefix`], [link beast.ref.boost__beast__buffers_range `buffers_range`], and [link beast.ref.boost__beast__buffers_suffix `buffers_suffix`]. This example returns the bytes in a buffer sequence as a string:
1218/12180 · 1218
12
string ID 125
type: paragraph
English
The __DynamicBuffer__ concept defines a resizable buffer sequence interface. Algorithms may be expressed in terms of dynamic buffers when the memory requirements are not known ahead of time, for example when reading an HTTP message from a stream. Beast provides a well-rounded collection of dynamic buffer types such as [link beast.ref.boost__beast__buffers_adaptor `buffers_adaptor`], [link beast.ref.boost__beast__flat_buffer `flat_buffer`], [link beast.ref.boost__beast__multi_buffer `multi_buffer`], and [link beast.ref.boost__beast__static_buffer `static_buffer`]. The following function reads data from a [link beast.ref.boost__beast__tcp_stream `tcp_stream`] into a dynamic buffer until it encountering a newline character, using [@boost:/doc/html/boost_asio/reference/buffers_iterator.html `net::buffers_iterator`] to treat the contents of the buffer as a range of characters:
884/8840 · 884
13
string ID 146
type: heading
English
Synchronous I/O
15/150 · 15
14
string ID 148
type: paragraph
English
Synchronous input and output is accomplished through blocking function calls that return with the result of the operation. Such operations typically cannot be canceled and do not have a method for setting a timeout. The __SyncReadStream__ and __SyncWriteStream__ concepts define requirements for ['synchronous streams]: a portable I/O abstraction that transfers data using buffer sequences to represent bytes and either `error_code` or an exception to report any failures. [@boost:/doc/html/boost_asio/reference/basic_stream_socket.html ['net::basic_stream_socket]] is a synchronous stream commonly used to form TCP/IP connections. User-defined types which meet the requirements are possible:
692/6920 · 692
15
string ID 162
type: paragraph
English
A ['synchronous stream algorithm] is written as a function template accepting a stream object meeting the named requirements for synchronous reading, writing, or both. This example shows an algorithm which writes text and uses exceptions to indicate errors:
257/2570 · 257
16
string ID 170
type: paragraph
English
The same algorithm may be expressed using error codes instead of exceptions:
76/760 · 76
17
string ID 176
type: heading
English
Asynchronous I/O
16/160 · 16
18
string ID 178
type: paragraph
English
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:
868/8680 · 868
19
string ID 196
type: paragraph
English
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:
816/8160 · 816
20
string ID 214
type: paragraph
English
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`]:
394/3940 · 394
21
string ID 224
type: paragraph
English
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.
174/1740 · 174
22
string ID 229
type: paragraph
English
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.
442/4420 · 442
23
string ID 236
type: paragraph
English
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.
175/1750 · 175
24
string ID 241
type: paragraph
English
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`] .
316/3160 · 316
25
string ID 248
type: paragraph
English
The available [@boost:/doc/html/boost_asio/reference/cancellation_type.html cancellation types] are listed below.
113/1130 · 113
26
string ID 250
type: list
English
# `terminal`
12/120 · 12