ceph/src/boost/libs/asio/doc/requirements/AsyncWriteStream.qbk

   1 [/
   2  / Copyright (c) 2003-2016 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:AsyncWriteStream Buffer-oriented asynchronous write stream requirements]
   9
  10 In the table below, `a` denotes an asynchronous write stream object, `cb`
  11 denotes an object satisfying [link boost_asio.reference.ConstBufferSequence
  12 constant buffer sequence] requirements, and `h` denotes an object satisfying
  13 [link boost_asio.reference.WriteHandler write handler] requirements.
  14
  15 [table Buffer-oriented asynchronous write stream requirements
  16   [[operation] [type] [semantics, pre/post-conditions]]
  17   [
  18     [`a.get_io_service();`]
  19     [`io_service&`]
  20     [Returns the `io_service` object through which the `async_write_some`
  21     handler `h` will be invoked.]
  22   ]
  23   [
  24     [`a.async_write_some(cb, h);`]
  25     [`void`]
  26     [
  27       Initiates an asynchronous operation to write one or more bytes of data to
  28       the stream `a`. The operation is performed via the `io_service` object
  29       `a.get_io_service()` and behaves according to [link
  30       boost_asio.reference.asynchronous_operations asynchronous operation]
  31       requirements.\n
  32       \n
  33       The constant buffer sequence `cb` specifies memory where the data to be
  34       written is located. The `async_write_some` operation shall always write a
  35       buffer in the sequence completely before proceeding to the next.\n
  36       \n
  37       The implementation shall maintain one or more copies of `cb` until such
  38       time as the write operation no longer requires access to the memory
  39       specified by the buffers in the sequence. The program must ensure the
  40       memory is valid until:\n
  41       \n
  42       [mdash] the last copy of `cb` is destroyed, or\n
  43       \n
  44       [mdash] the handler for the asynchronous write operation is invoked,\n
  45       \n
  46       whichever comes first.\n
  47       \n
  48       If the total size of all buffers in the sequence `cb` is `0`, the
  49       asynchronous write operation shall complete immediately and pass `0` as
  50       the argument to the handler that specifies the number of bytes written.
  51     ]
  52   ]
  53 ]
  54
  55 [endsect]