[Boost-commit] svn:boost r44685 - in trunk/libs/asio/doc: . requirements

From: chris_at_[hidden]
Date: 2008-04-21 03:59:22

Author: chris_kohlhoff
Date: 2008-04-21 03:59:21 EDT (Mon, 21 Apr 2008)
New Revision: 44685
URL: http://svn.boost.org/trac/boost/changeset/44685

Log:
Add requirements for handle and descriptor services. Add new classes to the
quickref index page.

Added:
   trunk/libs/asio/doc/requirements/DescriptorService.qbk   (contents, props changed)
   trunk/libs/asio/doc/requirements/HandleService.qbk   (contents, props changed)
   trunk/libs/asio/doc/requirements/StreamDescriptorService.qbk   (contents, props changed)
   trunk/libs/asio/doc/requirements/StreamHandleService.qbk   (contents, props changed)
Text files modified: 
   trunk/libs/asio/doc/quickref.xml |    23 +++++++++++++++++++++++                 
   1 files changed, 23 insertions(+), 0 deletions(-)

Modified: trunk/libs/asio/doc/quickref.xml
==============================================================================
--- trunk/libs/asio/doc/quickref.xml	(original)
+++ trunk/libs/asio/doc/quickref.xml	2008-04-21 03:59:21 EDT (Mon, 21 Apr 2008)
@@ -37,13 +37,24 @@
             <listitem><link linkend="boost_asio.reference.ip__udp.endpoint">ip::udp::endpoint</link></listitem>
             <listitem><link linkend="boost_asio.reference.ip__udp.resolver">ip::udp::resolver</link></listitem>
             <listitem><link linkend="boost_asio.reference.ip__udp.socket">ip::udp::socket</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__stream_protocol">local::stream_protocol</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__stream_protocol.acceptor">local::stream_protocol::acceptor</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__stream_protocol.endpoint">local::stream_protocol::endpoint</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__stream_protocol.iostream">local::stream_protocol::iostream</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__stream_protocol.socket">local::stream_protocol::socket</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__datagram_protocol">local::datagram_protocol</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__datagram_protocol.endpoint">local::datagram_protocol::endpoint</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__datagram_protocol.socket">local::datagram_protocol::socket</link></listitem>
             <listitem><link linkend="boost_asio.reference.mutable_buffer">mutable_buffer</link></listitem>
             <listitem><link linkend="boost_asio.reference.mutable_buffers_1">mutable_buffers_1</link></listitem>
+            <listitem><link linkend="boost_asio.reference.posix__descriptor_base">posix::descriptor_base</link></listitem>
+            <listitem><link linkend="boost_asio.reference.posix__stream_descriptor">posix::stream_descriptor</link></listitem>
             <listitem><link linkend="boost_asio.reference.socket_base">socket_base</link></listitem>
             <listitem><link linkend="boost_asio.reference.ssl__context">ssl::context</link></listitem>
             <listitem><link linkend="boost_asio.reference.ssl__context_base">ssl::context_base</link></listitem>
             <listitem><link linkend="boost_asio.reference.ssl__stream_base">ssl::stream_base</link></listitem>
             <listitem><link linkend="boost_asio.reference.streambuf">streambuf</link></listitem>
+            <listitem><link linkend="boost_asio.reference.windows__stream_handle">windows::stream_handle</link></listitem>
           </itemizedlist>
         </entry>
         <entry valign="top">
@@ -66,18 +77,25 @@
             <listitem><link linkend="boost_asio.reference.ip__basic_resolver_entry">ip::basic_resolver_entry</link></listitem>
             <listitem><link linkend="boost_asio.reference.ip__basic_resolver_iterator">ip::basic_resolver_iterator</link></listitem>
             <listitem><link linkend="boost_asio.reference.ip__basic_resolver_query">ip::basic_resolver_query</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__basic_endpoint">local::basic_endpoint</link></listitem>
+            <listitem><link linkend="boost_asio.reference.posix__basic_descriptor">posix::basic_descriptor</link></listitem>
+            <listitem><link linkend="boost_asio.reference.posix__basic_stream_descriptor">posix::basic_stream_descriptor</link></listitem>
             <listitem><link linkend="boost_asio.reference.ssl__basic_context">ssl::basic_context</link></listitem>
             <listitem><link linkend="boost_asio.reference.ssl__stream">ssl::stream</link></listitem>
