ceph/src/boost/libs/asio/doc/requirements/StreamHandleService.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:StreamHandleService Stream handle service requirements]
   9
  10 A stream handle service must meet the requirements for a [link
  11 boost_asio.reference.HandleService handle service], as well as the additional
  12 requirements listed below.
  13
  14 In the table below, `X` denotes a stream handle service class, `a` denotes
  15 a value of type `X`, `b` denotes a value of type `X::implementation_type`, `ec`
  16 denotes a value of type `error_code`, `mb` denotes a value satisfying [link
  17 boost_asio.reference.MutableBufferSequence mutable buffer sequence] requirements,
  18 `rh` denotes a value meeting [link boost_asio.reference.ReadHandler `ReadHandler`]
  19 requirements, `cb` denotes a value satisfying [link
  20 boost_asio.reference.ConstBufferSequence constant buffer sequence] requirements, and
  21 `wh` denotes a value meeting [link boost_asio.reference.WriteHandler `WriteHandler`]
  22 requirements.
  23
  24 [table StreamHandleService requirements
  25   [[expression] [return type] [assertion/note\npre/post-condition]]
  26   [
  27     [`a.read_some(b, mb, ec);`]
  28     [`size_t`]
  29     [
  30       pre: `a.is_open(b)`.\n
  31       \n
  32       Reads one or more bytes of data from a handle `b`.\n
  33       \n
  34       The mutable buffer sequence `mb` specifies memory where the data should
  35       be placed. The operation shall always fill a buffer in the sequence
  36       completely before proceeding to the next.\n
  37       \n
  38       If successful, returns the number of bytes read. Otherwise returns `0`.
  39       If the total size of all buffers in the sequence `mb` is `0`, the
  40       function shall return `0` immediately.\n
  41       \n
  42       If the operation completes due to graceful connection closure by the
  43       peer, the operation shall fail with `error::eof`.
  44     ]
  45   ]
  46   [
  47     [`a.async_read_some(b, mb, rh);`]
  48     [`void`]
  49     [
  50       pre: `a.is_open(b)`.\n
  51       \n
  52       Initiates an asynchronous operation to read one or more bytes of data
  53       from a handle `b`. The operation is performed via the
  54       `io_service` object `a.get_io_service()` and behaves according to [link
  55       boost_asio.reference.asynchronous_operations asynchronous operation]
  56       requirements.\n
  57       \n
  58       The mutable buffer sequence `mb` specifies memory where the data should
  59       be placed. The operation shall always fill a buffer in the sequence
  60       completely before proceeding to the next.\n
  61       \n
  62       The implementation shall maintain one or more copies of `mb` until such
  63       time as the read operation no longer requires access to the memory
  64       specified by the buffers in the sequence. The program must ensure the
  65       memory is valid until:\n
  66       \n
  67       [mdash] the last copy of `mb` is destroyed, or\n
  68       \n
  69       [mdash] the handler for the asynchronous operation is invoked,\n
  70       \n
  71       whichever comes first. If the total size of all buffers in the sequence
  72       `mb` is `0`, the asynchronous read operation shall complete immediately
  73       and pass `0` as the argument to the handler that specifies the number of
  74       bytes read.\n
  75       \n
  76       If the operation completes due to graceful connection closure by the
  77       peer, the operation shall fail with `error::eof`.\n
  78       \n
  79       If the operation completes successfully, the `ReadHandler` object
  80       `rh` is invoked with the number of bytes transferred. Otherwise it is
  81       invoked with `0`.
  82     ]
  83   ]
  84   [
  85     [`a.write_some(b, cb, ec);`]
  86     [`size_t`]
  87     [
  88       pre: `a.is_open(b)`.\n
  89       \n
  90       Writes one or more bytes of data to a handle `b`.\n
  91       \n
  92       The constant buffer sequence `cb` specifies memory where the data to be
  93       written is located. The operation shall always write a buffer in the
  94       sequence completely before proceeding to the next.\n
  95       \n
  96       If successful, returns the number of bytes written. Otherwise returns `0`.
  97       If the total size of all buffers in the sequence `cb` is `0`, the
  98       function shall return `0` immediately.
  99     ]
 100   ]
 101   [
 102     [`a.async_write_some(b, cb, wh);`]
 103     [`void`]
 104     [
 105       pre: `a.is_open(b)`.\n
 106       \n
 107       Initiates an asynchronous operation to write one or more bytes of data to
 108       a handle `b`. The operation is performed via the `io_service`
 109       object `a.get_io_service()` and behaves according to [link
 110       boost_asio.reference.asynchronous_operations asynchronous operation]
 111       requirements.\n
 112       \n
 113       The constant buffer sequence `cb` specifies memory where the data to be
 114       written is located. The operation shall always write a buffer in the
 115       sequence completely before proceeding to the next.\n
 116       \n
 117       The implementation shall maintain one or more copies of `cb` until such
 118       time as the write operation no longer requires access to the memory
 119       specified by the buffers in the sequence. The program must ensure the
 120       memory is valid until:\n
 121       \n
 122       [mdash] the last copy of `cb` is destroyed, or\n
 123       \n
 124       [mdash] the handler for the asynchronous operation is invoked,\n
 125       \n
 126       whichever comes first. If the total size of all buffers in the sequence
 127       `cb` is `0`, the asynchronous operation shall complete immediately and
 128       pass `0` as the argument to the handler that specifies the number of
 129       bytes read.\n
 130       \n
 131       If the operation completes successfully, the `WriteHandler` object `wh`
 132       is invoked with the number of bytes transferred. Otherwise it is invoked
 133       with `0`.
 134     ]
 135   ]
 136 ]
 137
 138 [endsect]