|
|
Boost-Commit : |
From: chris_at_[hidden]
Date: 2008-07-08 17:56:53
Author: chris_kohlhoff
Date: 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
New Revision: 47248
URL: http://svn.boost.org/trac/boost/changeset/47248
Log:
Add new type requirements.
Added:
trunk/libs/asio/doc/requirements/AsyncRandomAccessReadDevice.qbk (contents, props changed)
trunk/libs/asio/doc/requirements/AsyncRandomAccessWriteDevice.qbk (contents, props changed)
trunk/libs/asio/doc/requirements/GettableSerialPortOption.qbk (contents, props changed)
trunk/libs/asio/doc/requirements/RandomAccessHandleService.qbk (contents, props changed)
trunk/libs/asio/doc/requirements/RawSocketService.qbk (contents, props changed)
trunk/libs/asio/doc/requirements/SerialPortService.qbk (contents, props changed)
trunk/libs/asio/doc/requirements/SettableSerialPortOption.qbk (contents, props changed)
trunk/libs/asio/doc/requirements/SyncRandomAccessReadDevice.qbk (contents, props changed)
trunk/libs/asio/doc/requirements/SyncRandomAccessWriteDevice.qbk (contents, props changed)
Text files modified:
trunk/libs/asio/doc/reference.qbk | 9 +++++++++
trunk/libs/asio/doc/reference.xsl | 9 +++++++++
2 files changed, 18 insertions(+), 0 deletions(-)
Modified: trunk/libs/asio/doc/reference.qbk
==============================================================================
--- trunk/libs/asio/doc/reference.qbk (original)
+++ trunk/libs/asio/doc/reference.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -11,6 +11,8 @@
[include requirements/asynchronous_operations.qbk]
[include requirements/AcceptHandler.qbk]
+[include requirements/AsyncRandomAccessReadDevice.qbk]
+[include requirements/AsyncRandomAccessWriteDevice.qbk]
[include requirements/AsyncReadStream.qbk]
[include requirements/AsyncWriteStream.qbk]
[include requirements/CompletionHandler.qbk]
@@ -21,6 +23,7 @@
[include requirements/DatagramSocketService.qbk]
[include requirements/DescriptorService.qbk]
[include requirements/Endpoint.qbk]
+[include requirements/GettableSerialPortOption.qbk]
[include requirements/GettableSocketOption.qbk]
[include requirements/Handler.qbk]
[include requirements/HandleService.qbk]
@@ -29,16 +32,22 @@
[include requirements/IoObjectService.qbk]
[include requirements/MutableBufferSequence.qbk]
[include requirements/Protocol.qbk]
+[include requirements/RandomAccessHandleService.qbk]
+[include requirements/RawSocketService.qbk]
[include requirements/ReadHandler.qbk]
[include requirements/ResolveHandler.qbk]
[include requirements/ResolverService.qbk]
+[include requirements/SerialPortService.qbk]
[include requirements/Service.qbk]
+[include requirements/SettableSerialPortOption.qbk]
[include requirements/SettableSocketOption.qbk]
[include requirements/SocketAcceptorService.qbk]
[include requirements/SocketService.qbk]
[include requirements/StreamDescriptorService.qbk]
[include requirements/StreamHandleService.qbk]
[include requirements/StreamSocketService.qbk]
+[include requirements/SyncRandomAccessReadDevice.qbk]
+[include requirements/SyncRandomAccessWriteDevice.qbk]
[include requirements/SyncReadStream.qbk]
[include requirements/SyncWriteStream.qbk]
[include requirements/TimeTraits.qbk]
Modified: trunk/libs/asio/doc/reference.xsl
==============================================================================
--- trunk/libs/asio/doc/reference.xsl (original)
+++ trunk/libs/asio/doc/reference.xsl 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -37,6 +37,8 @@
[include requirements/asynchronous_operations.qbk]
[include requirements/AcceptHandler.qbk]
+[include requirements/AsyncRandomAccessReadDevice.qbk]
+[include requirements/AsyncRandomAccessWriteDevice.qbk]
[include requirements/AsyncReadStream.qbk]
[include requirements/AsyncWriteStream.qbk]
[include requirements/CompletionHandler.qbk]
@@ -47,6 +49,7 @@
[include requirements/DatagramSocketService.qbk]
[include requirements/DescriptorService.qbk]
[include requirements/Endpoint.qbk]
+[include requirements/GettableSerialPortOption.qbk]
[include requirements/GettableSocketOption.qbk]
[include requirements/Handler.qbk]
[include requirements/HandleService.qbk]
@@ -55,16 +58,22 @@
[include requirements/IoObjectService.qbk]
[include requirements/MutableBufferSequence.qbk]
[include requirements/Protocol.qbk]
+[include requirements/RandomAccessHandleService.qbk]
+[include requirements/RawSocketService.qbk]
[include requirements/ReadHandler.qbk]
[include requirements/ResolveHandler.qbk]
[include requirements/ResolverService.qbk]
+[include requirements/SerialPortService.qbk]
[include requirements/Service.qbk]
+[include requirements/SettableSerialPortOption.qbk]
[include requirements/SettableSocketOption.qbk]
[include requirements/SocketAcceptorService.qbk]
[include requirements/SocketService.qbk]
[include requirements/StreamDescriptorService.qbk]
[include requirements/StreamHandleService.qbk]
[include requirements/StreamSocketService.qbk]
+[include requirements/SyncRandomAccessReadDevice.qbk]
+[include requirements/SyncRandomAccessWriteDevice.qbk]
[include requirements/SyncReadStream.qbk]
[include requirements/SyncWriteStream.qbk]
[include requirements/TimeTraits.qbk]
Added: trunk/libs/asio/doc/requirements/AsyncRandomAccessReadDevice.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/AsyncRandomAccessReadDevice.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -0,0 +1,57 @@
+[/
+ / 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:AsyncRandomAccessReadDevice Buffer-oriented asynchronous random-access
+read device requirements]
+
+In the table below, `a` denotes an asynchronous random access read device
+object, `o` denotes an offset of type `boost::uint64_t`, `mb` denotes an object
+satisfying [link boost_asio.reference.MutableBufferSequence mutable buffer sequence]
+requirements, and `h` denotes an object satisfying [link
+boost_asio.reference.ReadHandler read handler] requirements.
+
+[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.async_read_some_at(o, mb, h);`]
+ [`void`]
+ [
+ Initiates an asynchronous operation to read one or more bytes of data
+ from the device `a` at the offset `o`. The operation is performed via the
+ `io_service` object `a.get_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 `async_read_some_at` 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 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.
+ ]
+ ]
+]
+
+[endsect]
Added: trunk/libs/asio/doc/requirements/AsyncRandomAccessWriteDevice.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/AsyncRandomAccessWriteDevice.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -0,0 +1,58 @@
+[/
+ / 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:AsyncRandomAccessWriteDevice Buffer-oriented asynchronous
+random-access write device requirements]
+
+In the table below, `a` denotes an asynchronous write stream object, `o`
+denotes an offset of type `boost::uint64_t`, `cb` denotes an object satisfying
+[link boost_asio.reference.ConstBufferSequence constant buffer sequence]
+requirements, and `h` denotes an object satisfying [link
+boost_asio.reference.WriteHandler write handler] requirements.
+
+[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.async_write_some_at(o, cb, h);`]
+ [`void`]
+ [
+ Initiates an asynchronous operation to write one or more bytes of data to
+ the device `a` at offset `o`. The operation is performed via the
+ `io_service` object `a.get_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 `async_write_some_at` 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 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.
+ ]
+ ]
+]
+
+[endsect]
Added: trunk/libs/asio/doc/requirements/GettableSerialPortOption.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/GettableSerialPortOption.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -0,0 +1,33 @@
+[/
+ / 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:GettableSerialPortOption Gettable serial port option requirements]
+
+In the table below, `X` denotes a serial port option class, `a` denotes a value
+of `X`, `ec` denotes a value of type `error_code`, and `s` denotes a value of
+implementation-defined type ['[^storage]] (where ['[^storage]] is the type
+`DCB` on Windows and `termios` on __POSIX__ platforms), and `u` denotes an
+identifier.
+
+[table GettableSerialPortOption requirements
+ [[expression] [type] [assertion/note\npre/post-conditions]]
+ [
+ [
+ `const `['[^storage]]`& u = s;`\n
+ `a.load(u, ec);`
+ ]
+ [`error_code`]
+ [
+ Retrieves the value of the serial port option from the storage.\n
+ \n
+ If successful, sets `ec` such that `!ec` is true. If an error occurred,
+ sets `ec` such that `!!ec` is true. Returns `ec`.
+ ]
+ ]
+]
+
+[endsect]
Added: trunk/libs/asio/doc/requirements/RandomAccessHandleService.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/RandomAccessHandleService.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -0,0 +1,133 @@
+[/
+ / 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:RandomAccessHandleService Random access handle service requirements]
+
+A random access 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 random access 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`, `o`
+denotes an offset of type boost::uint64_t, `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 RandomAccessHandleService requirements
+ [[expression] [return type] [assertion/note\npre/post-condition]]
+ [
+ [`a.read_some_at(b, o, mb, ec);`]
+ [`size_t`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Reads one or more bytes of data from a handle `b` at offset `o`.\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.
+ ]
+ ]
+ [
+ [`a.async_read_some_at(b, o, 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` at offset `o`. The operation is performed via the
+ `io_service` object `a.get_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 successfully, the `ReadHandler` object
+ `rh` is invoked with the number of bytes transferred. Otherwise it is
+ invoked with `0`.
+ ]
+ ]
+ [
+ [`a.write_some_at(b, o, cb, ec);`]
+ [`size_t`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Writes one or more bytes of data to a handle `b` at offset `o`.\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_at(b, o, cb, wh);`]
+ [`void`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Initiates an asynchronous operation to write one or more bytes of data to
+ a handle `b` at offset `o`. The operation is performed via the
+ `io_service` object `a.get_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/RawSocketService.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/RawSocketService.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -0,0 +1,227 @@
+[/
+ / 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:RawSocketService Raw socket service requirements]
+
+A raw socket service must meet the requirements for a [link
+boost_asio.reference.SocketService socket service], as well as the additional
+requirements listed below.
+
+In the table below, `X` denotes a raw socket service class for protocol
+[link boost_asio.reference.Protocol `Protocol`], `a` denotes a value of type
+`X`, `b` denotes a value of type `X::implementation_type`, `e` denotes a value
+of type `Protocol::endpoint`, `ec` denotes a value of type `error_code`, `f`
+denotes a value of type `socket_base::message_flags`, `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 RawSocketService requirements
+ [[expression] [return type] [assertion/note\npre/post-condition]]
+ [
+ [`a.receive(b, mb, f, ec);`]
+ [`size_t`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Reads one or more bytes of data from a connected socket `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`.
+ ]
+ ]
+ [
+ [`a.async_receive(b, mb, f, rh);`]
+ [`void`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Initiates an asynchronous operation to read one or more bytes of data
+ from a connected socket `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.\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.receive_from(b, mb, e, f, ec);`]
+ [`size_t`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Reads one or more bytes of data from an unconnected socket `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`.
+ ]
+ ]
+ [
+ [`a.async_receive_from(b, mb, e, f, rh);`]
+ [`void`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Initiates an asynchronous operation to read one or more bytes of data
+ from an unconnected socket `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.\n
+ \n
+ The program must ensure the object `e` is valid until the handler
+ for the asynchronous operation is invoked.\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.send(b, cb, f, ec);`]
+ [`size_t`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Writes one or more bytes of data to a connected socket `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`.
+ ]
+ ]
+ [
+ [`a.async_send(b, cb, f, wh);`]
+ [`void`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Initiates an asynchronous operation to write one or more bytes of data to
+ a connected socket `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.\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`.
+ ]
+ ]
+ [
+ [``
+ const typename Protocol::endpoint& u = e;
+ a.send_to(b, cb, u, f, ec);
+ ``]
+ [`size_t`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Writes one or more bytes of data to an unconnected socket `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`.
+ ]
+ ]
+ [
+ [``
+ const typename Protocol::endpoint& u = e;
+ a.async_send(b, cb, u, f, wh);
+ ``]
+ [`void`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Initiates an asynchronous operation to write one or more bytes of data to
+ an unconnected socket `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.\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/SerialPortService.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/SerialPortService.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -0,0 +1,279 @@
+[/
+ / 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:SerialPortService Serial port service requirements]
+
+A serial port 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 serial port service class, `a` denotes a
+value of type `X`, `d` denotes a serial port device name of type `std::string`,
+`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`, `s` denotes a
+value meeting [link boost_asio.reference.SettableSerialPortOption
+`SettableSerialPortOption`] requirements, `g` denotes a value meeting [link
+boost_asio.reference.GettableSerialPortOption `GettableSerialPortOption`]
+requirements, `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. and `u` and `v` denote identifiers.
+
+[table SerialPortService requirements
+ [[expression] [return type] [assertion/note\npre/post-condition]]
+ [
+ [`X::native_type`]
+ []
+ [
+ The implementation-defined native representation of a serial port. 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)`.
+ ]
+ ]
+ [
+ [``
+ const std::string& u = d;
+ a.open(b, u, ec);
+ ``]
+ [`error_code`]
+ [
+ pre: `!a.is_open(b)`.\n
+ post: `!!ec || a.is_open(b)`.
+ ]
+ ]
+ [
+ [``
+ 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.set_option(b, s, ec);
+ ``]
+ [`error_code`]
+ [
+ pre: `a.is_open(b)`.
+ ]
+ ]
+ [
+ [``
+ a.get_option(b, g, ec);
+ ``]
+ [`error_code`]
+ [
+ pre: `a.is_open(b)`.
+ ]
+ ]
+ [
+ [``
+ const X& u = a;
+ const X::implementation_type& v = b;
+ u.get_option(v, g, ec);
+ ``]
+ [`error_code`]
+ [
+ pre: `a.is_open(b)`.
+ ]
+ ]
+ [
+ [``
+ a.send_break(b, ec);
+ ``]
+ [`error_code`]
+ [
+ pre: `a.is_open(b)`.
+ ]
+ ]
+ [
+ [`a.read_some(b, mb, ec);`]
+ [`size_t`]
+ [
+ pre: `a.is_open(b)`.\n
+ \n
+ Reads one or more bytes of data from a serial port `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 serial port `b`. The operation is performed via the
+ `io_service` object `a.get_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 serial port `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 serial port `b`. The operation is performed via the `io_service`
+ object `a.get_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/SettableSerialPortOption.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/SettableSerialPortOption.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -0,0 +1,33 @@
+[/
+ / 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:SettableSerialPortOption Settable serial port option requirements]
+
+In the table below, `X` denotes a serial port option class, `a` denotes a value
+of `X`, `ec` denotes a value of type `error_code`, and `s` denotes a value of
+implementation-defined type ['[^storage]] (where ['[^storage]] is the type
+`DCB` on Windows and `termios` on __POSIX__ platforms), and `u` denotes an
+identifier.
+
+[table SettableSerialPortOption requirements
+ [[expression] [type] [assertion/note\npre/post-conditions]]
+ [
+ [
+ `const X& u = a;`\n
+ `u.store(s, ec);`
+ ]
+ [`error_code`]
+ [
+ Saves the value of the serial port option to the storage.\n
+ \n
+ If successful, sets `ec` such that `!ec` is true. If an error occurred,
+ sets `ec` such that `!!ec` is true. Returns `ec`.
+ ]
+ ]
+]
+
+[endsect]
Added: trunk/libs/asio/doc/requirements/SyncRandomAccessReadDevice.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/SyncRandomAccessReadDevice.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -0,0 +1,49 @@
+[/
+ / 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:SyncRandomAccessReadDevice Buffer-oriented synchronous random-access
+read device requirements]
+
+In the table below, `a` denotes a synchronous random-access read device object,
+`o` denotes an offset of type `boost::uint64_t`, `mb` denotes an object
+satisfying [link boost_asio.reference.MutableBufferSequence mutable buffer sequence]
+requirements, and `ec` denotes an object of type `error_code`.
+
+[table Buffer-oriented synchronous random-access read device requirements
+ [[operation] [type] [semantics, pre/post-conditions]]
+ [
+ [`a.read_some_at(o, mb);`]
+ [`size_t`]
+ [Equivalent to:
+ ``
+ error_code ec;
+ size_t s = a.read_some_at(o, mb, ec);
+ if (ec) throw system_error(ec);
+ return s;
+ ``]
+ ]
+ [
+ [`a.read_some_at(o, mb, ec);`]
+ [`size_t`]
+ [
+ Reads one or more bytes of data from the device `a` at offset `o`.\n
+ \n
+ The mutable buffer sequence `mb` specifies memory where the data should
+ be placed. The `read_some_at` 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 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.
+ ]
+ ]
+]
+
+[endsect]
Added: trunk/libs/asio/doc/requirements/SyncRandomAccessWriteDevice.qbk
==============================================================================
--- (empty file)
+++ trunk/libs/asio/doc/requirements/SyncRandomAccessWriteDevice.qbk 2008-07-08 17:56:50 EDT (Tue, 08 Jul 2008)
@@ -0,0 +1,49 @@
+[/
+ / 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:SyncRandomAccessWriteDevice Buffer-oriented synchronous random-access
+write device requirements]
+
+In the table below, `a` denotes a synchronous random-access write device
+object, `o` denotes an offset of type `boost::uint64_t`, `cb` denotes an object
+satisfying [link boost_asio.reference.ConstBufferSequence constant buffer sequence]
+requirements, and `ec` denotes an object of type `error_code`.
+
+[table Buffer-oriented synchronous random-access write device requirements
+ [[operation] [type] [semantics, pre/post-conditions]]
+ [
+ [`a.write_some_at(o, cb);`]
+ [`size_t`]
+ [Equivalent to:
+ ``
+ error_code ec;
+ size_t s = a.write_some(o, cb, ec);
+ if (ec) throw system_error(ec);
+ return s;
+ ``]
+ ]
+ [
+ [`a.write_some_at(o, cb, ec);`]
+ [`size_t`]
+ [
+ Writes one or more bytes of data to the device `a` at offset `o`.\n
+ \n
+ The constant buffer sequence `cb` specifies memory where the data to be
+ written is located. The `write_some_at` 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 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.
+ ]
+ ]
+]
+
+[endsect]
Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk