ceph/src/boost/libs/asio/doc/requirements/RawSocketService.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:RawSocketService Raw socket service requirements]
   9
  10 A raw socket service must meet the requirements for a [link
  11 boost_asio.reference.SocketService socket service], as well as the additional
  12 requirements listed below.
  13
  14 In the table below, `X` denotes a raw socket service class for protocol
  15 [link boost_asio.reference.Protocol `Protocol`], `a` denotes a value of type
  16 `X`, `b` denotes a value of type `X::implementation_type`, `e` denotes a value
  17 of type `Protocol::endpoint`, `ec` denotes a value of type `error_code`, `f`
  18 denotes a value of type `socket_base::message_flags`, `mb` denotes a value
  19 satisfying [link boost_asio.reference.MutableBufferSequence mutable buffer
  20 sequence] requirements, `rh` denotes a value meeting [link
  21 boost_asio.reference.ReadHandler `ReadHandler`] requirements, `cb` denotes a
  22 value satisfying [link boost_asio.reference.ConstBufferSequence constant
  23 buffer sequence] requirements, and `wh` denotes a value meeting [link
  24 boost_asio.reference.WriteHandler `WriteHandler`] requirements.
  25
  26 [table RawSocketService requirements
  27   [[expression] [return type] [assertion/note\npre/post-condition]]
  28   [
  29     [`a.receive(b, mb, f, ec);`]
  30     [`size_t`]
  31     [
  32       pre: `a.is_open(b)`.\n
  33       \n
  34       Reads one or more bytes of data from a connected socket `b`.\n
  35       \n
  36       The mutable buffer sequence `mb` specifies memory where the data should
  37       be placed. The operation shall always fill a buffer in the sequence
  38       completely before proceeding to the next.\n
  39       \n
  40       If successful, returns the number of bytes read. Otherwise returns `0`.
  41     ]
  42   ]
  43   [
  44     [`a.async_receive(b, mb, f, rh);`]
  45     [`void`]
  46     [
  47       pre: `a.is_open(b)`.\n
  48       \n
  49       Initiates an asynchronous operation to read one or more bytes of data
  50       from a connected socket `b`. The operation is performed via the
  51       `io_service` object `a.get_io_service()` and behaves according to [link
  52       boost_asio.reference.asynchronous_operations asynchronous operation]
  53       requirements.\n
  54       \n
  55       The mutable buffer sequence `mb` specifies memory where the data should
  56       be placed. The operation shall always fill a buffer in the sequence
  57       completely before proceeding to the next.\n
  58       \n
  59       The implementation shall maintain one or more copies of `mb` until such
  60       time as the read operation no longer requires access to the memory
  61       specified by the buffers in the sequence. The program must ensure the
  62       memory is valid until:\n
  63       \n
  64       [mdash] the last copy of `mb` is destroyed, or\n
  65       \n
  66       [mdash] the handler for the asynchronous operation is invoked,\n
  67       \n
  68       whichever comes first.\n
  69       \n
  70       If the operation completes successfully, the `ReadHandler` object
  71       `rh` is invoked with the number of bytes transferred. Otherwise it is
  72       invoked with `0`.
  73     ]
  74   ]
  75   [
  76     [`a.receive_from(b, mb, e, f, ec);`]
  77     [`size_t`]
  78     [
  79       pre: `a.is_open(b)`.\n
  80       \n
  81       Reads one or more bytes of data from an unconnected socket `b`.\n
  82       \n
  83       The mutable buffer sequence `mb` specifies memory where the data should
  84       be placed. The operation shall always fill a buffer in the sequence
  85       completely before proceeding to the next.\n
  86       \n
  87       If successful, returns the number of bytes read. Otherwise returns `0`.
  88     ]
  89   ]
  90   [
  91     [`a.async_receive_from(b, mb, e, f, rh);`]
  92     [`void`]
  93     [
  94       pre: `a.is_open(b)`.\n
  95       \n
  96       Initiates an asynchronous operation to read one or more bytes of data
  97       from an unconnected socket `b`. The operation is performed via the
  98       `io_service` object `a.get_io_service()` and behaves according to [link
  99       boost_asio.reference.asynchronous_operations asynchronous operation]
 100       requirements.\n
 101       \n
 102       The mutable buffer sequence `mb` specifies memory where the data should
 103       be placed. The operation shall always fill a buffer in the sequence
 104       completely before proceeding to the next.\n
 105       \n
 106       The implementation shall maintain one or more copies of `mb` until such
 107       time as the read operation no longer requires access to the memory
 108       specified by the buffers in the sequence. The program must ensure the
 109       memory is valid until:\n
 110       \n
 111       [mdash] the last copy of `mb` is destroyed, or\n
 112       \n
 113       [mdash] the handler for the asynchronous operation is invoked,\n
 114       \n
 115       whichever comes first.\n
 116       \n
 117       The program must ensure the object `e` is valid until the handler
 118       for the asynchronous operation is invoked.\n
 119       \n
 120       If the operation completes successfully, the `ReadHandler` object
 121       `rh` is invoked with the number of bytes transferred. Otherwise it is
 122       invoked with `0`.
 123     ]
 124   ]
 125   [
 126     [`a.send(b, cb, f, ec);`]
 127     [`size_t`]
 128     [
 129       pre: `a.is_open(b)`.\n
 130       \n
 131       Writes one or more bytes of data to a connected socket `b`.\n
 132       \n
 133       The constant buffer sequence `cb` specifies memory where the data to be
 134       written is located. The operation shall always write a buffer in the
 135       sequence completely before proceeding to the next.\n
 136       \n
 137       If successful, returns the number of bytes written. Otherwise returns `0`.
 138     ]
 139   ]
 140   [
 141     [`a.async_send(b, cb, f, wh);`]
 142     [`void`]
 143     [
 144       pre: `a.is_open(b)`.\n
 145       \n
 146       Initiates an asynchronous operation to write one or more bytes of data to
 147       a connected socket `b`. The operation is performed via the `io_service`
 148       object `a.get_io_service()` and behaves according to [link
 149       boost_asio.reference.asynchronous_operations asynchronous operation]
 150       requirements.\n
 151       \n
 152       The constant buffer sequence `cb` specifies memory where the data to be
 153       written is located. The operation shall always write a buffer in the
 154       sequence completely before proceeding to the next.\n
 155       \n
 156       The implementation shall maintain one or more copies of `cb` until such
 157       time as the write operation no longer requires access to the memory
 158       specified by the buffers in the sequence. The program must ensure the
 159       memory is valid until:\n
 160       \n
 161       [mdash] the last copy of `cb` is destroyed, or\n
 162       \n
 163       [mdash] the handler for the asynchronous operation is invoked,\n
 164       \n
 165       whichever comes first.\n
 166       \n
 167       If the operation completes successfully, the `WriteHandler` object `wh`
 168       is invoked with the number of bytes transferred. Otherwise it is invoked
 169       with `0`.
 170     ]
 171   ]
 172   [
 173     [``
 174       const typename Protocol::endpoint& u = e;
 175       a.send_to(b, cb, u, f, ec);
 176     ``]
 177     [`size_t`]
 178     [
 179       pre: `a.is_open(b)`.\n
 180       \n
 181       Writes one or more bytes of data to an unconnected socket `b`.\n
 182       \n
 183       The constant buffer sequence `cb` specifies memory where the data to be
 184       written is located. The operation shall always write a buffer in the
 185       sequence completely before proceeding to the next.\n
 186       \n
 187       If successful, returns the number of bytes written. Otherwise returns `0`.
 188     ]
 189   ]
 190   [
 191     [``
 192       const typename Protocol::endpoint& u = e;
 193       a.async_send(b, cb, u, f, wh);
 194     ``]
 195     [`void`]
 196     [
 197       pre: `a.is_open(b)`.\n
 198       \n
 199       Initiates an asynchronous operation to write one or more bytes of data to
 200       an unconnected socket `b`. The operation is performed via the `io_service`
 201       object `a.get_io_service()` and behaves according to [link
 202       boost_asio.reference.asynchronous_operations asynchronous operation]
 203       requirements.\n
 204       \n
 205       The constant buffer sequence `cb` specifies memory where the data to be
 206       written is located. The operation shall always write a buffer in the
 207       sequence completely before proceeding to the next.\n
 208       \n
 209       The implementation shall maintain one or more copies of `cb` until such
 210       time as the write operation no longer requires access to the memory
 211       specified by the buffers in the sequence. The program must ensure the
 212       memory is valid until:\n
 213       \n
 214       [mdash] the last copy of `cb` is destroyed, or\n
 215       \n
 216       [mdash] the handler for the asynchronous operation is invoked,\n
 217       \n
 218       whichever comes first.\n
 219       \n
 220       If the operation completes successfully, the `WriteHandler` object `wh`
 221       is invoked with the number of bytes transferred. Otherwise it is invoked
 222       with `0`.
 223     ]
 224   ]
 225 ]
 226
 227 [endsect]