msgid "" msgstr "" "Project-Id-Version: Chinese (Simplified Han script) (Boost Beast Translation " "(zh_Hans))\n" "Report-Msgid-Bugs-To: \n" "POT-Creation-Date: 2026-07-25 13:57+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: Chinese (Simplified Han script) \n" "Language: zh_Hans\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "Plural-Forms: nplurals=1; plural=0;\n" "X-Generator: Weblate 2026.5\n" #. type: section title #: 10 msgid "Refresher" msgstr "回顾" #. type: paragraph #: 12 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 "" "为有效使用 Beast，需要预先理解网络库相关知识。本节对这些概念进行回顾，以作为" "提醒及进一步学习的指引。" #. type: paragraph #: 16 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 "" "[@https://en.wikipedia.org/wiki/Computer_network [网络]] 允许位于任意地点的程" "序在建立 [@https://en.wikipedia.org/wiki/Data_link [连接]] 并选择通信后进行信" "息交换。数据可通过连接在双向（[@https://en.wikipedia.org/wiki/Duplex_" "(telecommunications) [全双工]]）上可靠传输，且字节按发送顺序到达。这些连接以" "及用于表示连接的对象和类型统称为 [link beast.concepts.streams [流]]。连接到网" "络的计算机或设备称为 [@https://en.wikipedia.org/wiki/Host_(network) [主机]]，" "已建立连接另一端的程序称为 [@https://en.wikipedia.org/wiki/Peer-to-peer [对等" "端]]。" #. type: paragraph #: 31 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 "" "[@https://en.wikipedia.org/wiki/Internet [互联网]] 是一个由全球互联计算机组成" "的网络，这些计算机使用多种标准化的通信协议进行信息交换。其中最为流行的协议是 " "[@https://en.wikipedia.org/wiki/Transmission_Control_Protocol [TCP/IP]]，这也" "是本库唯一依赖的协议。该协议处理了底层细节，使得应用程序看到的是一个可靠的、" "全双工的流式连接，用于承载上述有序字节序列。[@https://en.wikipedia.org/wiki/" "Server_(computing) [服务器]] 是一台强大的、始终在线的主机，位于知名的网络名称" "或地址上，用于提供数据服务。而 [@https://en.wikipedia.org/wiki/Client_" "(computing) [客户端]] 则是一个临时的对等端，它连接到服务器进行数据交换，完成" "后便离线。" #. type: paragraph #: 48 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 "" "[@https://en.wikipedia.org/wiki/Internet [互联网]] 是一个由全球互联计算机组成" "的网络，这些计算机使用多种标准化的通信协议进行信息交换。其中最为流行的协议是 " "[@https://en.wikipedia.org/wiki/Transmission_Control_Protocol [TCP/IP]]，这也" "是本库唯一依赖的协议。该协议处理了底层细节，使得应用程序看到的是一个可靠的、" "全双工的流式连接，用于承载上述有序字节序列。[@https://en.wikipedia.org/wiki/" "Server_(computing) [服务器]] 是一台强大的、始终在线的主机，位于知名的网络名称" "或地址上，用于提供数据服务。而 [@https://en.wikipedia.org/wiki/Client_" "(computing) [客户端]] 则是一个临时的对等端，它连接到服务器进行数据交换，完成" "后便离线。" #. type: paragraph #: 57 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 "" "C++ 中的网络编程以 __Asio__、[@https://think-async.com/Asio/ Asio] 以及 " "__NetTS__ 为代表，提供了一个抽象层，用于可移植地与操作系统设施交互。这些设施" "不仅涵盖网络，还涉及通用的 [@https://en.wikipedia.org/wiki/Input/output [输" "入/输出]]（简称 I/O）。" #. type: heading #: 65 msgid "Buffers" msgstr "缓冲区" #. type: paragraph #: 67 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 "" "[@https://en.wikipedia.org/wiki/Data_buffer [缓冲区]] 是用于存放 I/O 操作中字" "节数据的一段连续内存区域。[@boost:/doc/html/boost_asio/reference/" "const_buffer.html `net::const_buffer`] 与 [@boost:/doc/html/boost_asio/" "reference/mutable_buffer.html `net::mutable_buffer`] 类型以类型安全的指针/大" "小对来表示这些内存区域。" #. type: paragraph #: 79 msgid "" "`const_buffer` and `mutable_buffer` are preferred over `std::span`" msgstr "`const_buffer` 与 `mutable_buffer` 比 `std::span` 更适用。" #. type: paragraph #: 92 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 "" "__ConstBufferSequence__ 与 __MutableBufferSequence__ 概念用于描述双向范围，其" "值类型分别可转换为 `const_buffer` 与 `mutable_buffer`。这些序列允许在单个函数" "调用中处理多个缓冲区，这种技术称为 [@https://en.wikipedia.org/wiki/" "Vectored_I/O [分散/聚集 I/O]]。缓冲区及缓冲区序列不具有所有权；拷贝操作产生的" "是浅层引用，而非底层内存的副本。以下每条语句都用于声明一个缓冲区序列：" #. type: paragraph #: 104 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 "" "[@boost:/doc/html/boost_asio/reference/buffer_size.html `net::buffer_size`] " "函数用于确定缓冲区序列中的总字节数，而 [@boost:/doc/html/boost_asio/" "reference/buffer_copy.html `net::buffer_copy`] 函数则用于将部分或全部字节从一" "个缓冲区序列转移到另一个序列。`buffer_size` 是一个定制点：允许用户在外层命名" "空间中定义重载版本，调用时不应使用命名空间限定符。[@boost:/doc/html/" "boost_asio/reference/buffer_sequence_begin.html " "`net::buffer_sequence_begin`] 与 [@boost:/doc/html/boost_asio/reference/" "buffer_sequence_end.html `net::buffer_sequence_end`] 函数用于获取遍历序列的一" "对迭代器。Beast 提供了一系列缓冲区序列类型和算法，包括 [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`] 以及 [link " "beast.ref.boost__beast__buffers_suffix `buffers_suffix`]。以下示例将缓冲区序" "列中的字节转换为字符串：" #. type: paragraph #: 125 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 "" "__DynamicBuffer__ 概念用于定义一个可调整大小的缓冲区序列接口。当内存需求无法" "预先确定时（例如从流中读取 HTTP 消息时），算法可以使用动态缓冲区来表达。" "Beast 提供一系列完善的动态缓冲区类型，包括 [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`] 以及 [link " "beast.ref.boost__beast__static_buffer `static_buffer`]。以下函数从 [link " "beast.ref.boost__beast__tcp_stream `tcp_stream`] 中读取数据到动态缓冲区，直到" "遇到换行符为止，该函数使用 [@boost:/doc/html/boost_asio/reference/" "buffers_iterator.html `net::buffers_iterator`] 将缓冲区内容视为字符范围进行处" "理：" #. type: heading #: 146 msgid "Synchronous I/O" msgstr "同步 I/O" #. type: paragraph #: 148 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 "" "同步输入与输出通过阻塞函数调用实现，这些调用在操作完成后将返回结果。此类操作" "通常无法取消，也没有设置超时的方法。__SyncReadStream__ 与 " "__SyncWriteStream__ 概念用于定义 [同步流] 的要求：这是一种可移植的 I/O 抽象，" "使用缓冲区序列来传输字节数据，并通过 `error_code` 或异常来报告错误。[@boost:/" "doc/html/boost_asio/reference/basic_stream_socket.html " "`net::basic_stream_socket`] 是一种常用的同步流，用于建立 TCP/IP 连接。用户也" "可以定义满足这些要求的自定义类型。" #. type: paragraph #: 162 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 "" "同步流算法用于编写为函数模板，接受满足同步读写（或两者兼具）命名要求的流对象" "。以下示例用于展示一个写入文本并使用异常指示错误的算法：" #. type: paragraph #: 170 msgid "" "The same algorithm may be expressed using error codes instead of exceptions:" msgstr "同一算法也可采用错误码而非异常的方式来表述：" #. type: heading #: 176 msgid "Asynchronous I/O" msgstr "异步 I/O" #. type: paragraph #: 178 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 "" "异步操作从调用 [@boost:/doc/html/boost_asio/reference/" "asynchronous_operations.html [发起函数]] 开始。该函数负责启动操作并立即返回，" "不会等待操作完成。随后，这个 [未完成] 的异步操作会在后台并发执行，不会阻塞调" "用者。当操作的外部可见效果全部产生后，发起函数中提供的一个可移动对象（称为 " "[@boost:/doc/html/boost_asio/reference/CompletionHandler.html [完成处理器]]）" "会连同操作结果（例如错误码及其他信息）一起被放入队列，等待执行。完成处理器被" "放入队列的那一刻，就意味着该异步操作 [已完成]。下面的代码演示了如何异步地向套" "接字写入一段文本，并在操作完成时调用一个 lambda 函数：" #. type: paragraph #: 196 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 "" "每个完成处理器（也称为 [@https://en.wikipedia.org/wiki/Continuation [延续]]）" "都包含三个关联组件：通过 [@boost:/doc/html/boost_asio/reference/" "get_associated_allocator.html `net::get_associated_allocator`] 获取的 " "[@boost:/doc/html/boost_asio/overview/core/allocation.html [关联分配器]]、通" "过 [@boost:/doc/html/boost_asio/reference/associated_cancellation_slot.html " "`net::get_associated_cancellation_slot`] 获取的 [@boost:/doc/html/boost_asio/" "reference/associated_cancellation_slot.html [关联取消槽]]，以及通过 [@boost:/" "doc/html/boost_asio/reference/get_associated_executor.html " "`net::get_associated_executor`] 获取的 [@boost:/doc/html/boost_asio/" "reference/associated_executor.html [关联执行器]]。这些关联可以通过内嵌方式指" "定：" #. type: paragraph #: 214 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 "" "或者，这些关联也可以通过非侵入方式指定，即特化类模板 [@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`] 以及 " "[@boost:/doc/html/boost_asio/reference/associated_executor.html " "`net::associated_executor`]：" #. type: paragraph #: 224 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 "" "当调用方希望更改完成处理器的执行器时，可以使用 [@boost:/doc/html/boost_asio/" "reference/bind_executor.html `net::bind_executor`] 函数。" #. type: paragraph #: 229 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 "" "实现使用该分配器来获取执行操作所需的任何临时存储空间。所有临时分配的内存在完" "成处理器被调用之前都会被释放。执行器是一种轻量可复制的对象，提供用于调用完成" "处理器的算法。除非调用方进行了自定义，否则完成处理器默认使用 " "`std::allocator` 以及对应 I/O 对象的执行器。" #. type: paragraph #: 236 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 "" "当调用方希望为操作指定自定义分配器时，可以使用 [@boost:/doc/html/boost_asio/" "reference/bind_allocator.html `net::bind_allocator`] 函数。" #. type: paragraph #: 241 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 "" "完成处理器令牌所关联的取消槽可用于取消单个操作。该取消槽通常由完成处理器令牌" "（例如 [@boost:/doc/html/boost_asio/reference/use_awaitable.html " "`net::use_awaitable`] 或 [@boost:/doc/html/boost_asio/reference/" "yield_context.html `net::yield_context`]）进行传递。" #. type: paragraph #: 248 msgid "" "The available [@boost:/doc/html/boost_asio/reference/cancellation_type.html " "cancellation types] are listed below." msgstr "" "可用的 [@boost:/doc/html/boost_asio/reference/cancellation_type.html 取消类" "型] 如下所列。" #. type: list #: 250 msgid "# `terminal`" msgstr "# `terminal` —— 终止型" #. type: list #: 254 msgid "# `partial`" msgstr "# `partial` —— 部分型" #. type: list #: 259 msgid "# `total`" msgstr "# `total` —— 完全型" #. type: paragraph #: 266 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 "" "网络库规定用于确定处理器运行上下文的设施。每个 I/O 对象都关联一个 " "__ExecutionContext__，用于获取调用完成处理器所需的 __Executor__ 实例。执行器" "决定完成处理器的调用位置与方式。从 __io_context__ 实例获取的执行器提供一项基" "本保证：处理器仅会在当前正在调用 [@boost:/doc/html/boost_asio/reference/" "io_context/run/overload1.html `net::io_context::run`] 的线程中被执行。" #. type: paragraph #: 274 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 "" "__AsyncReadStream__ 与 __AsyncWriteStream__ 概念用于定义 [异步流] 的要求：这" "是一种可移植的 I/O 抽象，能够异步交换数据，使用缓冲区序列表示字节数据，并通" "过 `error_code` 报告错误。[异步流算法] 以模板化的发起函数形式编写，接受满足异" "步读、异步写或两者兼具命名要求的流对象。以下示例用于展示一个向异步流写入文本" "的算法：" #. type: heading #: 288 msgid "Concurrency" msgstr "并发" #. type: paragraph #: 290 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 对象 [*不是线程安全的]。尽管可以同时有多个操作未完成（例如，" "同时进行异步读和异步写），但流对象本身在同一时刻只能从一个线程进行访问。这意" "味着移动构造函数、析构函数或发起函数等成员函数不能并发调用。通常，这可以通过" "互斥锁等同步原语来实现，但并发网络程序需要更好的方式来访问共享资源，因为获取" "互斥锁的所有权可能会阻塞线程，使其无法执行无竞争的工作。为了提高效率，网络库" "采用了一种无需显式加锁的线程使用模型，要求所有对 I/O 对象的访问都必须在一个 " "[@boost:/doc/html/boost_asio/overview/core/strands.html [串行器]] 内执行。" #. type: heading #: 307 msgid "Universal Model" msgstr "通用模型" #. type: paragraph #: 309 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 "" "由于完成处理器会导致控制流反转，有时需要其他方式来附加延续。网络库提供 " "[@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3747.pdf [异步操作" "通用模型]]，该模型提供一种可定制的方法，用于改变发起函数的签名，以便使用其他" "类型的对象和方法来替代完成处理器回调。例如，使用 `std::future` 接收传输字节数" "来异步向套接字写入字符串的调用方式如下：" #. type: paragraph #: 321 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 "" "此功能通过将变量 [@boost:/doc/html/boost_asio/reference/use_future.html " "`net::use_future`]（类型为 [@boost:/doc/html/boost_asio/reference/" "use_future_t.html `net::use_future_t<>`]）传递给完成处理器位置来实现。同一个 " "`async_write` 函数重载还可以与通过 [@boost:/doc/html/boost_asio/reference/" "spawn/overload1.html `asio::spawn`] 启动的 [@https://en.wikipedia.org/wiki/" "Fiber_(computer_science) [纤程]] 配合使用：" #. type: paragraph #: 333 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 "" "在这两种情况下，都使用具有特定类型的对象来替代完成处理器，且发起函数的返回值" "也从 `void` 转变为 `std::future` 或 `std::size_t`。在这种上下文" "中，该处理器有时被称为 __CompletionToken__。发起函数签名中的定制点支持这种返" "回值类型的转换。以下是 [@boost:/doc/html/boost_asio/reference/async_write/" "overload1.html `net::async_write`] 的签名：" #. type: paragraph #: 343 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 "" "需要注意的是，`spawn` 函数本身也带有完成签名，但示例中通过使用 " "`asio::detached` 忽略了它的结果。" #. type: paragraph #: 348 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 "" "函数返回值类型由 [@boost:/doc/html/boost_asio/reference/async_result.html " "`net::async_result`] 定制点决定。该定制点为 `std::future` 等常用库类型提供特" "化版本，同时也支持用户自定义类型的特化。发起函数的函数体通过调用 [@boost:/" "doc/html/boost_asio/reference/async_initiate.html `net::async_initiate`] 辅助" "函数来捕获参数并将其转发给 `async_result` 的特化版本。此外，还提供一个额外的“" "发起函数”对象，`async_result` 可利用该对象立即启动操作，或将操作启动延迟到未" "来某个时刻（即“延迟执行”）。该发起函数对象接收一个内部完成处理器，其签名与发" "起函数所期望的签名相匹配。" #. type: paragraph #: 363 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 "" "这个经过转换的内部处理器负责执行最终步骤，将操作结果传递给调用方。例如，当使" "用 `net::use_future` 时，内部处理器会通过调用发起函数返回的 promise 对象上的 " "[@https://en.cppreference.com/w/cpp/thread/promise/set_value " "`std::promise::set_value`] 来传递结果。" #. type: heading #: 371 msgid "Using Networking" msgstr "使用网络库" #. type: paragraph #: 373 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 "" "大多数库中的流算法都需要一个已与远程对等端建立通信的 " "__socket__、__ssl_stream__ 或其他 __Stream__ 对象。以下示例用于回顾如何使用套" "接字：" #. type: paragraph #: 380 msgid "" "Throughout this documentation identifiers with the following names have " "special meaning:" msgstr "在本文档中，以下名称的标识符具有特殊含义：" #. type: table title #: 383 msgid "Global Variables" msgstr "全局变量" #. type: table cell #: 383 msgid "Name" msgstr "名称" #. type: table cell #: 383 msgid "Description" msgstr "描述" #. type: table cell #: 383 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 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 "" "一个类型为 __io_context__ 的变量，该变量在单独线程上运行，且已为其构造一个 " "__executor_work_guard__ 对象。" #. type: table cell #: 383 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 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 "" "一个类型为 [@boost:/doc/html/boost_asio/reference/ip__tcp/socket.html " "`tcp::socket`] 的变量，该变量已连接到远程主机。" #. type: table cell #: 383 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 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 "" "一个类型为 [@boost:/doc/html/boost_asio/reference/ssl__stream.html " "`net::ssl::stream`] 的变量，该变量已与远程主机建立连接并完成握手" "。" #. type: table cell #: 383 msgid "[link beast.ref.boost__beast__websocket__stream [*`ws`]]" msgstr "[link beast.ref.boost__beast__websocket__stream [*`ws`]]" #. type: table cell #: 383 msgid "" "A variable of type [link beast.ref.boost__beast__websocket__stream " "`websocket::stream`] which is already connected with a remote " "host." msgstr "" "一个类型为 [link beast.ref.boost__beast__websocket__stream " "`websocket::stream`] 的变量，该变量已与远程主机建立连接。"