+            <listitem><link linkend="boost_asio.reference.windows__basic_handle">windows::basic_handle</link></listitem>
+            <listitem><link linkend="boost_asio.reference.windows__basic_stream_handle">windows::basic_stream_handle</link></listitem>
           </itemizedlist>
           <bridgehead renderas="sect3">Services</bridgehead>
           <itemizedlist>
             <listitem><link linkend="boost_asio.reference.datagram_socket_service">datagram_socket_service</link></listitem>
             <listitem><link linkend="boost_asio.reference.deadline_timer_service">deadline_timer_service</link></listitem>
             <listitem><link linkend="boost_asio.reference.ip__resolver_service">ip::resolver_service</link></listitem>
+            <listitem><link linkend="boost_asio.reference.posix__stream_descriptor_service">posix::stream_descriptor_service</link></listitem>
             <listitem><link linkend="boost_asio.reference.socket_acceptor_service">socket_acceptor_service</link></listitem>
             <listitem><link linkend="boost_asio.reference.ssl__context_service">ssl::context_service</link></listitem>
             <listitem><link linkend="boost_asio.reference.ssl__stream_service">ssl::stream_service</link></listitem>
             <listitem><link linkend="boost_asio.reference.stream_socket_service">stream_socket_service</link></listitem>
+            <listitem><link linkend="boost_asio.reference.windows__stream_handle_service">windows::stream_handle_service</link></listitem>
           </itemizedlist>
           <bridgehead renderas="sect3">Placeholders</bridgehead>
           <itemizedlist>
@@ -99,6 +117,7 @@
             <listitem><link linkend="boost_asio.reference.buffer">buffer</link></listitem>
             <listitem><link linkend="boost_asio.reference.has_service">has_service</link></listitem>
             <listitem><link linkend="boost_asio.reference.ip__host_name">ip::host_name</link></listitem>
+            <listitem><link linkend="boost_asio.reference.local__connect_pair">local::connect_pair</link></listitem>
             <listitem><link linkend="boost_asio.reference.read">read</link></listitem>
             <listitem><link linkend="boost_asio.reference.read_until">read_until</link></listitem>
             <listitem><link linkend="boost_asio.reference.transfer_all">transfer_all</link></listitem>
@@ -132,9 +151,11 @@
             <listitem><link linkend="boost_asio.reference.ConvertibleToConstBuffer">ConvertibleToConstBuffer</link></listitem>
             <listitem><link linkend="boost_asio.reference.ConvertibleToMutableBuffer">ConvertibleToMutableBuffer</link></listitem>
             <listitem><link linkend="boost_asio.reference.DatagramSocketService">DatagramSocketService</link></listitem>
+            <listitem><link linkend="boost_asio.reference.DescriptorService">DescriptorService</link></listitem>
             <listitem><link linkend="boost_asio.reference.Endpoint">Endpoint</link></listitem>
             <listitem><link linkend="boost_asio.reference.GettableSocketOption">GettableSocketOption</link></listitem>
             <listitem><link linkend="boost_asio.reference.Handler">Handler</link></listitem>
+            <listitem><link linkend="boost_asio.reference.HandleService">HandleService</link></listitem>
             <listitem><link linkend="boost_asio.reference.InternetProtocol">InternetProtocol</link></listitem>
             <listitem><link linkend="boost_asio.reference.IoControlCommand">IoControlCommand</link></listitem>
             <listitem><link linkend="boost_asio.reference.IoObjectService">IoObjectService</link></listitem>
@@ -147,6 +168,8 @@
             <listitem><link linkend="boost_asio.reference.SettableSocketOption">SettableSocketOption</link></listitem>
             <listitem><link linkend="boost_asio.reference.SocketAcceptorService">SocketAcceptorService</link></listitem>
             <listitem><link linkend="boost_asio.reference.SocketService">SocketService</link></listitem>
+            <listitem><link linkend="boost_asio.reference.StreamDescriptorService">StreamDescriptorService</link></listitem>
+            <listitem><link linkend="boost_asio.reference.StreamHandleService">StreamHandleService</link></listitem>
             <listitem><link linkend="boost_asio.reference.StreamSocketService">StreamSocketService</link></listitem>
             <listitem><link linkend="boost_asio.reference.SyncReadStream">SyncReadStream</link></listitem>
             <listitem><link linkend="boost_asio.reference.SyncWriteStream">SyncWriteStream</link></listitem>

