msgid "" msgstr "" "Project-Id-Version: English (Boost Beast Translation (zh_Hans))\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2026-06-07 00:12+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: English \n" "Language: en\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=2; plural=n != 1;\n" "X-Generator: Weblate 2026.5\n" #. type: section title #: 10 #, read-only msgid "Refresher" msgstr "Refresher" #. type: paragraph #: 12 #, read-only msgid "" "To use Beast effectively, a prior understanding of Networking is required. " "This section reviews these concepts as a reminder and guide for further " "learning." msgstr "" "To use Beast effectively, a prior understanding of Networking is required. " "This section reviews these concepts as a reminder and guide for further " "learning." #. type: paragraph #: 16 #, read-only msgid "" "A [@https://en.wikipedia.org/wiki/Computer_network ['network]] allows " "programs located anywhere to exchange information after opting-in to " "communications by establishing a [@https://en.wikipedia.org/wiki/Data_link " "['connection]]. Data may be reliably transferred across a connection in both " "directions ([@https://en.wikipedia.org/wiki/Duplex_(telecommunications) " "['full-duplex]]) with bytes arriving in the same order they were sent. These " "connections, along with the objects and types used to represent them, are " "collectively termed [link beast.concepts.streams ['streams]]. The computer " "or device attached to the network is called a [@https://en.wikipedia.org/" "wiki/Host_(network) ['host]], and the program on the other end of an " "established connection is called a [@https://en.wikipedia.org/wiki/Peer-to-" "peer ['peer]]." msgstr "" "A [@https://en.wikipedia.org/wiki/Computer_network ['network]] allows " "programs located anywhere to exchange information after opting-in to " "communications by establishing a [@https://en.wikipedia.org/wiki/Data_link " "['connection]]. Data may be reliably transferred across a connection in both " "directions ([@https://en.wikipedia.org/wiki/Duplex_(telecommunications) " "['full-duplex]]) with bytes arriving in the same order they were sent. These " "connections, along with the objects and types used to represent them, are " "collectively termed [link beast.concepts.streams ['streams]]. The computer " "or device attached to the network is called a [@https://en.wikipedia.org/" "wiki/Host_(network) ['host]], and the program on the other end of an " "established connection is called a [@https://en.wikipedia.org/wiki/Peer-to-" "peer ['peer]]." #. type: paragraph #: 31 #, read-only msgid "" "The [@https://en.wikipedia.org/wiki/Internet ['internet]] is a global " "network of interconnected computers that use a variety of standardized " "communication protocols to exchange information. The most popular protocol " "is [@https://en.wikipedia.org/wiki/Transmission_Control_Protocol ['TCP/IP]], " "which this library relies on exclusively. The protocol takes care of the low " "level details so that applications see a ['stream], which is the reliable, " "full-duplex connection carrying the ordered set of bytes described above. A " "[@https://en.wikipedia.org/wiki/Server_(computing) ['server]] is a powerful, " "always-on host at a well-known network name or network address which " "provides data services. A [@https://en.wikipedia.org/wiki/Client_(computing) " "['client]] is a transient peer which connects to a server to exchange data, " "and goes offline." msgstr "" "The [@https://en.wikipedia.org/wiki/Internet ['internet]] is a global " "network of interconnected computers that use a variety of standardized " "communication protocols to exchange information. The most popular protocol " "is [@https://en.wikipedia.org/wiki/Transmission_Control_Protocol ['TCP/IP]], " "which this library relies on exclusively. The protocol takes care of the low " "level details so that applications see a ['stream], which is the reliable, " "full-duplex connection carrying the ordered set of bytes described above. A " "[@https://en.wikipedia.org/wiki/Server_(computing) ['server]] is a powerful, " "always-on host at a well-known network name or network address which " "provides data services. A [@https://en.wikipedia.org/wiki/Client_(computing) " "['client]] is a transient peer which connects to a server to exchange data, " "and goes offline." #. type: paragraph #: 48 #, read-only msgid "" "A vendor supplies a program called a [@https://en.wikipedia.org/wiki/" "Device_driver ['device driver]], enabling networking hardware such as an " "[@https://en.wikipedia.org/wiki/Network_interface_controller ['ethernet " "adaptor]] to talk to the operating system. This in turn permits running " "programs to interact with networking using various flavors of interfaces " "such as [@https://en.wikipedia.org/wiki/Berkeley_sockets ['Berkeley " "sockets]] or [@https://en.wikipedia.org/wiki/Winsock ['Windows Sockets 2]] " "(\"Winsock\")." msgstr "" "A vendor supplies a program called a [@https://en.wikipedia.org/wiki/" "Device_driver ['device driver]], enabling networking hardware such as an " "[@https://en.wikipedia.org/wiki/Network_interface_controller ['ethernet " "adaptor]] to talk to the operating system. This in turn permits running " "programs to interact with networking using various flavors of interfaces " "such as [@https://en.wikipedia.org/wiki/Berkeley_sockets ['Berkeley " "sockets]] or [@https://en.wikipedia.org/wiki/Winsock ['Windows Sockets 2]] " "(\"Winsock\")." #. type: paragraph #: 57 #, read-only msgid "" "Networking in C++, represented by __Asio__, [@https://think-async.com/Asio/ " "Asio], and __NetTS__, provides a layer of abstraction to interact portably " "with the operating system facilities for not just networking but general " "[@https://en.wikipedia.org/wiki/Input/output ['input/output]] (\"I/O\")." msgstr "" "Networking in C++, represented by __Asio__, [@https://think-async.com/Asio/ " "Asio], and __NetTS__, provides a layer of abstraction to interact portably " "with the operating system facilities for not just networking but general " "[@https://en.wikipedia.org/wiki/Input/output ['input/output]] (\"I/O\")." #. type: heading #: 65 #, read-only msgid "Buffers" msgstr "Buffers" #. type: paragraph #: 67 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 79 #, read-only msgid "" "`const_buffer` and `mutable_buffer` are preferred over `std::span`" msgstr "" "`const_buffer` and `mutable_buffer` are preferred over `std::span`" #. type: paragraph #: 92 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 104 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 125 #, read-only msgid "" "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:" msgstr "" "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:" #. type: heading #: 146 #, read-only msgid "Synchronous I/O" msgstr "Synchronous I/O" #. type: paragraph #: 148 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 162 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 170 #, read-only msgid "" "The same algorithm may be expressed using error codes instead of exceptions:" msgstr "" "The same algorithm may be expressed using error codes instead of exceptions:" #. type: heading #: 176 #, read-only msgid "Asynchronous I/O" msgstr "Asynchronous I/O" #. type: paragraph #: 178 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 196 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 214 #, read-only msgid "" "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`]:" msgstr "" "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`]:" #. type: paragraph #: 224 #, read-only msgid "" "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." msgstr "" "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." #. type: paragraph #: 229 #, read-only msgid "" "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` and the executor of the corresponding I/O object." msgstr "" "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` and the executor of the corresponding I/O object." #. type: paragraph #: 236 #, read-only msgid "" "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." msgstr "" "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." #. type: paragraph #: 241 #, read-only msgid "" "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`] ." msgstr "" "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`] ." #. type: paragraph #: 248 #, read-only msgid "" "The available [@boost:/doc/html/boost_asio/reference/cancellation_type.html " "cancellation types] are listed below." msgstr "" "The available [@boost:/doc/html/boost_asio/reference/cancellation_type.html " "cancellation types] are listed below." #. type: list #: 250 #, read-only msgid "# `terminal`" msgstr "# `terminal`" #. type: list #: 254 #, read-only msgid "# `partial`" msgstr "# `partial`" #. type: list #: 259 #, read-only msgid "# `total`" msgstr "# `total`" #. type: paragraph #: 266 #, read-only msgid "" "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`]." msgstr "" "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`]." #. type: paragraph #: 274 #, read-only msgid "" "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:" msgstr "" "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:" #. type: heading #: 288 #, read-only msgid "Concurrency" msgstr "Concurrency" #. type: paragraph #: 290 #, read-only msgid "" "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]]." msgstr "" "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]]." #. type: heading #: 307 #, read-only msgid "Universal Model" msgstr "Universal Model" #. type: paragraph #: 309 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 321 #, read-only msgid "" "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`]:" msgstr "" "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`]:" #. type: paragraph #: 333 #, read-only msgid "" "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` 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`]:" msgstr "" "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` 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`]:" #. type: paragraph #: 343 #, read-only msgid "" "Note that a `spawn` function itself has a completion signature, but we're " "ignoring it's result in the example by using `asio::detached`." msgstr "" "Note that a `spawn` function itself has a completion signature, but we're " "ignoring it's result in the example by using `asio::detached`." #. type: paragraph #: 348 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 363 #, read-only msgid "" "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." msgstr "" "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." #. type: heading #: 371 #, read-only msgid "Using Networking" msgstr "Using Networking" #. type: paragraph #: 373 #, read-only msgid "" "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:" msgstr "" "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:" #. type: paragraph #: 380 #, read-only msgid "" "Throughout this documentation identifiers with the following names have " "special meaning:" msgstr "" "Throughout this documentation identifiers with the following names have " "special meaning:" #. type: table title #: 383 #, read-only msgid "Global Variables" msgstr "Global Variables" #. type: table cell #: 383 #, read-only msgid "Name" msgstr "Name" #. type: table cell #: 383 #, read-only msgid "Description" msgstr "Description" #. type: table cell #: 383 #, read-only msgid "[@boost:/doc/html/boost_asio/reference/io_context.html [*`ioc`]]" msgstr "[@boost:/doc/html/boost_asio/reference/io_context.html [*`ioc`]]" #. type: table cell #: 383 #, read-only msgid "" "A variable of type __io_context__ which is running on one separate thread, " "and upon which an __executor_work_guard__ object has been constructed." msgstr "" "A variable of type __io_context__ which is running on one separate thread, " "and upon which an __executor_work_guard__ object has been constructed." #. type: table cell #: 383 #, read-only msgid "[@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html [*`sock`]]" msgstr "[@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html [*`sock`]]" #. type: table cell #: 383 #, read-only msgid "" "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." msgstr "" "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." #. type: table cell #: 383 #, read-only msgid "[@boost:/doc/html/boost_asio/reference/ssl__stream.html [*`ssl_sock`]]" msgstr "[@boost:/doc/html/boost_asio/reference/ssl__stream.html [*`ssl_sock`]]" #. type: table cell #: 383 #, read-only msgid "" "A variable of type [@boost:/doc/html/boost_asio/reference/ssl__stream.html " "`net::ssl::stream`] which is already connected and has " "handshaked with a remote host." msgstr "" "A variable of type [@boost:/doc/html/boost_asio/reference/ssl__stream.html " "`net::ssl::stream`] which is already connected and has " "handshaked with a remote host." #. type: table cell #: 383 #, read-only msgid "[link beast.ref.boost__beast__websocket__stream [*`ws`]]" msgstr "[link beast.ref.boost__beast__websocket__stream [*`ws`]]" #. type: table cell #: 383 #, read-only msgid "" "A variable of type [link beast.ref.boost__beast__websocket__stream " "`websocket::stream`] which is already connected with a remote " "host." msgstr "" "A variable of type [link beast.ref.boost__beast__websocket__stream " "`websocket::stream`] which is already connected with a remote " "host."