libs/asio/doc/requirements/AsyncReadStream.qbk

   1 [/
   2  / Copyright (c) 2003-2017 Christopher M. Kohlhoff (chris at kohlhoff dot com)
   3  /
   4  / Distributed under the Boost Software License, Version 1.0. (See accompanying
   5  / file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
   6  /]
   7
   8 [section:AsyncReadStream Buffer-oriented asynchronous read stream requirements]
   9
  10 In the table below, `a` denotes an asynchronous read stream object, `mb`
  11 denotes an object satisfying [link
  12 boost_asio.reference.MutableBufferSequence mutable buffer sequence]
  13 requirements, and `h` denotes an object satisfying [link
  14 boost_asio.reference.ReadHandler read handler] requirements.
  15
  16 [table Buffer-oriented asynchronous read stream requirements
  17   [[operation] [type] [semantics, pre/post-conditions]]
  18   [
  19     [`a.get_io_service();`]
  20     [`io_service&`]
  21     [Returns the `io_service` object through which the `async_read_some`
  22     handler `h` will be invoked.]
  23   ]
  24   [
  25     [`a.async_read_some(mb, h);`]
  26     [`void`]
  27     [
  28       Initiates an asynchronous operation to read one or more bytes of data
  29       from the stream `a`. The operation is performed via the `io_service`
  30       object `a.get_io_service()` and behaves according to [link
  31       boost_asio.reference.asynchronous_operations asynchronous operation]
  32       requirements.\n
  33       \n
  34       The mutable buffer sequence `mb` specifies memory where the data should
  35       be placed. The `async_read_some` operation shall always fill a buffer in
  36       the sequence completely before proceeding to the next.\n
  37       \n
  38       The implementation shall maintain one or more copies of `mb` until such
  39       time as the read operation no longer requires access to the memory
  40       specified by the buffers in the sequence. The program must ensure the
  41       memory is valid until:\n
  42       \n
  43       [mdash] the last copy of `mb` is destroyed, or\n
  44       \n
  45       [mdash] the handler for the asynchronous read operation is invoked,\n
  46       \n
  47       whichever comes first.\n
  48       \n
  49       If the total size of all buffers in the sequence `mb` is `0`, the
  50       asynchronous read operation shall complete immediately and pass `0` as
  51       the argument to the handler that specifies the number of bytes read.
  52     ]
  53   ]
  54 ]
  55
  56 [endsect]