Added: trunk/libs/asio/doc/requirements/DescriptorService.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/DescriptorService.qbk	2008-04-21 03:59:21 EDT (Mon, 21 Apr 2008)
@@ -0,0 +1,120 @@
+[/
+ / Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:DescriptorService Descriptor service requirements]
+
+A descriptor service must meet the requirements for an [link
+boost_asio.reference.IoObjectService I/O object service], as well as the
+additional requirements listed below.
+
+In the table below, `X` denotes a descriptor service class, `a` denotes a value
+of type `X`, `b` denotes a value of type `X::implementation_type`, `n` denotes
+a value of type `X::native_type`, `ec` denotes a value of type `error_code`,
+`i` denotes a value meeting [link boost_asio.reference.IoControlCommand
+`IoControlCommand`] requirements, and `u` and `v` denote identifiers.
+
+[table DescriptorService requirements
+  [[expression] [return type] [assertion/note\npre/post-condition]]
+  [
+    [`X::native_type`]
+    []
+    [
+      The implementation-defined native representation of a descriptor. Must
+      satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3),
+      and the requirements of `Assignable` types (C++ Std, 23.1).
+    ]
+  ]
+  [
+    [`a.construct(b);`]
+    []
+    [
+      From [link boost_asio.reference.IoObjectService IoObjectService]
+      requirements.\n
+      post: `!a.is_open(b)`.
+    ]
+  ]
+  [
+    [`a.destroy(b);`]
+    []
+    [
+      From [link boost_asio.reference.IoObjectService IoObjectService]
+      requirements. Implicitly cancels asynchronous operations, as if by calling
+      `a.close(b, ec)`.
+    ]
+  ]
+  [
+    [``
+      a.assign(b, n, ec);
+    ``]
+    [`error_code`]
+    [
+      pre: `!a.is_open(b)`.\n
+      post: `!!ec || a.is_open(b)`.
+    ]
+  ]
+  [
+    [``
+      a.is_open(b);
+    ``]
+    [`bool`]
+    [
+    ]
+  ]
+  [
+    [``
+      const X& u = a;
+      const X::implementation_type& v = b;
+      u.is_open(v);
+    ``]
+    [`bool`]
+    [
+    ]
+  ]
+  [
+    [``
+      a.close(b, ec);
+    ``]
+    [`error_code`]
+    [
+      If `a.is_open()` is true, causes any outstanding asynchronous operations
+      to complete as soon as possible. Handlers for cancelled operations shall
+      be passed the error code `error::operation_aborted`.\n
+      post: `!a.is_open(b)`.
+    ]
+  ]
+  [
+    [``
+      a.native(b);
+    ``]
+    [`X::native_type`]
+    [
+    ]
+  ]
+  [
+    [``
+      a.cancel(b, ec);
+    ``]
+    [`error_code`]
+    [
+      pre: `a.is_open(b)`.\n
+      Causes any outstanding asynchronous operations to complete as soon as
+      possible. Handlers for cancelled operations shall be passed the error
+      code `error::operation_aborted`.
+    ]
+  ]
+  [
+    [``
+      a.io_control(b, i, ec);
+    ``]
+    [`error_code`]
+    [
+      pre: `a.is_open(b)`.
+    ]
+  ]
+]
+
+[endsect]

Added: trunk/libs/asio/doc/requirements/HandleService.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/HandleService.qbk	2008-04-21 03:59:21 EDT (Mon, 21 Apr 2008)
@@ -0,0 +1,110 @@
+[/
+ / Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:HandleService Handle service requirements]
+
+A handle service must meet the requirements for an [link
+boost_asio.reference.IoObjectService I/O object service], as well as the
+additional requirements listed below.
+
+In the table below, `X` denotes a handle service class, `a` denotes a value of
+type `X`, `b` denotes a value of type `X::implementation_type`, `n` denotes a
+value of type `X::native_type`, `ec` denotes a value of type `error_code`, and
+`u` and `v` denote identifiers.
+
+[table HandleService requirements
+  [[expression] [return type] [assertion/note\npre/post-condition]]
+  [
+    [`X::native_type`]
+    []
+    [
+      The implementation-defined native representation of a handle. Must
+      satisfy the requirements of `CopyConstructible` types (C++ Std, 20.1.3),
+      and the requirements of `Assignable` types (C++ Std, 23.1).
+    ]
+  ]
+  [
+    [`a.construct(b);`]
+    []
+    [
+      From [link boost_asio.reference.IoObjectService IoObjectService]
+      requirements.\n
+      post: `!a.is_open(b)`.
+    ]
+  ]
+  [
+    [`a.destroy(b);`]
+    []
+    [
+      From [link boost_asio.reference.IoObjectService IoObjectService]
+      requirements. Implicitly cancels asynchronous operations, as if by calling
+      `a.close(b, ec)`.
+    ]
+  ]
+  [
+    [``
+      a.assign(b, n, ec);
+    ``]
+    [`error_code`]
+    [
+      pre: `!a.is_open(b)`.\n
+      post: `!!ec || a.is_open(b)`.
+    ]
+  ]
+  [
+    [``
+      a.is_open(b);
+    ``]
+    [`bool`]
+    [
+    ]
+  ]
+  [
+    [``
+      const X& u = a;
+      const X::implementation_type& v = b;
+      u.is_open(v);
+    ``]
+    [`bool`]
+    [
+    ]
+  ]
+  [
+    [``
+      a.close(b, ec);
+    ``]
+    [`error_code`]
+    [
+      If `a.is_open()` is true, causes any outstanding asynchronous operations
+      to complete as soon as possible. Handlers for cancelled operations shall
+      be passed the error code `error::operation_aborted`.\n
+      post: `!a.is_open(b)`.
+    ]
+  ]
+  [
+    [``
+      a.native(b);
+    ``]
+    [`X::native_type`]
+    [
+    ]
+  ]
+  [
+    [``
+      a.cancel(b, ec);
+    ``]
+    [`error_code`]
+    [
+      pre: `a.is_open(b)`.\n
+      Causes any outstanding asynchronous operations to complete as soon as
+      possible. Handlers for cancelled operations shall be passed the error
+      code `error::operation_aborted`.
+    ]
+  ]
+]
+
+[endsect]

