| [/ |
| / Copyright (c) 2003-2010 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:AsyncReadStream Buffer-oriented asynchronous read stream requirements] |
| |
| In the table below, `a` denotes an asynchronous read stream object, `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 read stream requirements |
| [[operation] [type] [semantics, pre/post-conditions]] |
| [ |
| [`a.io_service();`] |
| [`io_service&`] |
| [Returns the `io_service` object through which the `async_read_some` |
| handler `h` will be invoked.] |
| ] |
| [ |
| [`a.async_read_some(mb, h);`] |
| [`void`] |
| [ |
| 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.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` 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] |