Update requirements, overview and quick reference.
diff --git a/asio/src/doc/asio.qbk b/asio/src/doc/asio.qbk
index 29e3a28..68cc2e0 100644
--- a/asio/src/doc/asio.qbk
+++ b/asio/src/doc/asio.qbk
@@ -19,8 +19,10 @@
]
[template mdash[] '''— ''']
-[template indexterm1[term1] '''<indexterm><primary>'''[term1]'''</primary></indexterm>''']
-[template indexterm2[term1 term2] '''<indexterm><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
+[template half_open_range[text] '''['''[text])]
+[template indexterm1[id term1] '''<indexterm id="'''[id]'''"><primary>'''[term1]'''</primary></indexterm>''']
+[template indexterm2[id term1 term2] '''<indexterm id="'''[id]'''"><primary>'''[term1]'''</primary><secondary>'''[term2]'''</secondary></indexterm>''']
+[template inline_note[text] \[['Note:] [text] '''—'''['end note]\] ]
[template ticket[number]'''<ulink url="https://svn.boost.org/trac/boost/ticket/'''[number]'''">'''#[number]'''</ulink>''']
[def __POSIX__ /POSIX/]
[def __Windows__ /Windows/]
@@ -30,9 +32,11 @@
[def __getsockname__ [@http://www.opengroup.org/onlinepubs/000095399/functions/getsockname.html `getsockname()`]]
[def __getsockopt__ [@http://www.opengroup.org/onlinepubs/000095399/functions/getsockopt.html `getsockopt()`]]
[def __ioctl__ [@http://www.opengroup.org/onlinepubs/000095399/functions/ioctl.html `ioctl()`]]
+[def __poll__ [@http://www.opengroup.org/onlinepubs/000095399/functions/poll.html `poll()`]]
[def __recvfrom__ [@http://www.opengroup.org/onlinepubs/000095399/functions/recvfrom.html `recvfrom()`]]
[def __sendto__ [@http://www.opengroup.org/onlinepubs/000095399/functions/sendto.html `sendto()`]]
[def __setsockopt__ [@http://www.opengroup.org/onlinepubs/000095399/functions/setsockopt.html `setsockopt()`]]
+[def __shutdown__ [@http://www.opengroup.org/onlinepubs/000095399/functions/shutdown.html `shutdown()`]]
[def __socket__ [@http://www.opengroup.org/onlinepubs/000095399/functions/socket.html `socket()`]]
[/=============================================================================]
diff --git a/asio/src/doc/index.xml b/asio/src/doc/index.xml
index b695bbb..3b7b556 100644
--- a/asio/src/doc/index.xml
+++ b/asio/src/doc/index.xml
@@ -9,5 +9,5 @@
-->
<section id="asio.index">
- <index/>
+ <index id="asio.index.index"/>
</section>
diff --git a/asio/src/doc/overview/async.qbk b/asio/src/doc/overview/async.qbk
index fadb2e9..ff62787 100644
--- a/asio/src/doc/overview/async.qbk
+++ b/asio/src/doc/overview/async.qbk
@@ -30,8 +30,8 @@
[mdash] Asynchronous Operation Processor
[:Executes asynchronous operations and queues events on a completion event
-queue when operations complete. From a high-level point of view, services like
-`stream_socket_service` are asynchronous operation processors.]
+queue when operations complete. From a high-level point of view, internal
+services like `reactive_socket_service` are asynchronous operation processors.]
[mdash] Completion Event Queue
@@ -59,7 +59,7 @@
[:Application-specific code that starts asynchronous operations. The initiator
interacts with an asynchronous operation processor via a high-level interface
such as `basic_stream_socket`, which in turn delegates to a service like
-`stream_socket_service`.]
+`reactive_socket_service`.]
[heading Implementation Using Reactor]
diff --git a/asio/src/doc/overview/implementation.qbk b/asio/src/doc/overview/implementation.qbk
index a1529b1..34c92f0 100644
--- a/asio/src/doc/overview/implementation.qbk
+++ b/asio/src/doc/overview/implementation.qbk
@@ -242,8 +242,8 @@
`io_context::poll_one()`.
* An additional thread per `io_context` is used to trigger timers. This thread
-is created on construction of the first `deadline_timer` or
-`deadline_timer_service` objects.
+is created on construction of the first `basic_deadline_timer` or
+`basic_waitable_timer` objects.
* An additional thread per `io_context` is used for the `select`
demultiplexing. This thread is created on the first call to `async_connect()`.
diff --git a/asio/src/doc/overview/posix.qbk b/asio/src/doc/overview/posix.qbk
index 112d054..e35e72e 100644
--- a/asio/src/doc/overview/posix.qbk
+++ b/asio/src/doc/overview/posix.qbk
@@ -93,8 +93,6 @@
[heading See Also]
[link asio.reference.posix__stream_descriptor posix::stream_descriptor],
-[link asio.reference.posix__basic_stream_descriptor posix::basic_stream_descriptor],
-[link asio.reference.posix__stream_descriptor_service posix::stream_descriptor_service],
[link asio.examples.cpp03_examples.chat Chat example (C++03)],
[link asio.examples.cpp11_examples.chat Chat example (C++11)].
@@ -127,7 +125,7 @@
}
User-defined services can also be made fork-aware by overriding the
-`io_context::service::fork_service()` virtual function.
+`io_context::service::notify_fork()` virtual function.
Note that any file descriptors accessible via Asio's public API (e.g. the
descriptors underlying `basic_socket<>`, `posix::stream_descriptor`, etc.) are
@@ -138,7 +136,7 @@
[link asio.reference.io_context.notify_fork io_context::notify_fork()],
[link asio.reference.io_context.fork_event io_context::fork_event],
-[link asio.reference.execution_context__service.fork_service io_context::service::fork_service()],
+[link asio.reference.execution_context__service.notify_fork io_context::service::notify_fork()],
[link asio.examples.cpp03_examples.fork Fork examples].
[endsect]
diff --git a/asio/src/doc/overview/serial_ports.qbk b/asio/src/doc/overview/serial_ports.qbk
index 17fe96d..dd049cd 100644
--- a/asio/src/doc/overview/serial_ports.qbk
+++ b/asio/src/doc/overview/serial_ports.qbk
@@ -29,8 +29,6 @@
[link asio.reference.serial_port serial_port],
[link asio.reference.serial_port_base serial_port_base],
-[link asio.reference.basic_serial_port basic_serial_port],
-[link asio.reference.serial_port_service serial_port_service],
[link asio.reference.serial_port_base__baud_rate serial_port_base::baud_rate],
[link asio.reference.serial_port_base__flow_control serial_port_base::flow_control],
[link asio.reference.serial_port_base__parity serial_port_base::parity],
diff --git a/asio/src/doc/overview/timers.qbk b/asio/src/doc/overview/timers.qbk
index b8eb2b4..0c5528d 100644
--- a/asio/src/doc/overview/timers.qbk
+++ b/asio/src/doc/overview/timers.qbk
@@ -47,7 +47,6 @@
[link asio.reference.basic_deadline_timer basic_deadline_timer],
[link asio.reference.deadline_timer deadline_timer],
-[link asio.reference.deadline_timer_service deadline_timer_service],
[link asio.tutorial.tuttimer1 timer tutorials].
[endsect]
diff --git a/asio/src/doc/overview/windows.qbk b/asio/src/doc/overview/windows.qbk
index 8602025..da49a0b 100644
--- a/asio/src/doc/overview/windows.qbk
+++ b/asio/src/doc/overview/windows.qbk
@@ -37,9 +37,7 @@
[heading See Also]
-[link asio.reference.windows__stream_handle windows::stream_handle],
-[link asio.reference.windows__basic_stream_handle windows::basic_stream_handle],
-[link asio.reference.windows__stream_handle_service windows::stream_handle_service].
+[link asio.reference.windows__stream_handle windows::stream_handle].
[heading Notes]
@@ -76,9 +74,7 @@
[heading See Also]
-[link asio.reference.windows__random_access_handle windows::random_access_handle],
-[link asio.reference.windows__basic_random_access_handle windows::basic_random_access_handle],
-[link asio.reference.windows__random_access_handle_service windows::random_access_handle_service].
+[link asio.reference.windows__random_access_handle windows::random_access_handle].
[heading Notes]
@@ -117,9 +113,7 @@
[heading See Also]
-[link asio.reference.windows__object_handle windows::object_handle],
-[link asio.reference.windows__basic_object_handle windows::basic_object_handle],
-[link asio.reference.windows__object_handle_service windows::object_handle_service].
+[link asio.reference.windows__object_handle windows::object_handle].
[heading Notes]
diff --git a/asio/src/doc/quickref.xml b/asio/src/doc/quickref.xml
index 7bf99d2..5a8ff55 100644
--- a/asio/src/doc/quickref.xml
+++ b/asio/src/doc/quickref.xml
@@ -45,7 +45,6 @@
<member><link linkend="asio.reference.thread">thread</link></member>
<member><link linkend="asio.reference.thread_pool">thread_pool</link></member>
<member><link linkend="asio.reference.thread_pool__executor_type">thread_pool::executor_type</link></member>
- <member><link linkend="asio.reference.use_future_t">use_future_t</link></member>
<member><link linkend="asio.reference.yield_context">yield_context</link></member>
</simplelist>
</entry>
@@ -63,8 +62,7 @@
<member><link linkend="asio.reference.get_associated_allocator">get_associated_allocator</link></member>
<member><link linkend="asio.reference.get_associated_executor">get_associated_executor</link></member>
<member><link linkend="asio.reference.has_service">has_service</link></member>
- <member><link linkend="asio.reference.make_work">make_work</link></member>
- <member><link linkend="asio.reference.package">package</link></member>
+ <member><link linkend="asio.reference.make_work_guard">make_work_guard</link></member>
<member><link linkend="asio.reference.post">post</link></member>
<member><link linkend="asio.reference.spawn">spawn</link></member>
<member><link linkend="asio.reference.use_service">use_service</link></member>
@@ -76,11 +74,10 @@
<member><link linkend="asio.reference.async_completion">async_completion</link></member>
<member><link linkend="asio.reference.basic_io_object">basic_io_object</link></member>
<member><link linkend="asio.reference.basic_yield_context">basic_yield_context</link></member>
- <member><link linkend="asio.reference.executor_work">executor_work</link></member>
- <member><link linkend="asio.reference.executor_wrapper">executor_wrapper</link></member>
- <member><link linkend="asio.reference.packaged_handler">packaged_handler</link></member>
- <member><link linkend="asio.reference.packaged_token">packaged_token</link></member>
+ <member><link linkend="asio.reference.executor_binder">executor_binder</link></member>
+ <member><link linkend="asio.reference.executor_work_guard">executor_work_guard</link></member>
<member><link linkend="asio.reference.strand">strand</link></member>
+ <member><link linkend="asio.reference.use_future_t">use_future_t</link></member>
</simplelist>
<bridgehead renderas="sect3">Special Values</bridgehead>
<simplelist type="vert" columns="1">
@@ -110,7 +107,7 @@
<member><link linkend="asio.reference.associated_allocator">associated_allocator</link></member>
<member><link linkend="asio.reference.associated_executor">associated_executor</link></member>
<member><link linkend="asio.reference.async_result">async_result</link></member>
- <member><link linkend="asio.reference.handler_type">handler_type</link></member>
+ <member><link linkend="asio.reference.handler_type">handler_type </link> (deprecated)</member>
<member><link linkend="asio.reference.is_executor">is_executor</link></member>
<member><link linkend="asio.reference.uses_executor">uses_executor</link></member>
</simplelist>
@@ -118,6 +115,7 @@
<simplelist type="vert" columns="1">
<member><link linkend="asio.reference.asynchronous_operations">Asynchronous operations</link></member>
<member><link linkend="asio.reference.CompletionHandler">CompletionHandler</link></member>
+ <member><link linkend="asio.reference.ExecutionContext">ExecutionContext</link></member>
<member><link linkend="asio.reference.Executor1">Executor</link></member>
<member><link linkend="asio.reference.Handler">Handler</link></member>
<member><link linkend="asio.reference.Service">Service</link></member>
@@ -144,9 +142,9 @@
<bridgehead renderas="sect3">Classes</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="asio.reference.const_buffer">const_buffer</link></member>
- <member><link linkend="asio.reference.const_buffers_1">const_buffers_1</link></member>
<member><link linkend="asio.reference.mutable_buffer">mutable_buffer</link></member>
- <member><link linkend="asio.reference.mutable_buffers_1">mutable_buffers_1</link></member>
+ <member><link linkend="asio.reference.const_buffers_1">const_buffers_1 </link> (deprecated)</member>
+ <member><link linkend="asio.reference.mutable_buffers_1">mutable_buffers_1 </link> (deprecated)</member>
<member><link linkend="asio.reference.null_buffers">null_buffers</link> (deprecated)</member>
<member><link linkend="asio.reference.streambuf">streambuf</link></member>
</simplelist>
@@ -170,7 +168,7 @@
<member><link linkend="asio.reference.async_write">async_write</link></member>
<member><link linkend="asio.reference.async_write_at">async_write_at</link></member>
<member><link linkend="asio.reference.buffer">buffer</link></member>
- <member><link linkend="asio.reference.buffer_cast">buffer_cast</link></member>
+ <member><link linkend="asio.reference.buffer_cast">buffer_cast </link> (deprecated)</member>
<member><link linkend="asio.reference.buffer_copy">buffer_copy</link></member>
<member><link linkend="asio.reference.buffer_size">buffer_size</link></member>
<member><link linkend="asio.reference.buffers_begin">buffers_begin</link></member>
@@ -199,10 +197,12 @@
<entry valign="top">
<bridgehead renderas="sect3">Type Requirements</bridgehead>
<simplelist type="vert" columns="1">
+ <member><link linkend="asio.reference.read_write_operations">Read and write operations</link></member>
<member><link linkend="asio.reference.AsyncRandomAccessReadDevice">AsyncRandomAccessReadDevice</link></member>
<member><link linkend="asio.reference.AsyncRandomAccessWriteDevice">AsyncRandomAccessWriteDevice</link></member>
<member><link linkend="asio.reference.AsyncReadStream">AsyncReadStream</link></member>
<member><link linkend="asio.reference.AsyncWriteStream">AsyncWriteStream</link></member>
+ <member><link linkend="asio.reference.CompletionCondition">CompletionCondition</link></member>
<member><link linkend="asio.reference.ConstBufferSequence">ConstBufferSequence</link></member>
<member><link linkend="asio.reference.DynamicBufferSequence">DynamicBufferSequence</link></member>
<member><link linkend="asio.reference.MutableBufferSequence">MutableBufferSequence</link></member>
@@ -335,15 +335,21 @@
</simplelist>
<bridgehead renderas="sect3">Type Requirements</bridgehead>
<simplelist type="vert" columns="1">
+ <member><link linkend="asio.reference.synchronous_socket_operations">Synchronous socket operations</link></member>
+ <member><link linkend="asio.reference.asynchronous_socket_operations">Asynchronous socket operations</link></member>
<member><link linkend="asio.reference.AcceptableProtocol">AcceptableProtocol</link></member>
<member><link linkend="asio.reference.AcceptHandler">AcceptHandler</link></member>
- <member><link linkend="asio.reference.ComposedConnectHandler">ComposedConnectHandler</link></member>
+ <member><link linkend="asio.reference.ConnectCondition">ConnectCondition</link></member>
<member><link linkend="asio.reference.ConnectHandler">ConnectHandler</link></member>
<member><link linkend="asio.reference.Endpoint">Endpoint</link></member>
+ <member><link linkend="asio.reference.EndpointSequence">EndpointSequence</link></member>
<member><link linkend="asio.reference.GettableSocketOption">GettableSocketOption</link></member>
<member><link linkend="asio.reference.InternetProtocol">InternetProtocol</link></member>
<member><link linkend="asio.reference.IoControlCommand">IoControlCommand</link></member>
+ <member><link linkend="asio.reference.IteratorConnectHandler">IteratorConnectHandler</link></member>
+ <member><link linkend="asio.reference.MoveAcceptHandler">MoveAcceptHandler</link></member>
<member><link linkend="asio.reference.Protocol">Protocol</link></member>
+ <member><link linkend="asio.reference.RangeConnectHandler">RangeConnectHandler</link></member>
<member><link linkend="asio.reference.ResolveHandler">ResolveHandler</link></member>
<member><link linkend="asio.reference.SettableSocketOption">SettableSocketOption</link></member>
</simplelist>
@@ -378,16 +384,22 @@
<bridgehead renderas="sect3">Classes</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="asio.reference.deadline_timer">deadline_timer</link></member>
+ <member><link linkend="asio.reference.high_resolution_timer">high_resolution_timer</link></member>
+ <member><link linkend="asio.reference.steady_timer">steady_timer</link></member>
+ <member><link linkend="asio.reference.system_timer">system_timer</link></member>
</simplelist>
<bridgehead renderas="sect3">Class Templates</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="asio.reference.basic_deadline_timer">basic_deadline_timer</link></member>
+ <member><link linkend="asio.reference.basic_waitable_timer">basic_waitable_timer</link></member>
<member><link linkend="asio.reference.time_traits_lt__ptime__gt_">time_traits</link></member>
+ <member><link linkend="asio.reference.wait_traits">wait_traits</link></member>
</simplelist>
<bridgehead renderas="sect3">Type Requirements</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="asio.reference.TimeTraits">TimeTraits</link></member>
<member><link linkend="asio.reference.WaitHandler">WaitHandler</link></member>
+ <member><link linkend="asio.reference.WaitTraits">WaitTraits</link></member>
</simplelist>
</entry>
<entry valign="top">
@@ -475,12 +487,12 @@
<member><link linkend="asio.reference.posix__descriptor_base">posix::descriptor_base</link></member>
<member><link linkend="asio.reference.posix__stream_descriptor">posix::stream_descriptor</link></member>
</simplelist>
+ </entry>
+ <entry valign="top">
<bridgehead renderas="sect3">Free Functions</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="asio.reference.local__connect_pair">local::connect_pair</link></member>
</simplelist>
- </entry>
- <entry valign="top">
<bridgehead renderas="sect3">Class Templates</bridgehead>
<simplelist type="vert" columns="1">
<member><link linkend="asio.reference.local__basic_endpoint">local::basic_endpoint</link></member>
diff --git a/asio/src/doc/reference.xsl b/asio/src/doc/reference.xsl
index 6f7d2e9..47a28f3 100644
--- a/asio/src/doc/reference.xsl
+++ b/asio/src/doc/reference.xsl
@@ -37,6 +37,9 @@
[xinclude quickref.xml]
[include requirements/asynchronous_operations.qbk]
+[include requirements/read_write_operations.qbk]
+[include requirements/synchronous_socket_operations.qbk]
+[include requirements/asynchronous_socket_operations.qbk]
[include requirements/AcceptableProtocol.qbk]
[include requirements/AcceptHandler.qbk]
[include requirements/AsyncRandomAccessReadDevice.qbk]
@@ -44,11 +47,15 @@
[include requirements/AsyncReadStream.qbk]
[include requirements/AsyncWriteStream.qbk]
[include requirements/BufferedHandshakeHandler.qbk]
+[include requirements/CompletionCondition.qbk]
[include requirements/CompletionHandler.qbk]
+[include requirements/ConnectCondition.qbk]
[include requirements/ConnectHandler.qbk]
[include requirements/ConstBufferSequence.qbk]
[include requirements/DynamicBufferSequence.qbk]
[include requirements/Endpoint.qbk]
+[include requirements/EndpointSequence.qbk]
+[include requirements/ExecutionContext.qbk]
[include requirements/Executor.qbk]
[include requirements/GettableSerialPortOption.qbk]
[include requirements/GettableSocketOption.qbk]
@@ -56,8 +63,11 @@
[include requirements/HandshakeHandler.qbk]
[include requirements/InternetProtocol.qbk]
[include requirements/IoControlCommand.qbk]
+[include requirements/IoObjectService.qbk]
[include requirements/IteratorConnectHandler.qbk]
+[include requirements/MoveAcceptHandler.qbk]
[include requirements/MutableBufferSequence.qbk]
+[include requirements/ProtoAllocator.qbk]
[include requirements/Protocol.qbk]
[include requirements/RangeConnectHandler.qbk]
[include requirements/ReadHandler.qbk]
@@ -89,7 +99,9 @@
contains(compoundname, 'asio::') and
not(contains(compoundname, '::detail')) and
not(contains(compoundname, '::service::key')) and
- (contains(compoundname, 'packaged_handler') or not(contains(compoundname, '_handler')))">
+ not(contains(compoundname, '_handler')) and
+ not(contains(compoundname, 'thread_function')) and
+ not(contains(compoundname, 'context_impl'))">
<xsl:call-template name="class"/>
</xsl:if>
</xsl:when>
@@ -99,7 +111,8 @@
not(contains(ancestor::*/compoundname, '::service::key')) and
not(contains(ancestor::*/compoundname, '_helper')) and
not(contains(name, '_helper')) and
- not(contains(name, 'io_service_impl'))">
+ not(contains(name, 'thread_function')) and
+ not(contains(name, 'io_context_impl'))">
<xsl:call-template name="namespace-memberdef"/>
</xsl:if>
</xsl:otherwise>
@@ -178,7 +191,7 @@
</xsl:variable>
<xsl:choose>
<xsl:when test="$type='void_or_deduced'">
- <xsl:text>``[link asio.reference.asynchronous_operations.return_type_of_an_initiating_function ['void-or-deduced]]``</xsl:text>
+ <xsl:text>``[link asio.reference.asynchronous_operations.automatic_deduction_of_initiating_function_return_type ['DEDUCED]]``</xsl:text>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="$type"/>
@@ -286,6 +299,18 @@
select="concat(substring-before($name, '~'), '_', substring-after($name, '~'))"/>
</xsl:call-template>
</xsl:when>
+ <xsl:when test="contains($name, ',')">
+ <xsl:call-template name="make-id">
+ <xsl:with-param name="name"
+ select="concat(substring-before($name, ','), '_comma_', substring-after($name, ','))"/>
+ </xsl:call-template>
+ </xsl:when>
+ <xsl:when test="contains($name, '...')">
+ <xsl:call-template name="make-id">
+ <xsl:with-param name="name"
+ select="concat(substring-before($name, '...'), '_ellipsis_', substring-after($name, '...'))"/>
+ </xsl:call-template>
+ </xsl:when>
<xsl:when test="contains($name, ' ')">
<xsl:call-template name="make-id">
<xsl:with-param name="name"
@@ -579,6 +604,13 @@
<xsl:with-param name="text" select="substring-after($text, ']')"/>
</xsl:call-template>
</xsl:when>
+ <xsl:when test="contains($text, '...')">
+ <xsl:value-of select="substring-before($text, '...')"/>
+ <xsl:text>\.\.\.</xsl:text>
+ <xsl:call-template name="escape-name">
+ <xsl:with-param name="text" select="substring-after($text, '...')"/>
+ </xsl:call-template>
+ </xsl:when>
<xsl:otherwise>
<xsl:value-of select="$text"/>
</xsl:otherwise>
@@ -827,7 +859,7 @@
[[Name][Description]]
<xsl:for-each select="
sectiondef[@kind='public-type']/memberdef |
- innerclass[@prot='public' and not(contains(., '_handler'))]" mode="class-table">
+ innerclass[@prot='public' and not(contains(., '_handler')) and not(contains(., 'thread_function'))]" mode="class-table">
<xsl:sort select="concat(name, (.)[not(name)])"/>
[
<xsl:choose>
@@ -1178,6 +1210,11 @@
<xsl:with-param name="text" select="$name"/>
</xsl:call-template>
</xsl:variable>
+ <xsl:variable name="escaped-class-name">
+ <xsl:call-template name="escape-name">
+ <xsl:with-param name="text" select="$class-name"/>
+ </xsl:call-template>
+ </xsl:variable>
<xsl:variable name="id">
<xsl:call-template name="make-id">
<xsl:with-param name="name" select="$name"/>
@@ -1202,9 +1239,12 @@
<xsl:value-of select="$class-name"/>::<xsl:value-of select="$escaped-name"/>]
<xsl:text>[indexterm2 </xsl:text>
+<xsl:text>asio.indexterm.</xsl:text>
+<xsl:number level="multiple" count="*"/>
+<xsl:text>..</xsl:text>
<xsl:value-of select="$escaped-name"/>
<xsl:text>..</xsl:text>
-<xsl:value-of select="$class-name"/>
+<xsl:value-of select="$escaped-class-name"/>
<xsl:text>] </xsl:text>
<xsl:apply-templates select="briefdescription" mode="markup"/><xsl:text>
@@ -1259,9 +1299,12 @@
<xsl:if test="$overload-count = 1">
<xsl:text>[indexterm2 </xsl:text>
+ <xsl:text>asio.indexterm.</xsl:text>
+ <xsl:number level="multiple" count="*"/>
+ <xsl:text>..</xsl:text>
<xsl:value-of select="$escaped-name"/>
<xsl:text>..</xsl:text>
- <xsl:value-of select="$class-name"/>
+ <xsl:value-of select="$escaped-class-name"/>
<xsl:text>] </xsl:text>
</xsl:if>
@@ -1357,6 +1400,9 @@
<xsl:value-of select="$newline"/>
<xsl:for-each select="enumvalue">
<xsl:text>[indexterm2 </xsl:text>
+ <xsl:text>asio.indexterm.</xsl:text>
+ <xsl:number level="multiple" count="*"/>
+ <xsl:text>..</xsl:text>
<xsl:value-of select="name"/>
<xsl:text>..</xsl:text>
<xsl:value-of select="$enum-name"/>
@@ -1427,19 +1473,19 @@
<xsl:when test="declname = 'ByteType'">
<xsl:value-of select="declname"/>
</xsl:when>
- <xsl:when test="declname = 'Clock'">
+ <xsl:when test="declname = 'C'">
<xsl:value-of select="declname"/>
</xsl:when>
- <xsl:when test="declname = 'CompletionCondition'">
+ <xsl:when test="declname = 'Clock'">
<xsl:value-of select="declname"/>
</xsl:when>
<xsl:when test="declname = 'CompletionToken'">
<xsl:value-of select="declname"/>
</xsl:when>
- <xsl:when test="declname = 'ConnectCondition'">
+ <xsl:when test="declname = 'Context_Service'">
<xsl:value-of select="declname"/>
</xsl:when>
- <xsl:when test="declname = 'Context_Service'">
+ <xsl:when test="declname = 'Duration'">
<xsl:value-of select="declname"/>
</xsl:when>
<xsl:when test="declname = 'DatagramSocketService1'">
@@ -1484,6 +1530,9 @@
<xsl:when test="declname = 'PasswordCallback'">
<xsl:value-of select="declname"/>
</xsl:when>
+ <xsl:when test="declname = 'Period'">
+ <xsl:value-of select="declname"/>
+ </xsl:when>
<xsl:when test="declname = 'PodType'">
<xsl:value-of select="declname"/>
</xsl:when>
@@ -1496,6 +1545,12 @@
<xsl:when test="declname = 'RawSocketService1'">
<xsl:value-of select="concat('``[link asio.reference.RawSocketService ', declname, ']``')"/>
</xsl:when>
+ <xsl:when test="declname = 'Rep'">
+ <xsl:value-of select="declname"/>
+ </xsl:when>
+ <xsl:when test="declname = 'Result'">
+ <xsl:value-of select="declname"/>
+ </xsl:when>
<xsl:when test="declname = 'SeqPacketSocketService1'">
<xsl:value-of select="concat('``[link asio.reference.SeqPacketSocketService ', declname, ']``')"/>
</xsl:when>
@@ -1610,6 +1665,9 @@
[section:<xsl:value-of select="$id"/><xsl:text> </xsl:text><xsl:value-of select="$name"/>]
<xsl:text>[indexterm1 </xsl:text>
+<xsl:text>asio.indexterm.</xsl:text>
+<xsl:number level="multiple" count="*"/>
+<xsl:text>..</xsl:text>
<xsl:value-of select="$name"/>
<xsl:text>] </xsl:text>
@@ -1663,6 +1721,9 @@
<xsl:if test="$overload-count = 1">
<xsl:text>[indexterm1 </xsl:text>
+ <xsl:text>asio.indexterm.</xsl:text>
+ <xsl:number level="multiple" count="*"/>
+ <xsl:text>..</xsl:text>
<xsl:value-of select="$name"/>
<xsl:text>] </xsl:text>
</xsl:if>
diff --git a/asio/src/doc/requirements/AcceptableProtocol.qbk b/asio/src/doc/requirements/AcceptableProtocol.qbk
index cb35ddb..3768387 100644
--- a/asio/src/doc/requirements/AcceptableProtocol.qbk
+++ b/asio/src/doc/requirements/AcceptableProtocol.qbk
@@ -7,18 +7,18 @@
[section:AcceptableProtocol Acceptable protocol requirements]
-An acceptable protocol must meet the requirements for a [link
-asio.reference.Protocol protocol] as well as the additional requirements listed
-below.
-
-In the table below, `X` denotes an acceptable protocol class.
+A type `X` meets the `AcceptableProtocol` requirements if it satisfies the
+requirements of [link asio.reference.Protocol `Protocol`] as well as the
+additional requirements listed below.
[table AcceptableProtocol requirements
[[expression] [return type] [assertion/note\npre/post-conditions]]
[
[`X::socket`]
- [`
- [The type of a socket for the protocol.]
+ [A type that satisfies the requirements of `Destructible` (C++Std
+ \[destructible\]) and `MoveConstructible` (C++Std \[moveconstructible\]),
+ and that is publicly and unambiguously derived from `basic_socket<X>`.]
+ []
]
]
diff --git a/asio/src/doc/requirements/AsyncRandomAccessReadDevice.qbk b/asio/src/doc/requirements/AsyncRandomAccessReadDevice.qbk
index 25fed2c..4109c01 100644
--- a/asio/src/doc/requirements/AsyncRandomAccessReadDevice.qbk
+++ b/asio/src/doc/requirements/AsyncRandomAccessReadDevice.qbk
@@ -17,10 +17,9 @@
[table Buffer-oriented asynchronous random-access read device requirements
[[operation] [type] [semantics, pre/post-conditions]]
[
- [`a.get_io_service();`]
- [`io_service&`]
- [Returns the `io_service` object through which the `async_read_some_at`
- handler `h` will be invoked.]
+ [`a.get_executor()`]
+ [A type satisfying the [link asio.reference.Executor1 Executor requirements].]
+ [Returns the associated I/O executor.]
]
[
[`a.async_read_some_at(o, mb, h);`]
diff --git a/asio/src/doc/requirements/AsyncRandomAccessWriteDevice.qbk b/asio/src/doc/requirements/AsyncRandomAccessWriteDevice.qbk
index af8ee36..bd9ecbd 100644
--- a/asio/src/doc/requirements/AsyncRandomAccessWriteDevice.qbk
+++ b/asio/src/doc/requirements/AsyncRandomAccessWriteDevice.qbk
@@ -17,10 +17,9 @@
[table Buffer-oriented asynchronous random-access write device requirements
[[operation] [type] [semantics, pre/post-conditions]]
[
- [`a.get_io_service();`]
- [`io_service&`]
- [Returns the `io_service` object through which the `async_write_some_at`
- handler `h` will be invoked.]
+ [`a.get_executor()`]
+ [A type satisfying the [link asio.reference.Executor1 Executor requirements].]
+ [Returns the associated I/O executor.]
]
[
[`a.async_write_some_at(o, cb, h);`]
diff --git a/asio/src/doc/requirements/AsyncReadStream.qbk b/asio/src/doc/requirements/AsyncReadStream.qbk
index b2da797..0fcd42f 100644
--- a/asio/src/doc/requirements/AsyncReadStream.qbk
+++ b/asio/src/doc/requirements/AsyncReadStream.qbk
@@ -7,48 +7,42 @@
[section:AsyncReadStream Buffer-oriented asynchronous read stream requirements]
-In the table below, `a` denotes an asynchronous read stream object, `mb`
-denotes an object satisfying [link
-asio.reference.MutableBufferSequence mutable buffer sequence]
-requirements, and `h` denotes an object satisfying [link
-asio.reference.ReadHandler read handler] requirements.
+A type `X` meets the `AsyncReadStream` requirements if it satisfies the
+requirements listed below.
-[table Buffer-oriented asynchronous read stream requirements
+In the table below, `a` denotes a value of type `X`, `mb` denotes a (possibly
+const) value satisfying the [link asio.reference.MutableBufferSequence
+`MutableBufferSequence`] requirements, and `t` is a completion token.
+
+[table AsyncReadStream requirements
[[operation] [type] [semantics, pre/post-conditions]]
[
- [`a.get_io_service();`]
- [`io_service&`]
- [Returns the `io_service` object through which the `async_read_some`
- handler `h` will be invoked.]
+ [`a.get_executor()`]
+ [A type satisfying the [link asio.reference.Executor1 Executor requirements].]
+ [Returns the associated I/O executor.]
]
[
- [`a.async_read_some(mb, h);`]
- [`void`]
+ [`a.async_read_some(mb,t)`]
[
- Initiates an asynchronous operation to read one or more bytes of data
- from the stream `a`. The operation is performed via the `io_service`
- object `a.get_io_service()` and behaves according to [link
- asio.reference.asynchronous_operations asynchronous operation]
- requirements.\n
+ The return type is determined according to the requirements for an
+ [link asio.reference.asynchronous_operations asynchronous operation].
+ ]
+ [
+ Meets the requirements for a [link asio.reference.read_write_operations
+ read operation] and an [link asio.reference.asynchronous_operations
+ asynchronous operation] with completion signature `void(error_code ec,
+ size_t n)`.\n
\n
- The mutable buffer sequence `mb` specifies memory where the data should
- be placed. The `async_read_some` operation shall always fill a buffer in
- the sequence completely before proceeding to the next.\n
+ If `buffer_size(mb) > 0`, initiates an asynchronous operation to read one
+ or more bytes of data from the stream `a` into the buffer sequence `mb`.
+ If successful, `ec` is set such that `!ec` is `true`, and `n` is the
+ number of bytes read. If an error occurred, `ec` is set such that `!!ec`
+ is `true`, and `n` is 0. If all data has been read from the stream, and
+ the stream performed an orderly shutdown, `ec` is
+ `stream_errc::eof` and `n` is 0.\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 read operation is invoked,\n
- \n
- whichever comes first.\n
- \n
- 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.
+ If `buffer_size(mb) == 0`, the operation completes immediately. `ec` is
+ set such that `!ec` is `true`, and `n` is 0.
]
]
]
diff --git a/asio/src/doc/requirements/AsyncWriteStream.qbk b/asio/src/doc/requirements/AsyncWriteStream.qbk
index 06cca8c..ee53b23 100644
--- a/asio/src/doc/requirements/AsyncWriteStream.qbk
+++ b/asio/src/doc/requirements/AsyncWriteStream.qbk
@@ -7,47 +7,40 @@
[section:AsyncWriteStream Buffer-oriented asynchronous write stream requirements]
-In the table below, `a` denotes an asynchronous write stream object, `cb`
-denotes an object satisfying [link asio.reference.ConstBufferSequence
-constant buffer sequence] requirements, and `h` denotes an object satisfying
-[link asio.reference.WriteHandler write handler] requirements.
+A type `X` meets the `AsyncWriteStream` requirements if it satisfies the
+requirements listed below.
-[table Buffer-oriented asynchronous write stream requirements
+In the table below, `a` denotes a value of type `X`, `cb` denotes a (possibly
+const) value satisfying the [link asio.reference.ConstBufferSequence
+`ConstBufferSequence`] requirements, and `t` is a completion token.
+
+[table AsyncWriteStream requirements
[[operation] [type] [semantics, pre/post-conditions]]
[
- [`a.get_io_service();`]
- [`io_service&`]
- [Returns the `io_service` object through which the `async_write_some`
- handler `h` will be invoked.]
+ [`a.get_executor()`]
+ [A type satisfying the [link asio.reference.Executor1 Executor requirements].]
+ [Returns the associated I/O executor.]
]
[
- [`a.async_write_some(cb, h);`]
- [`void`]
+ [`a.async_write_some(cb,t)`]
[
- Initiates an asynchronous operation to write one or more bytes of data to
- the stream `a`. The operation is performed via the `io_service` object
- `a.get_io_service()` and behaves according to [link
- asio.reference.asynchronous_operations asynchronous operation]
- requirements.\n
+ The return type is determined according to the requirements for an
+ [link asio.reference.asynchronous_operations asynchronous operation].
+ ]
+ [
+ Meets the requirements for a [link asio.reference.read_write_operations
+ write operation] and an [link asio.reference.asynchronous_operations
+ asynchronous operation] with completion signature `void(error_code ec,
+ size_t n)`.\n
\n
- The constant buffer sequence `cb` specifies memory where the data to be
- written is located. The `async_write_some` operation shall always write a
- buffer in the sequence completely before proceeding to the next.\n
+ If `buffer_size(cb) > 0`, initiates an asynchronous operation to write
+ one or more bytes of data to the stream `a` from the buffer sequence
+ `cb`. If successful, `ec` is set such that `!ec` is `true`, and `n` is
+ the number of bytes written. If an error occurred, `ec` is set such that
+ `!!ec` is `true`, and `n` is 0.\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 write operation is invoked,\n
- \n
- whichever comes first.\n
- \n
- If the total size of all buffers in the sequence `cb` is `0`, the
- asynchronous write operation shall complete immediately and pass `0` as
- the argument to the handler that specifies the number of bytes written.
+ If `buffer_size(cb) == 0`, the operation completes immediately. `ec` is
+ set such that `!ec` is `true`, and `n` is 0.
]
]
]
diff --git a/asio/src/doc/requirements/CompletionCondition.qbk b/asio/src/doc/requirements/CompletionCondition.qbk
new file mode 100644
index 0000000..1575613
--- /dev/null
+++ b/asio/src/doc/requirements/CompletionCondition.qbk
@@ -0,0 +1,42 @@
+[/
+ / Copyright (c) 2003-2016 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:CompletionCondition Completion condition requirements]
+
+A ['completion condition] is a function object that is used with the algorithms
+[link asio.reference.read `read`], [link asio.reference.async_read
+`async_read`], [link asio.reference.write `write`], and [link
+asio.reference.async_write `async_write`] to determine when the algorithm has
+completed transferring data.
+
+A type `X` meets the `CompletionCondition` requirements if it satisfies the
+requirements of `Destructible` (C++Std [destructible]) and
+`CopyConstructible` (C++Std [copyconstructible]), as well as the additional
+requirements listed below.
+
+In the table below, `x` denotes a value of type `X`, `ec` denotes a (possibly
+const) value of type `error_code`, and `n` denotes a (possibly const) value of
+type `size_t`.
+
+[table CompletionCondition requirements
+ [[expression] [return type] [assertion/note\npre/post-condition]]
+ [
+ [`x(ec, n)`]
+ [`size_t`]
+ [
+ Let `n` be the total number of bytes transferred by the read or write
+ algorithm so far.\n
+ \n
+ Returns the maximum number of bytes to be transferred on the next
+ `read_some`, `async_read_some`, `write_some`, or `async_write_some`
+ operation performed by the algorithm. Returns `0` to indicate that the
+ algorithm is complete.
+ ]
+ ]
+]
+
+[endsect]
diff --git a/asio/src/doc/requirements/ConnectCondition.qbk b/asio/src/doc/requirements/ConnectCondition.qbk
new file mode 100644
index 0000000..995398c
--- /dev/null
+++ b/asio/src/doc/requirements/ConnectCondition.qbk
@@ -0,0 +1,34 @@
+[/
+ / Copyright (c) 2003-2016 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:ConnectCondition Connect condition requirements]
+
+A type `X` meets the `ConnectCondition` requirements if it satisfies the
+requirements of `Destructible` (C++Std [destructible]) and
+`CopyConstructible` (C++Std [copyconstructible]), as well as the additional
+requirements listed below.
+
+In the table below, `x` denotes a value of type `X`, `ec` denotes a (possibly
+const) value of type `error_code`, and `ep` denotes a (possibly const) value of
+some type satisfying the [link asio.reference.Endpoint endpoint] requirements.
+
+[table ConnectCondition requirements
+ [[expression] [return type] [assertion/note\npre/post-condition]]
+ [
+ [`x(ec, ep)`]
+ [`bool`]
+ [
+ Returns `true` to indicate that the `connect` or `async_connect`
+ algorithm should attempt a connection to the endpoint `ep`. Otherwise,
+ returns `false` to indicate that the algorithm should not attempt
+ connection to the endpoint `ep`, and should instead skip to the next
+ endpoint in the sequence.
+ ]
+ ]
+]
+
+[endsect]
diff --git a/asio/src/doc/requirements/Endpoint.qbk b/asio/src/doc/requirements/Endpoint.qbk
index 7a14ad8..4940dae 100644
--- a/asio/src/doc/requirements/Endpoint.qbk
+++ b/asio/src/doc/requirements/Endpoint.qbk
@@ -7,84 +7,85 @@
[section:Endpoint Endpoint requirements]
-An endpoint must meet the requirements of `CopyConstructible` types (C++ Std,
-20.1.3), and the requirements of `Assignable` types (C++ Std, 23.1).
+A type `X` meets the `Endpoint` requirements if it satisfies the requirements
+of `Destructible` (C++Std [destructible]), `DefaultConstructible` (C++Std
+[defaultconstructible]), `CopyConstructible` (C++Std [copyconstructible]),
+and `CopyAssignable` (C++Std [copyassignable]), as well as the additional
+requirements listed below.
-In the table below, `X` denotes an endpoint class, `a` denotes a value of type
-`X`, `s` denotes a size in bytes, and `u` denotes an identifier.
+In the table below, `a` denotes a (possibly const) value of type `X`, and `u`
+denotes an identifier.
[table Endpoint requirements
[[expression] [type] [assertion/note\npre/post-conditions]]
[
[`X::protocol_type`]
- [type meeting [link asio.reference.Protocol protocol] requirements]
+ [type meeting [link asio.reference.Protocol `Protocol`] requirements]
[]
]
[
- [`X u;`]
- []
- []
- ]
- [
- [`X();`]
- []
- []
- ]
- [
- [`a.protocol();`]
+ [`a.protocol()`]
[`protocol_type`]
[]
]
+]
+
+In the table below, `a` denotes a (possibly const) value of type `X`, `b`
+denotes a value of type `X`, and `s` denotes a (possibly const) value of a type
+that is convertible to `size_t` and denotes a size in bytes.
+
+[table Endpoint requirements for extensible implementations
+ [[expression] [type] [assertion/note\npre/post-conditions]]
[
- [`a.data();`]
- [a pointer]
+ [`a.data()`]
+ [`const void*`]
[
Returns a pointer suitable for passing as the /address/ argument to
- __POSIX__ functions such as __accept__, __getpeername__, __getsockname__
- and __recvfrom__. The implementation shall perform a
- `reinterpret_cast` on the pointer to convert it to `sockaddr*`.
- ]
- ]
- [
- [`const X& u = a;
- u.data();`]
- [a pointer]
- [
- Returns a pointer suitable for passing as the /address/ argument to
- __POSIX__ functions such as __connect__, or as the /dest_addr/ argument
- to __POSIX__ functions such as __sendto__. The implementation shall
- perform a `reinterpret_cast` on the pointer to convert it to `const
+ functions such as __POSIX__ __connect__, or as the /dest_addr/ argument
+ to functions such as __POSIX__ __sendto__. The implementation shall
+ perform a `static_cast` on the pointer to convert it to `const
sockaddr*`.
]
]
[
- [`a.size();`]
+ [`b.data()`]
+ [`void*`]
+ [
+ Returns a pointer suitable for passing as the /address/ argument to
+ functions such as __POSIX__ __accept__, __getpeername__, __getsockname__
+ and __recvfrom__. The implementation shall perform a `static_cast` on the
+ pointer to convert it to `sockaddr*`.
+ ]
+ ]
+ [
+ [`a.size()`]
[`size_t`]
[
Returns a value suitable for passing as the /address_len/ argument
- to __POSIX__ functions such as __connect__, or as the /dest_len/ argument
- to __POSIX__ functions such as __sendto__, after appropriate integer
+ to functions such as __POSIX__ __connect__, or as the /dest_len/ argument
+ to functions such as __POSIX__ __sendto__, after appropriate integer
conversion has been performed.
]
]
[
- [`a.resize(s);`]
+ [`b.resize(s)`]
[]
[
+ pre: `s >= 0`\n
post: `a.size() == s`\n
- Passed the value contained in the /address_len/ argument to __POSIX__
- functions such as __accept__, __getpeername__, __getsockname__ and
+ Passed the value contained in the /address_len/ argument to functions
+ such as __POSIX__ __accept__, __getpeername__, __getsockname__ and
__recvfrom__, after successful completion of the function. Permitted to
- throw an exception if the protocol associated with the endpoint object `a`
- does not support the specified size.
+ throw an exception if the protocol associated with the endpoint object
+ `a` does not support the specified size.
]
]
[
- [`a.capacity();`]
+ [`a.capacity()`]
[`size_t`]
[
Returns a value suitable for passing as the /address_len/ argument to
- __POSIX__ functions such as __accept__, __getpeername__, __getsockname__
+ functions such as __POSIX__ __accept__, __getpeername__, __getsockname__
and __recvfrom__, after appropriate integer conversion has been performed.
]
]
diff --git a/asio/src/doc/requirements/EndpointSequence.qbk b/asio/src/doc/requirements/EndpointSequence.qbk
new file mode 100644
index 0000000..1e1648e
--- /dev/null
+++ b/asio/src/doc/requirements/EndpointSequence.qbk
@@ -0,0 +1,30 @@
+[/
+ / Copyright (c) 2003-2016 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:EndpointSequence Endpoint sequence requirements]
+
+A type `X` meets the `EndpointSequence` requirements if it satisfies the
+requirements of `Destructible` (C++Std [destructible]) and `CopyConstructible`
+(C++Std [copyconstructible]), as well as the additional requirements listed
+below.
+
+In the table below, `x` denotes a (possibly const) value of type `X`.
+
+[table EndpointSequence requirements
+ [[expression] [return type] [assertion/note\npre/post-condition]]
+ [
+ [`x.begin()`\n
+ `x.end()`]
+ [A type meeting the requirements for forward iterators
+ (C++Std \[forward.iterators\]) whose value type is convertible to
+ a type satisfying the [link asio.reference.Endpoint `Endpoint`]
+ requirements.]
+ [[half_open_range `x.begin()`,`x.end()`] is a valid range.]
+ ]
+]
+
+[endsect]
diff --git a/asio/src/doc/requirements/ExecutionContext.qbk b/asio/src/doc/requirements/ExecutionContext.qbk
new file mode 100644
index 0000000..94d1cd1
--- /dev/null
+++ b/asio/src/doc/requirements/ExecutionContext.qbk
@@ -0,0 +1,36 @@
+[/
+ / Copyright (c) 2003-2016 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:ExecutionContext Execution context requirements]
+
+A type `X` meets the `ExecutionContext` requirements if it is publicly and
+unambiguously derived from `execution_context`, and satisfies the additional
+requirements listed below.
+
+In the table below, `x` denotes a value of type `X`.
+
+[table ExecutionContext requirements
+ [[expression] [return type] [assertion/note\npre/post-condition]]
+ [
+ [`X::executor_type`]
+ [type meeting [link asio.reference.Executor1 `Executor`] requirements]
+ []
+ ]
+ [
+ [`x.~X()`]
+ []
+ [Destroys all unexecuted function objects that were submitted via an
+ executor object that is associated with the execution context.]
+ ]
+ [
+ [`x.get_executor()`]
+ [`X::executor_type`]
+ [Returns an executor object that is associated with the execution context.]
+ ]
+]
+
+[endsect]
diff --git a/asio/src/doc/requirements/Executor.qbk b/asio/src/doc/requirements/Executor.qbk
index 0ff6bac..0754860 100644
--- a/asio/src/doc/requirements/Executor.qbk
+++ b/asio/src/doc/requirements/Executor.qbk
@@ -74,7 +74,7 @@
[
[`x1.context()`]
[`execution_context&`, or `E&` where `E` is a type that satifisfies the
- [link requirements.execution_context `ExecutionContext`] requirements.]
+ [link asio.reference.ExecutionContext `ExecutionContext`] requirements.]
[Shall not exit via an exception.\n
\n
The comparison operators and member functions defined in these
diff --git a/asio/src/doc/requirements/GettableSocketOption.qbk b/asio/src/doc/requirements/GettableSocketOption.qbk
index fffc429..e859a54 100644
--- a/asio/src/doc/requirements/GettableSocketOption.qbk
+++ b/asio/src/doc/requirements/GettableSocketOption.qbk
@@ -7,14 +7,19 @@
[section:GettableSocketOption Gettable socket option requirements]
-In the table below, `X` denotes a socket option class, `a` denotes a value of
-`X`, `p` denotes a value that meets the [link asio.reference.Protocol
-protocol] requirements, and `u` denotes an identifier.
+A type `X` meets the `GettableSocketOption` requirements if it satisfies the
+requirements listed below.
-[table GettableSocketOption requirements
+In the table below, `a` denotes a (possibly const) value of type `X`, `b`
+denotes a value of type `X`, `p` denotes a (possibly const) value that meets
+the [link asio.reference.Protocol `Protocol`] requirements, and `s` denotes a
+(possibly const) value of a type that is convertible to `size_t` and denotes a
+size in bytes.
+
+[table GettableSocketOption requirements for extensible implementations
[[expression] [type] [assertion/note\npre/post-conditions]]
[
- [`a.level(p);`]
+ [`a.level(p)`]
[`int`]
[
Returns a value suitable for passing as the /level/ argument to __POSIX__
@@ -22,7 +27,7 @@
]
]
[
- [`a.name(p);`]
+ [`a.name(p)`]
[`int`]
[
Returns a value suitable for passing as the /option_name/ argument to
@@ -30,15 +35,15 @@
]
]
[
- [`a.data(p);`]
- [a pointer, convertible to `void*`]
+ [`b.data(p)`]
+ [`void*`]
[
Returns a pointer suitable for passing as the /option_value/ argument to
__POSIX__ __getsockopt__ (or equivalent).
]
]
[
- [`a.size(p);`]
+ [`a.size(p)`]
[`size_t`]
[
Returns a value suitable for passing as the /option_len/ argument to
@@ -47,13 +52,13 @@
]
]
[
- [`a.resize(p, s);`]
+ [`b.resize(p,s)`]
[]
[
- post: `a.size(p) == s`.\n
+ post: `b.size(p) == s`.\n
Passed the value contained in the /option_len/ argument to __POSIX__
__getsockopt__ (or equivalent) after successful completion of the
- function. Permitted to throw an exception if the socket option object `a`
+ function. Permitted to throw an exception if the socket option object `b`
does not support the specified size.
]
]
diff --git a/asio/src/doc/requirements/InternetProtocol.qbk b/asio/src/doc/requirements/InternetProtocol.qbk
index 9c1dae6..70ab668 100644
--- a/asio/src/doc/requirements/InternetProtocol.qbk
+++ b/asio/src/doc/requirements/InternetProtocol.qbk
@@ -7,12 +7,12 @@
[section:InternetProtocol Internet protocol requirements]
-An internet protocol must meet the requirements for a [link
-asio.reference.Protocol protocol] as well as the additional
-requirements listed below.
+A type `X` meets the `InternetProtocol` requirements if it satisfies the
+requirements of [link asio.reference.AcceptableProtocol `AcceptableProtocol`],
+as well as the additional requirements listed below.
-In the table below, `X` denotes an internet protocol class, `a` denotes a value
-of type `X`, and `b` denotes a value of type `X`.
+In the table below, `a` denotes a (possibly const) value of type `X`, and `b`
+denotes a (possibly const) value of type `X`.
[table InternetProtocol requirements
[[expression] [return type] [assertion/note\npre/post-conditions]]
@@ -34,7 +34,8 @@
[
[`a == b`]
[convertible to `bool`]
- [Returns whether two protocol objects are equal.]
+ [Returns `true` if `a` and `b` represent the same IP protocol version,
+ otherwise `false`.]
]
[
[`a != b`]
diff --git a/asio/src/doc/requirements/IoControlCommand.qbk b/asio/src/doc/requirements/IoControlCommand.qbk
index 428d726..8809335 100644
--- a/asio/src/doc/requirements/IoControlCommand.qbk
+++ b/asio/src/doc/requirements/IoControlCommand.qbk
@@ -7,13 +7,16 @@
[section:IoControlCommand I/O control command requirements]
-In the table below, `X` denotes an I/O control command class, `a` denotes a
-value of `X`, and `u` denotes an identifier.
+A type `X` meets the `IoControlCommand` requirements if it satisfies the
+requirements listed below.
-[table IoControlCommand requirements
+In the table below, `a` denotes a (possibly const) value of type `X`, and `b`
+denotes a value of type `X`.
+
+[table IoControlCommand requirements for extensible implementations
[[expression] [type] [assertion/note\npre/post-conditions]]
[
- [`a.name();`]
+ [`a.name()`]
[`int`]
[
Returns a value suitable for passing as the /request/ argument to
@@ -21,8 +24,8 @@
]
]
[
- [`a.data();`]
- [a pointer, convertible to `void*`]
+ [`b.data()`]
+ [`void*`]
[
]
]
diff --git a/asio/src/doc/requirements/ProtoAllocator.qbk b/asio/src/doc/requirements/ProtoAllocator.qbk
new file mode 100644
index 0000000..2d318f2
--- /dev/null
+++ b/asio/src/doc/requirements/ProtoAllocator.qbk
@@ -0,0 +1,19 @@
+[/
+ / Copyright (c) 2003-2016 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:ProtoAllocator Proto-allocator requirements]
+
+A type `A` meets the proto-allocator requirements if `A` is `CopyConstructible`
+(C++Std [copyconstructible]), `Destructible` (C++Std [destructible]), and
+`allocator_traits<A>::rebind_alloc<U>` meets the allocator requirements (C++Std
+[allocator.requirements]), where `U` is an object type. [inline_note For
+example, `std::allocator<void>` meets the proto-allocator requirements but not
+the allocator requirements.] No constructor, comparison operator, copy
+operation, move operation, or swap operation on these types shall exit via an
+exception.
+
+[endsect]
diff --git a/asio/src/doc/requirements/Protocol.qbk b/asio/src/doc/requirements/Protocol.qbk
index 15e983c..7a55d14 100644
--- a/asio/src/doc/requirements/Protocol.qbk
+++ b/asio/src/doc/requirements/Protocol.qbk
@@ -7,11 +7,10 @@
[section:Protocol Protocol requirements]
-A protocol must meet the requirements of `CopyConstructible` types (C++ Std,
-20.1.3), and the requirements of `Assignable` types (C++ Std, 23.1).
-
-In the table below, `X` denotes a protocol class, and `a` denotes a value of
-`X`.
+A type `X` meets the `Protocol` requirements if it satisfies the requirements
+of `Destructible` (C++Std [destructible]), `CopyConstructible` (C++Std
+[copyconstructible]), and `CopyAssignable` (C++Std [copyassignable]), as well
+as the additional requirements listed below.
[table Protocol requirements
[[expression] [return type] [assertion/note\npre/post-conditions]]
@@ -20,6 +19,12 @@
[type meeting [link asio.reference.Endpoint endpoint] requirements]
[]
]
+]
+
+In the table below, `a` denotes a (possibly const) value of type `X`.
+
+[table Protocol requirements for extensible implementations
+ [[expression] [return type] [assertion/note\npre/post-conditions]]
[
[`a.family()`]
[`int`]
diff --git a/asio/src/doc/requirements/ResolveHandler.qbk b/asio/src/doc/requirements/ResolveHandler.qbk
index be7b334..0ba9385 100644
--- a/asio/src/doc/requirements/ResolveHandler.qbk
+++ b/asio/src/doc/requirements/ResolveHandler.qbk
@@ -12,7 +12,7 @@
expression `h(ec, r)`, where `ec` is an lvalue of type `const error_code` and
`r` is an lvalue of type `const ip::basic_resolver_results<InternetProtocol>`.
`InternetProtocol` is the template parameter of the [link
-asio.reference.ip__resolver_service `resolver_service`] which is used to
+asio.reference.ip__basic_resolver `ip::basic_resolver<>`] which is used to
initiate the asynchronous operation.
[heading Examples]
diff --git a/asio/src/doc/requirements/Service.qbk b/asio/src/doc/requirements/Service.qbk
index 50a8bda..24a1ae5 100644
--- a/asio/src/doc/requirements/Service.qbk
+++ b/asio/src/doc/requirements/Service.qbk
@@ -7,27 +7,34 @@
[section:Service Service requirements]
-A class is a service if it is publicly derived from another service, or if it
-is a class derived from `io_service::service` and contains a
-publicly-accessible declaration as follows:
+A class is a ['service] if it is publicly and unambiguously derived from
+`execution_context::service`, or if it is publicly and unambiguously derived
+from another service. For a service `S`, `S::key_type` shall be valid and
+denote a type (C++Std [temp.deduct]), `is_base_of_v<typename S::key_type, S>`
+shall be `true`, and `S` shall satisfy the `Destructible` requirements (C++Std
+[destructible]).
- static io_service::id id;
+The first parameter of all service constructors shall be an lvalue reference to
+`execution_context`. This parameter denotes the `execution_context` object that
+represents a set of services, of which the service object will be a member.
+[inline_note These constructors may be called by the `make_service` function.]
-All services define a one-argument constructor that takes a reference to the
-`io_service` object that owns the service. This constructor is /explicit/,
-preventing its participation in automatic conversions. For example:
+A service shall provide an explicit constructor with a single parameter of
+lvalue reference to `execution_context`. [inline_note This constructor may be
+called by the `use_service` function.]
- class my_service : public io_service::service
+ class my_service : public execution_context::service
{
public:
- static io_service::id id;
- explicit my_service(io_service& ios);
+ typedef my_service key_type;
+ explicit my_service(execution_context& ctx);
+ my_service(execution_context& ctx, int some_value);
private:
- virtual void shutdown_service();
+ virtual void shutdown() noexcept override;
...
};
-A service's `shutdown_service` member function must cause all copies of
-user-defined handler objects that are held by the service to be destroyed.
+A service's `shutdown` member function shall destroy all copies of user-defined
+function objects that are held by the service.
[endsect]
diff --git a/asio/src/doc/requirements/SettableSocketOption.qbk b/asio/src/doc/requirements/SettableSocketOption.qbk
index b63d9d2..162c0a9 100644
--- a/asio/src/doc/requirements/SettableSocketOption.qbk
+++ b/asio/src/doc/requirements/SettableSocketOption.qbk
@@ -7,14 +7,17 @@
[section:SettableSocketOption Settable socket option requirements]
-In the table below, `X` denotes a socket option class, `a` denotes a value of
-`X`, `p` denotes a value that meets the [link asio.reference.Protocol
-protocol] requirements, and `u` denotes an identifier.
+A type `X` meets the `SettableSocketOption` requirements if it satisfies the
+requirements listed below.
-[table SettableSocketOption requirements
+In the table below, `a` denotes a (possibly const) value of type `X`, `p`
+denotes a (possibly const) value that meets the [link asio.reference.Protocol
+`Protocol`] requirements, and `u` denotes an identifier.
+
+[table SettableSocketOption requirements for extensible implementations
[[expression] [type] [assertion/note\npre/post-conditions]]
[
- [`a.level(p);`]
+ [`a.level(p)`]
[`int`]
[
Returns a value suitable for passing as the /level/ argument to __POSIX__
@@ -22,7 +25,7 @@
]
]
[
- [`a.name(p);`]
+ [`a.name(p)`]
[`int`]
[
Returns a value suitable for passing as the /option_name/ argument to
@@ -30,16 +33,15 @@
]
]
[
- [`const X& u = a;
- u.data(p);`]
- [a pointer, convertible to `const void*`]
+ [`a.data(p)`]
+ [`const void*`]
[
Returns a pointer suitable for passing as the /option_value/ argument to
__POSIX__ __setsockopt__ (or equivalent).
]
]
[
- [`a.size(p);`]
+ [`a.size(p)`]
[`size_t`]
[
Returns a value suitable for passing as the /option_len/ argument to
diff --git a/asio/src/doc/requirements/SyncReadStream.qbk b/asio/src/doc/requirements/SyncReadStream.qbk
index 679a700..48d3c23 100644
--- a/asio/src/doc/requirements/SyncReadStream.qbk
+++ b/asio/src/doc/requirements/SyncReadStream.qbk
@@ -7,40 +7,33 @@
[section:SyncReadStream Buffer-oriented synchronous read stream requirements]
-In the table below, `a` denotes a synchronous read stream object, `mb` denotes
-an object satisfying [link asio.reference.MutableBufferSequence
-mutable buffer sequence] requirements, and `ec` denotes an object of type
+A type `X` meets the `SyncReadStream` requirements if it satisfies the
+requirements listed below.
+
+In the table below, `a` denotes a value of type `X`, `mb` denotes a (possibly
+const) value satisfying the [link asio.reference.MutableBufferSequence
+`MutableBufferSequence`] requirements, and `ec` denotes an object of type
`error_code`.
-[table Buffer-oriented synchronous read stream requirements
+[table SyncReadStream requirements
[[operation] [type] [semantics, pre/post-conditions]]
[
- [`a.read_some(mb);`]
- [`size_t`]
- [Equivalent to:
- ``
- error_code ec;
- size_t s = a.read_some(mb, ec);
- if (ec) throw system_error(ec);
- return s;
- ``]
- ]
- [
- [`a.read_some(mb, ec);`]
+ [`a.read_some(mb)`\n
+ `a.read_some(mb,ec)`]
[`size_t`]
[
- Reads one or more bytes of data from the stream `a`.\n
+ Meets the requirements for a [link asio.reference.read_write_operations
+ read operation].\n
\n
- The mutable buffer sequence `mb` specifies memory where the data should
- be placed. The `read_some` operation shall always fill a buffer in the
- sequence completely before proceeding to the next.\n
+ If `buffer_size(mb) > 0`, reads one or more bytes of data from the stream
+ `a` into the buffer sequence `mb`. If successful, sets `ec` such that
+ `!ec` is `true`, and returns the number of bytes read. If an error
+ occurred, sets `ec` such that `!!ec` is `true`, and returns 0. If all
+ data has been read from the stream, and the stream performed an orderly
+ shutdown, sets `ec` to `stream_errc::eof` and returns 0.\n
\n
- If successful, returns the number of bytes read and sets `ec` such that
- `!ec` is true. If an error occurred, returns `0` and sets `ec` such that
- `!!ec` is true.\n
- \n
- If the total size of all buffers in the sequence `mb` is `0`, the
- function shall return `0` immediately.
+ If `buffer_size(mb) == 0`, the operation shall not block. Sets `ec` such
+ that `!ec` is `true`, and returns 0.
]
]
]
diff --git a/asio/src/doc/requirements/SyncWriteStream.qbk b/asio/src/doc/requirements/SyncWriteStream.qbk
index 570bd93..713050c 100644
--- a/asio/src/doc/requirements/SyncWriteStream.qbk
+++ b/asio/src/doc/requirements/SyncWriteStream.qbk
@@ -7,39 +7,31 @@
[section:SyncWriteStream Buffer-oriented synchronous write stream requirements]
-In the table below, `a` denotes a synchronous write stream object, `cb` denotes
-an object satisfying [link asio.reference.ConstBufferSequence constant
-buffer sequence] requirements, and `ec` denotes an object of type `error_code`.
+A type `X` meets the `SyncWriteStream` requirements if it satisfies the
+requirements listed below.
-[table Buffer-oriented synchronous write stream requirements
+In the table below, `a` denotes a value of type `X`, `cb` denotes a (possibly
+const) value satisfying the [link asio.reference.ConstBufferSequence
+`ConstBufferSequence`] requirements, and `ec` denotes an object of type
+`error_code`.
+
+[table SyncWriteStream requirements
[[operation] [type] [semantics, pre/post-conditions]]
[
- [`a.write_some(cb);`]
- [`size_t`]
- [Equivalent to:
- ``
- error_code ec;
- size_t s = a.write_some(cb, ec);
- if (ec) throw system_error(ec);
- return s;
- ``]
- ]
- [
- [`a.write_some(cb, ec);`]
+ [`a.write_some(cb)`\n
+ `a.write_some(cb,ec)`]
[`size_t`]
[
- Writes one or more bytes of data to the stream `a`.\n
+ Meets the requirements for a [link asio.reference.read_write_operations
+ write operation].\n
\n
- The constant buffer sequence `cb` specifies memory where the data to be
- written is located. The `write_some` operation shall always write a
- buffer in the sequence completely before proceeding to the next.\n
+ If `buffer_size(cb) > 0`, writes one or more bytes of data to the stream
+ `a` from the buffer sequence `cb`. If successful, sets `ec` such that
+ `!ec` is `true`, and returns the number of bytes written. If an error
+ occurred, sets `ec` such that `!!ec` is `true`, and returns 0.\n
\n
- If successful, returns the number of bytes written and sets `ec` such
- that `!ec` is true. If an error occurred, returns `0` and sets `ec` such
- that `!!ec` is true.\n
- \n
- If the total size of all buffers in the sequence `cb` is `0`, the
- function shall return `0` immediately.
+ If `buffer_size(cb) == 0`, the operation shall not block. Sets `ec` such
+ that `!ec` is `true`, and returns 0.
]
]
]
diff --git a/asio/src/doc/requirements/WaitTraits.qbk b/asio/src/doc/requirements/WaitTraits.qbk
index dc16660..13eb748 100644
--- a/asio/src/doc/requirements/WaitTraits.qbk
+++ b/asio/src/doc/requirements/WaitTraits.qbk
@@ -7,27 +7,44 @@
[section:WaitTraits Wait traits requirements]
-In the table below, `X` denotes a wait traits class for clock type `Clock`,
-where `Clock` meets the C++11 type requirements for a clock, `t` denotes a
-value of type `Clock::time_point`, and `d` denotes a value of type
+The `basic_waitable_timer` template uses wait traits to allow programs to
+customize `wait` and `async_wait` behavior.
+[inline_note Possible uses of wait traits include:\n
+[mdash] To enable timers based on non-realtime clocks.\n
+[mdash] Determining how quickly wallclock-based timers respond to system time
+changes.\n
+[mdash] Correcting for errors or rounding timeouts to boundaries.\n
+[mdash] Preventing duration overflow. That is, a program may set a timer's
+expiry `e` to be `Clock::max()` (meaning never reached) or `Clock::min()`
+(meaning always in the past). As a result, computing the duration until timer
+expiry as `e - Clock::now()` may cause overflow.]
+
+For a type `Clock` meeting the `Clock` requirements (C++Std
+[time.clock.req]), a type `X` meets the `WaitTraits` requirements if it
+satisfies the requirements listed below.
+
+In the table below, `t` denotes a (possibly const) value of type
+`Clock::time_point`; and `d` denotes a (possibly const) value of type
`Clock::duration`.
[table WaitTraits requirements
[[expression] [return type] [assertion/note\npre/post-condition]]
[
- [`X::to_wait_duration(d);`]
+ [`X::to_wait_duration(d)`]
[`Clock::duration`]
[
- Returns the maximum duration to be used for an individual,
- implementation-defined wait operation for the duration `d`.
+ Returns a `Clock::duration` value to be used in a `wait` or `async_wait`
+ operation. [inline_note The return value is typically representative of
+ the duration `d`.]
]
]
[
- [`X::to_wait_duration(t);`]
+ [`X::to_wait_duration(t)`]
[`Clock::duration`]
[
- Returns the maximum duration to be used for an individual,
- implementation-defined wait operation until the time point `t`.
+ Returns a `Clock::duration` value to be used in a `wait` or `async_wait`
+ operation. [inline_note The return value is typically representative of
+ the duration from `Clock::now()` until the time point `t`.]
]
]
]
diff --git a/asio/src/doc/requirements/asynchronous_operations.qbk b/asio/src/doc/requirements/asynchronous_operations.qbk
index 37b4e71..40ccccf 100644
--- a/asio/src/doc/requirements/asynchronous_operations.qbk
+++ b/asio/src/doc/requirements/asynchronous_operations.qbk
@@ -7,211 +7,275 @@
[section:asynchronous_operations Requirements on asynchronous operations]
-In Asio, an asynchronous operation is initiated by a function that is
-named with the prefix `async_`. These functions will be referred to as
-['initiating functions].
+This section uses the names `Alloc1`, `Alloc2`, `alloc1`, `alloc2`, `Args`,
+`CompletionHandler`, `completion_handler`, `Executor1`, `Executor2`, `ex1`,
+`ex2`, `f`, [^['i]], [^['N]], `Signature`, `token`, [^T[sub ['i]]], [^t[sub
+['i]]], `work1`, and `work2` as placeholders for specifying the requirements
+below.
-All initiating functions in Asio take a function object meeting [link
-asio.reference.Handler handler] requirements as the final parameter.
-These handlers accept as their first parameter an lvalue of type `const
-error_code`.
+[section General asynchronous operation concepts]
-Implementations of asynchronous operations in Asio may call the
-application programming interface (API) provided by the operating system. If
-such an operating system API call results in an error, the handler will be
-invoked with a `const error_code` lvalue that evaluates to true. Otherwise the
-handler will be invoked with a `const error_code` lvalue that evaluates to
-false.
+An ['initiating function] is a function which may be called to start an
+asynchronous operation. A ['completion handler] is a function object that will
+be invoked, at most once, with the result of the asynchronous operation.
-Unless otherwise noted, when the behaviour of an asynchronous operation is
-defined "as if" implemented by a __POSIX__ function, the handler will be
-invoked with a value of type `error_code` that corresponds to the failure
-condition described by __POSIX__ for that function, if any. Otherwise the
-handler will be invoked with an implementation-defined `error_code` value that
-reflects the operating system error.
+The lifecycle of an asynchronous operation is comprised of the following events
+and phases:
-Asynchronous operations will not fail with an error condition that indicates
-interruption by a signal (__POSIX__ `EINTR`). Asynchronous operations will not
-fail with any error condition associated with non-blocking operations
-(__POSIX__ `EWOULDBLOCK`, `EAGAIN` or `EINPROGRESS`; __Windows__
-`WSAEWOULDBLOCK` or `WSAEINPROGRESS`).
+[mdash] Event 1: The asynchronous operation is started by a call to the
+initiating function.
-All asynchronous operations have an associated `io_service` object. Where the
-initiating function is a member function, the associated `io_service` is that
-returned by the `get_io_service()` member function on the same object. Where the
-initiating function is not a member function, the associated `io_service` is
-that returned by the `get_io_service()` member function of the first argument to
-the initiating function.
+[mdash] Phase 1: The asynchronous operation is now ['outstanding].
-Arguments to initiating functions will be treated as follows:
+[mdash] Event 2: The externally observable side effects of the asynchronous
+operation, if any, are fully established. The completion handler is submitted
+to an executor.
-[mdash] If the parameter is declared as a const reference or by-value, the
-program is not required to guarantee the validity of the argument after the
-initiating function completes. The implementation may make copies of the
-argument, and all copies will be destroyed no later than immediately after
-invocation of the handler.
+[mdash] Phase 2: The asynchronous operation is now ['completed].
-[mdash] If the parameter is declared as a non-const reference, const pointer or
-non-const pointer, the program must guarantee the validity of the argument
-until the handler is invoked.
-
-The library implementation is only permitted to make calls to an initiating
-function's arguments' copy constructors or destructors from a thread that
-satisfies one of the following conditions:
-
-[mdash] The thread is executing any member function of the associated
-`io_service` object.
-
-[mdash] The thread is executing the destructor of the associated `io_service`
-object.
-
-[mdash] The thread is executing one of the `io_service` service access
-functions `use_service`, `add_service` or `has_service`, where the first
-argument is the associated `io_service` object.
-
-[mdash] The thread is executing any member function, constructor or destructor
-of an object of a class defined in this clause, where the object's
-`get_io_service()` member function returns the associated `io_service` object.
-
-[mdash] The thread is executing any function defined in this clause, where any
-argument to the function has an `get_io_service()` member function that returns
-the associated `io_service` object.
-
-[blurb Asio may use one or more hidden threads to emulate asynchronous
-functionality. The above requirements are intended to prevent these hidden
-threads from making calls to program code. This means that a program can, for
-example, use thread-unsafe reference counting in handler objects, provided the
-program ensures that all calls to an `io_service` and related objects occur
-from the one thread.]
-
-The `io_service` object associated with an asynchronous operation will have
-unfinished work, as if by maintaining the existence of one or more objects of
-class `io_service::work` constructed using the `io_service`, until immediately
-after the handler for the asynchronous operation has been invoked.
-
-When an asynchronous operation is complete, the handler for the operation will
-be invoked as if by:
-
-# Constructing a bound completion handler `bch` for the handler, as described
- below.
-
-# Calling `ios.post(bch)` to schedule the handler for deferred invocation,
- where `ios` is the associated `io_service`.
-
-This implies that the handler must not be called directly from within
-the initiating function, even if the asynchronous operation completes
-immediately.
-
-A bound completion handler is a handler object that contains a copy of a
-user-supplied handler, where the user-supplied handler accepts one or more
-arguments. The bound completion handler does not accept any arguments, and
-contains values to be passed as arguments to the user-supplied handler. The
-bound completion handler forwards the `asio_handler_allocate()`,
-`asio_handler_deallocate()`, and `asio_handler_invoke()` calls to the
-corresponding functions for the user-supplied handler. A bound completion
-handler meets the requirements for a [link
-asio.reference.CompletionHandler completion handler].
-
-For example, a bound completion handler for a `ReadHandler` may be implemented
-as follows:
-
- template<class ReadHandler>
- struct bound_read_handler
- {
- bound_read_handler(ReadHandler handler, const error_code& ec, size_t s)
- : handler_(handler), ec_(ec), s_(s)
- {
- }
-
- void operator()()
- {
- handler_(ec_, s_);
- }
-
- ReadHandler handler_;
- const error_code ec_;
- const size_t s_;
- };
-
- template<class ReadHandler>
- void* asio_handler_allocate(size_t size,
- bound_read_handler<ReadHandler>* this_handler)
- {
- using asio::asio_handler_allocate;
- return asio_handler_allocate(size, &this_handler->handler_);
- }
-
- template<class ReadHandler>
- void asio_handler_deallocate(void* pointer, std::size_t size,
- bound_read_handler<ReadHandler>* this_handler)
- {
- using asio::asio_handler_deallocate;
- asio_handler_deallocate(pointer, size, &this_handler->handler_);
- }
-
- template<class F, class ReadHandler>
- void asio_handler_invoke(const F& f,
- bound_read_handler<ReadHandler>* this_handler)
- {
- using asio::asio_handler_invoke;
- asio_handler_invoke(f, &this_handler->handler_);
- }
-
-If the thread that initiates an asynchronous operation terminates before the
-associated handler is invoked, the behaviour is implementation-defined.
-Specifically, on __Windows__ versions prior to Vista, unfinished operations are
-cancelled when the initiating thread exits.
-
-The handler argument to an initiating function defines a handler identity. That
-is, the original handler argument and any copies of the handler argument will
-be considered equivalent. If the implementation needs to allocate storage for
-an asynchronous operation, the implementation will perform
-`asio_handler_allocate(size, &h)`, where `size` is the required size in bytes,
-and `h` is the handler. The implementation will perform
-`asio_handler_deallocate(p, size, &h)`, where `p` is a pointer to the storage,
-to deallocate the storage prior to the invocation of the handler via
-`asio_handler_invoke`. Multiple storage blocks may be allocated for a single
+[mdash] Event 3: The completion handler is called with the result of the
asynchronous operation.
-[heading Return type of an initiating function]
+In this library, all functions with the prefix `async_` are initiating
+functions.
-By default, initiating functions return `void`. This is always the case when
-the handler is a function pointer, C++11 lambda, or a function object produced
-by `boost::bind` or `std::bind`.
+[endsect]
-For other types, the return type may be customised via a two-step process:
+[section:completion_token Completion tokens and handlers]
-# A specialisation of the [link asio.reference.handler_type `handler_type`]
-template, which is used to determine the true handler type based on the
-asynchronous operation's handler's signature.
+Initiating functions:
-# A specialisation of the [link asio.reference.async_result `async_result`]
-template, which is used both to determine the return type and to extract the
-return value from the handler.
+[mdash] are function templates with template parameter `CompletionToken`;
-These two templates have been specialised to provide support for [link
-asio.overview.core.spawn stackful coroutines] and the C++11 `std::future`
-class.
+[mdash] accept, as the final parameter, a ['completion token] object `token`
+of type `CompletionToken`;
-As an example, consider what happens when enabling `std::future` support by
-using the `asio::use_future` special value, as in:
+[mdash] specify a ['completion signature], which is a call signature (C++Std
+[func.def]) `Signature` that determines the arguments to the completion
+handler.
- std::future<std::size_t> length =
- my_socket.async_read_some(my_buffer, asio::use_future);
+An initiating function determines the type `CompletionHandler` of its
+completion handler function object by performing `typename
+async_result<decay_t<CompletionToken>, Signature>::completion_handler_type`.
+The completion handler object `completion_handler` is initialized with
+`forward<CompletionToken>(token)`. [inline_note No other requirements are
+placed on the type `CompletionToken`.]
-When a handler signature has the form:
+The type `CompletionHandler` must satisfy the requirements of `Destructible`
+(C++Std [destructible]) and `MoveConstructible` (C++Std
+[moveconstructible]), and be callable with the specified call signature.
- void handler(error_code ec, result_type result);
+In this library, all initiating functions specify a ['Completion signature]
+element that defines the call signature `Signature`. The ['Completion
+signature] elements in this Technical Specification have named parameters, and
+the results of an asynchronous operation are specified in terms of these names.
-the initiating function returns a `std::future` templated on `result_type`. In
-the above `async_read_some` example, this is `std::size_t`. If the asynchronous
-operation fails, the `error_code` is converted into a `system_error` exception
-and passed back to the caller through the future.
+[endsect]
-Where a handler signature has the form:
+[section Automatic deduction of initiating function return type]
- void handler(error_code ec);
+The return type of an initiating function is `typename
+async_result<decay_t<CompletionToken>, Signature>::return_type`.
-the initiating function instead returns `std::future<void>`.
+For the sake of exposition, this library sometimes annotates functions with a
+return type ['[^DEDUCED]]. For every function declaration that returns
+['[^DEDUCED]], the meaning is equivalent to specifying the return type as
+`typename async_result<decay_t<CompletionToken>, Signature>::return_type`.
+
+[endsect]
+
+[section Production of initiating function return value]
+
+An initiating function produces its return type as follows:
+
+[mdash] constructing an object `result` of type
+`async_result<decay_t<CompletionToken>, Signature>`, initialized as
+`result(completion_handler)`; and
+
+[mdash] using `result.get()` as the operand of the return statement.
+
+\[['Example:] Given an asynchronous operation with ['Completion signature]
+`void(R1 r1, R2 r2)`, an initiating function meeting these requirements may be
+implemented as follows:
+
+ template<class CompletionToken>
+ auto async_xyz(T1 t1, T2 t2, CompletionToken&& token)
+ {
+ typename async_result<decay_t<CompletionToken>, void(R1, R2)>::completion_handler_type
+ completion_handler(forward<CompletionToken>(token));
+
+ async_result<decay_t<CompletionToken>, void(R1, R2)> result(completion_handler);
+
+ // initiate the operation and cause completion_handler to be invoked with
+ // the result
+
+ return result.get();
+ }
+
+For convenience, initiating functions may be implemented using the
+`async_completion` template:
+
+ template<class CompletionToken>
+ auto async_xyz(T1 t1, T2 t2, CompletionToken&& token)
+ {
+ async_completion<CompletionToken, void(R1, R2)> init(token);
+
+ // initiate the operation and cause init.completion_handler to be invoked
+ // with the result
+
+ return init.result.get();
+ }
+
+'''—'''['end example]\]
+
+[endsect]
+
+[section Lifetime of initiating function arguments]
+
+Unless otherwise specified, the lifetime of arguments to initiating functions
+shall be treated as follows:
+
+[mdash] If the parameter has a pointer type or has a type of lvalue reference
+to non-const, the implementation may assume the validity of the pointee or
+referent, respectively, until the completion handler is invoked. [inline_note
+In other words, the program must guarantee the validity of the argument until
+the completion handler is invoked.]
+
+[mdash] Otherwise, the implementation must not assume the validity of the
+argument after the initiating function completes. [inline_note In other words,
+the program is not required to guarantee the validity of the argument after the
+initiating function completes.] The implementation may make copies of the
+argument, and all copies shall be destroyed no later than immediately after
+invocation of the completion handler.
+
+[endsect]
+
+[section Non-blocking requirements on initiating functions]
+
+An initiating function shall not block (C++Std [defns.block]) the calling
+thread pending completion of the outstanding operation.
+
+[std_note Initiating functions may still block the calling thread for other
+reasons. For example, an initiating function may lock a mutex in order to
+synchronize access to shared data.]
+
+[endsect]
+
+[section Associated executor]
+
+Certain objects that participate in asynchronous operations have an
+['associated executor]. These are obtained as specified below.
+
+[endsect]
+
+[section I/O executor]
+
+An asynchronous operation has an associated executor satisfying the [link
+asio.reference.Executor1 `Executor`] requirements. If not otherwise specified by
+the asynchronous operation, this associated executor is an object of type
+`system_executor`.
+
+All asynchronous operations in this library have an associated executor object
+that is determined as follows:
+
+[mdash] If the initiating function is a member function, the associated
+executor is that returned by the `get_executor` member function on the same
+object.
+
+[mdash] If the initiating function is not a member function, the associated
+executor is that returned by the `get_executor` member function of the first
+argument to the initiating function.
+
+Let `Executor1` be the type of the associated executor. Let `ex1` be a value of
+type `Executor1`, representing the associated executor object obtained as
+described above.
+
+[endsect]
+
+[section Completion handler executor]
+
+A completion handler object of type `CompletionHandler` has an associated
+executor of type `Executor2` satisfying the [link asio.reference.Executor1
+Executor requirements]. The type `Executor2` is
+`associated_executor_t<CompletionHandler, Executor1>`. Let `ex2` be a value of
+type `Executor2` obtained by performing
+`get_associated_executor(completion_handler, ex1)`.
+
+[endsect]
+
+[section Outstanding work]
+
+Until the asynchronous operation has completed, the asynchronous operation
+shall maintain:
+
+[mdash] an object `work1` of type `executor_work_guard<Executor1>`, initialized
+as `work1(ex1)`, and where `work1.owns_work() == true`; and
+
+[mdash] an object `work2` of type `executor_work_guard<Executor2>`, initialized
+as `work2(ex2)`, and where `work2.owns_work() == true`.
+
+[endsect]
+
+[section Allocation of intermediate storage]
+
+Asynchronous operations may allocate memory. [inline_note Such as a data
+structure to store copies of the `completion_handler` object and the initiating
+function's arguments.]
+
+Let `Alloc1` be a type, satisfying the [link asio.reference.ProtoAllocator
+`ProtoAllocator`] requirements, that represents the asynchronous operation's
+default allocation strategy. [inline_note Typically `std::allocator<void>`.]
+Let `alloc1` be a value of type `Alloc1`.
+
+A completion handler object of type `CompletionHandler` has an associated
+allocator object `alloc2` of type `Alloc2` satisfying the [link
+asio.reference.ProtoAllocator `ProtoAllocator`] requirements. The type `Alloc2`
+is `associated_allocator_t<CompletionHandler, Alloc1>`. Let `alloc2` be a value
+of type `Alloc2` obtained by performing
+`get_associated_allocator(completion_handler, alloc1)`.
+
+The asynchronous operations defined in this library:
+
+[mdash] If required, allocate memory using only the completion handler's
+associated allocator.
+
+[mdash] Prior to completion handler execution, deallocate any memory allocated
+using the completion handler's associated allocator.
+
+[std_note The implementation may perform operating system or underlying API
+calls that perform memory allocations not using the associated allocator.
+Invocations of the allocator functions may not introduce data races (See C++Std
+\[res.on.data.races\]).]
+
+[endsect]
+
+[section Execution of completion handler on completion of asynchronous operation]
+
+Let `Args...` be the argument types of the completion signature `Signature` and
+let [^['N]] be `sizeof...(Args)`. Let [^['i]] be in the range [half_open_range
+`0`,[^['N]]]. Let [^T[sub ['i]]] be the [^['i]]th type in `Args...` and let
+[^t[sub ['i]]] be the [^['i]]th completion handler argument associated with
+[^T[sub ['i]]].
+
+Let `f` be a function object, callable as `f()`, that invokes
+`completion_handler` as if by [^completion_handler(forward<T[sub ['0]]>(t[sub
+['0]]), ..., forward<T[sub ['N-1]]>(t[sub ['N-1]]))].
+
+If an asynchonous operation completes immediately (that is, within the thread
+of execution calling the initiating function, and before the initiating
+function returns), the completion handler shall be submitted for execution as
+if by performing `ex2.post(std::move(f), alloc2)`. Otherwise, the completion
+handler shall be submitted for execution as if by performing
+`ex2.dispatch(std::move(f), alloc2)`.
+
+[endsect]
+
+[section Completion handlers and exceptions]
+
+Completion handlers are permitted to throw exceptions. The effect of any
+exception propagated from the execution of a completion handler is determined
+by the executor which is executing the completion handler.
+
+[endsect]
[endsect]
diff --git a/asio/src/doc/requirements/asynchronous_socket_operations.qbk b/asio/src/doc/requirements/asynchronous_socket_operations.qbk
new file mode 100644
index 0000000..c055528
--- /dev/null
+++ b/asio/src/doc/requirements/asynchronous_socket_operations.qbk
@@ -0,0 +1,39 @@
+[/
+ / Copyright (c) 2003-2016 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:asynchronous_socket_operations Requirements on asynchronous socket operations]
+
+In this library, ['asynchronous socket operations] are those member functions
+having prefix `async_`.
+
+For an object `s`, a program may initiate asynchronous socket operations such
+that there are multiple simultaneously outstanding asynchronous operations.
+
+When there are multiple outstanding asynchronous [link
+asio.reference.read_write_operations read operations] on `s`:
+
+[mdash] having no argument `flags` of type `socket_base::message_flags`, or
+
+[mdash] having an argument `flags` of type `socket_base::message_flags` but
+where `(flags & socket_base::message_out_of_band) == 0`
+
+then the `buffers` are filled in the order in which these operations were
+issued. The order of invocation of the completion handlers for these operations
+is unspecified.
+
+When there are multiple outstanding asynchronous [link
+asio.reference.read_write_operations read operations] on `s` having an argument
+`flags` of type `socket_base::message_flags` where `(flags &
+socket_base::message_out_of_band) != 0` then the `buffers` are filled in the
+order in which these operations were issued.
+
+When there are multiple outstanding asynchronous [link
+asio.reference.read_write_operations write operations] on `s`, the `buffers`
+are transmitted in the order in which these operations were issued. The order
+of invocation of the completion handlers for these operations is unspecified.
+
+[endsect]
diff --git a/asio/src/doc/requirements/read_write_operations.qbk b/asio/src/doc/requirements/read_write_operations.qbk
new file mode 100644
index 0000000..d7185a9
--- /dev/null
+++ b/asio/src/doc/requirements/read_write_operations.qbk
@@ -0,0 +1,34 @@
+[/
+ / Copyright (c) 2003-2016 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:read_write_operations Requirements on read and write operations]
+
+A ['read operation] is an operation that reads data into a mutable buffer
+sequence argument of a type meeting [link asio.reference.MutableBufferSequence
+`MutableBufferSequence`] requirements. The mutable buffer sequence specifies
+memory where the data should be placed. A read operation shall always fill a
+buffer in the sequence completely before proceeding to the next.
+
+A ['write operation] is an operation that writes data from a constant buffer
+sequence argument of a type meeting [link asio.reference.ConstBufferSequence
+`ConstBufferSequence`] requirements. The constant buffer sequence specifies
+memory where the data to be written is located. A write operation shall always
+write a buffer in the sequence completely before proceeding to the next.
+
+If a read or write operation is also an [link
+asio.reference.asynchronous_operations asynchronous operation], the operation
+shall maintain one or more copies of the buffer sequence until such time as the
+operation no longer requires access to the memory specified by the buffers in
+the sequence. The program shall ensure the memory remains valid until:
+
+[mdash] the last copy of the buffer sequence is destroyed, or
+
+[mdash] the completion handler for the asynchronous operation is invoked,
+
+whichever comes first.
+
+[endsect]
diff --git a/asio/src/doc/requirements/synchronous_socket_operations.qbk b/asio/src/doc/requirements/synchronous_socket_operations.qbk
new file mode 100644
index 0000000..e6d5250
--- /dev/null
+++ b/asio/src/doc/requirements/synchronous_socket_operations.qbk
@@ -0,0 +1,37 @@
+[/
+ / Copyright (c) 2003-2016 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:synchronous_socket_operations Requirements on synchronous socket operations]
+
+In this section, ['synchronous socket operations] are those member functions
+specified as two overloads, with and without an argument of type `error_code&`:
+
+ ``[*['R f]]``(``['[*A1]]`` a1, ``['[*A2]]`` a2, ..., ``['[*AN]]`` aN);
+ ``[*['R f]]``(``['[*A1]]`` a1, ``['[*A2]]`` a2, ..., ``['[*AN]]`` aN, error_code& ec);
+
+For an object `s`, the conditions under which its synchronous socket operations
+may block the calling thread (C++Std [defns.block]) are determined as follows.
+
+If:
+
+[mdash] `s.non_blocking() == true`,
+
+[mdash] the synchronous socket operation is specified in terms of a __POSIX__
+function other than `__poll__`,
+
+[mdash] that __POSIX__ function lists `EWOULDBLOCK` or `EAGAIN`
+in its failure conditions, and
+
+[mdash] the effects of the operation cannot be established immediately
+
+then the synchronous socket operation shall not block the calling thread.
+[inline_note And the effects of the operation are not established.]
+
+Otherwise, the synchronous socket operation shall block the calling thread
+until the effects are established.
+
+[endsect]