Added: trunk/libs/asio/doc/requirements/StreamDescriptorService.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/StreamDescriptorService.qbk	2008-04-21 03:59:21 EDT (Mon, 21 Apr 2008)
@@ -0,0 +1,138 @@
+[/
+ / Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:StreamDescriptorService Stream descriptor service requirements]
+
+A stream descriptor service must meet the requirements for a [link
+boost_asio.reference.DescriptorService descriptor service], as well as the additional
+requirements listed below.
+
+In the table below, `X` denotes a stream descriptor service class, `a` denotes
+a value of type `X`, `b` denotes a value of type `X::implementation_type`, `ec`
+denotes a value of type `error_code`, `mb` denotes a value satisfying [link
+boost_asio.reference.MutableBufferSequence mutable buffer sequence] requirements,
+`rh` denotes a value meeting [link boost_asio.reference.ReadHandler `ReadHandler`]
+requirements, `cb` denotes a value satisfying [link
+boost_asio.reference.ConstBufferSequence constant buffer sequence] requirements, and
+`wh` denotes a value meeting [link boost_asio.reference.WriteHandler `WriteHandler`]
+requirements.
+
+[table StreamDescriptorService requirements
+  [[expression] [return type] [assertion/note\npre/post-condition]]
+  [
+    [`a.read_some(b, mb, ec);`]
+    [`size_t`]
+    [
+      pre: `a.is_open(b)`.\n
+      \n
+      Reads one or more bytes of data from a decsriptor `b`.\n
+      \n
+      The mutable buffer sequence `mb` specifies memory where the data should
+      be placed. The operation shall always fill a buffer in the sequence
+      completely before proceeding to the next.\n
+      \n
+      If successful, returns the number of bytes read. Otherwise returns `0`.
+      If the total size of all buffers in the sequence `mb` is `0`, the
+      function shall return `0` immediately.\n
+      \n
+      If the operation completes due to graceful connection closure by the
+      peer, the operation shall fail with `error::eof`.
+    ]
+  ]
+  [
+    [`a.async_read_some(b, mb, rh);`]
+    [`void`]
+    [
+      pre: `a.is_open(b)`.\n
+      \n
+      Initiates an asynchronous operation to read one or more bytes of data
+      from a descriptor `b`. The operation is performed via the
+      `io_service` object `a.io_service()` and behaves according to [link
+      boost_asio.reference.asynchronous_operations asynchronous operation]
+      requirements.\n
+      \n
+      The mutable buffer sequence `mb` specifies memory where the data should
+      be placed. The operation shall always fill a buffer in the sequence
+      completely before proceeding to the next.\n
+      \n
+      The implementation shall maintain one or more copies of `mb` until such
+      time as the read operation no longer requires access to the memory
+      specified by the buffers in the sequence. The program must ensure the
+      memory is valid until:\n
+      \n
+      [mdash] the last copy of `mb` is destroyed, or\n
+      \n
+      [mdash] the handler for the asynchronous operation is invoked,\n
+      \n
+      whichever comes first. If the total size of all buffers in the sequence
+      `mb` is `0`, the asynchronous read operation shall complete immediately
+      and pass `0` as the argument to the handler that specifies the number of
+      bytes read.\n
+      \n
+      If the operation completes due to graceful connection closure by the
+      peer, the operation shall fail with `error::eof`.\n
+      \n
+      If the operation completes successfully, the `ReadHandler` object
+      `rh` is invoked with the number of bytes transferred. Otherwise it is
+      invoked with `0`.
+    ]
+  ]
+  [
+    [`a.write_some(b, cb, ec);`]
+    [`size_t`]
+    [
+      pre: `a.is_open(b)`.\n
+      \n
+      Writes one or more bytes of data to a descriptor `b`.\n
+      \n
+      The constant buffer sequence `cb` specifies memory where the data to be
+      written is located. The operation shall always write a buffer in the
+      sequence completely before proceeding to the next.\n
+      \n
+      If successful, returns the number of bytes written. Otherwise returns `0`.
+      If the total size of all buffers in the sequence `cb` is `0`, the
+      function shall return `0` immediately.
+    ]
+  ]
+  [
+    [`a.async_write_some(b, cb, wh);`]
+    [`void`]
+    [
+      pre: `a.is_open(b)`.\n
+      \n
+      Initiates an asynchronous operation to write one or more bytes of data to
+      a decsriptor `b`. The operation is performed via the `io_service`
+      object `a.io_service()` and behaves according to [link
+      boost_asio.reference.asynchronous_operations asynchronous operation]
+      requirements.\n
+      \n
+      The constant buffer sequence `cb` specifies memory where the data to be
+      written is located. The operation shall always write a buffer in the
+      sequence completely before proceeding to the next.\n
+      \n
+      The implementation shall maintain one or more copies of `cb` until such
+      time as the write operation no longer requires access to the memory
+      specified by the buffers in the sequence. The program must ensure the
+      memory is valid until:\n
+      \n
+      [mdash] the last copy of `cb` is destroyed, or\n
+      \n
+      [mdash] the handler for the asynchronous operation is invoked,\n
+      \n
+      whichever comes first. If the total size of all buffers in the sequence
+      `cb` is `0`, the asynchronous operation shall complete immediately and
+      pass `0` as the argument to the handler that specifies the number of
+      bytes read.\n
+      \n
+      If the operation completes successfully, the `WriteHandler` object `wh`
+      is invoked with the number of bytes transferred. Otherwise it is invoked
+      with `0`.
+    ]
+  ]
+]
+
+[endsect]

Added: trunk/libs/asio/doc/requirements/StreamHandleService.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/StreamHandleService.qbk	2008-04-21 03:59:21 EDT (Mon, 21 Apr 2008)
@@ -0,0 +1,138 @@
+[/
+ / Copyright (c) 2003-2008 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+ /
+ / Distributed under the Boost Software License, Version 1.0. (See accompanying
+ / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+ /]
+
+[section:StreamHandleService Stream handle service requirements]
+
+A stream handle service must meet the requirements for a [link
+boost_asio.reference.HandleService handle service], as well as the additional
+requirements listed below.
+
+In the table below, `X` denotes a stream handle service class, `a` denotes
+a value of type `X`, `b` denotes a value of type `X::implementation_type`, `ec`
+denotes a value of type `error_code`, `mb` denotes a value satisfying [link
+boost_asio.reference.MutableBufferSequence mutable buffer sequence] requirements,
+`rh` denotes a value meeting [link boost_asio.reference.ReadHandler `ReadHandler`]
+requirements, `cb` denotes a value satisfying [link
+boost_asio.reference.ConstBufferSequence constant buffer sequence] requirements, and
+`wh` denotes a value meeting [link boost_asio.reference.WriteHandler `WriteHandler`]
+requirements.
+
+[table StreamHandleService requirements
+  [[expression] [return type] [assertion/note\npre/post-condition]]
+  [
+    [`a.read_some(b, mb, ec);`]
+    [`size_t`]
+    [
+      pre: `a.is_open(b)`.\n
+      \n
+      Reads one or more bytes of data from a decsriptor `b`.\n
+      \n
+      The mutable buffer sequence `mb` specifies memory where the data should
+      be placed. The operation shall always fill a buffer in the sequence
+      completely before proceeding to the next.\n
+      \n
+      If successful, returns the number of bytes read. Otherwise returns `0`.
+      If the total size of all buffers in the sequence `mb` is `0`, the
+      function shall return `0` immediately.\n
+      \n
+      If the operation completes due to graceful connection closure by the
+      peer, the operation shall fail with `error::eof`.
+    ]
+  ]
+  [
+    [`a.async_read_some(b, mb, rh);`]
+    [`void`]
+    [
+      pre: `a.is_open(b)`.\n
+      \n
+      Initiates an asynchronous operation to read one or more bytes of data
+      from a handle `b`. The operation is performed via the
+      `io_service` object `a.io_service()` and behaves according to [link
+      boost_asio.reference.asynchronous_operations asynchronous operation]
+      requirements.\n
+      \n
+      The mutable buffer sequence `mb` specifies memory where the data should
+      be placed. The operation shall always fill a buffer in the sequence
+      completely before proceeding to the next.\n
+      \n
+      The implementation shall maintain one or more copies of `mb` until such
+      time as the read operation no longer requires access to the memory
+      specified by the buffers in the sequence. The program must ensure the
+      memory is valid until:\n
+      \n
+      [mdash] the last copy of `mb` is destroyed, or\n
+      \n
+      [mdash] the handler for the asynchronous operation is invoked,\n
+      \n
+      whichever comes first. If the total size of all buffers in the sequence
+      `mb` is `0`, the asynchronous read operation shall complete immediately
+      and pass `0` as the argument to the handler that specifies the number of
+      bytes read.\n
+      \n
+      If the operation completes due to graceful connection closure by the
+      peer, the operation shall fail with `error::eof`.\n
+      \n
+      If the operation completes successfully, the `ReadHandler` object
+      `rh` is invoked with the number of bytes transferred. Otherwise it is
+      invoked with `0`.
+    ]
+  ]
+  [
+    [`a.write_some(b, cb, ec);`]
+    [`size_t`]
+    [
+      pre: `a.is_open(b)`.\n
+      \n
+      Writes one or more bytes of data to a handle `b`.\n
+      \n
+      The constant buffer sequence `cb` specifies memory where the data to be
+      written is located. The operation shall always write a buffer in the
+      sequence completely before proceeding to the next.\n
+      \n
+      If successful, returns the number of bytes written. Otherwise returns `0`.
+      If the total size of all buffers in the sequence `cb` is `0`, the
+      function shall return `0` immediately.
+    ]
+  ]
+  [
+    [`a.async_write_some(b, cb, wh);`]
+    [`void`]
+    [
+      pre: `a.is_open(b)`.\n
+      \n
+      Initiates an asynchronous operation to write one or more bytes of data to
+      a decsriptor `b`. The operation is performed via the `io_service`
+      object `a.io_service()` and behaves according to [link
+      boost_asio.reference.asynchronous_operations asynchronous operation]
+      requirements.\n
+      \n
+      The constant buffer sequence `cb` specifies memory where the data to be
+      written is located. The operation shall always write a buffer in the
+      sequence completely before proceeding to the next.\n
+      \n
+      The implementation shall maintain one or more copies of `cb` until such
+      time as the write operation no longer requires access to the memory
+      specified by the buffers in the sequence. The program must ensure the
+      memory is valid until:\n
+      \n
+      [mdash] the last copy of `cb` is destroyed, or\n
+      \n
+      [mdash] the handler for the asynchronous operation is invoked,\n
+      \n
+      whichever comes first. If the total size of all buffers in the sequence
+      `cb` is `0`, the asynchronous operation shall complete immediately and
+      pass `0` as the argument to the handler that specifies the number of
+      bytes read.\n
+      \n
+      If the operation completes successfully, the `WriteHandler` object `wh`
+      is invoked with the number of bytes transferred. Otherwise it is invoked
+      with `0`.
+    ]
+  ]
+]
+
+[endsect]