ceph/src/boost/libs/asio/doc/requirements/SeqPacketSocketService.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:SeqPacketSocketService Sequenced packet socket service requirements]
   9
  10 A sequenced packet 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 stream socket service class, `a` denotes a
  15 value of type `X`, `b` denotes a value of type `X::implementation_type`, `ec`
  16 denotes a value of type `error_code`, `f` denotes a value of type
  17 `socket_base::message_flags`, `g` denotes an lvalue of type
  18 `socket_base::message_flags`, `mb` denotes a value satisfying [link
  19 boost_asio.reference.MutableBufferSequence mutable buffer sequence] requirements,
  20 `rh` denotes a value meeting [link boost_asio.reference.ReadHandler `ReadHandler`]
  21 requirements, `cb` denotes a value satisfying [link
  22 boost_asio.reference.ConstBufferSequence constant buffer sequence] requirements, and
  23 `wh` denotes a value meeting [link boost_asio.reference.WriteHandler `WriteHandler`]
  24 requirements.
  25
  26 [table StreamSocketService requirements
  27   [[expression] [return type] [assertion/note\npre/post-condition]]
  28   [
  29     [`a.receive(b, mb, f, g, 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, sets `g` to the flags associated with the received data,
  41       and returns the number of bytes read. Otherwise, sets `g` to `0` and
  42       returns `0`.
  43     ]
  44   ]
  45   [
  46     [`a.async_receive(b, mb, f, g, rh);`]
  47     [`void`]
  48     [
  49       pre: `a.is_open(b)`.\n
  50       \n
  51       Initiates an asynchronous operation to read one or more bytes of data
  52       from a connected socket `b`. The operation is performed via the
  53       `io_service` object `a.get_io_service()` and behaves according to [link
  54       boost_asio.reference.asynchronous_operations asynchronous operation]
  55       requirements.\n
  56       \n
  57       The mutable buffer sequence `mb` specifies memory where the data should
  58       be placed. The operation shall always fill a buffer in the sequence
  59       completely before proceeding to the next.\n
  60       \n
  61       The implementation shall maintain one or more copies of `mb` until such
  62       time as the read operation no longer requires access to the memory
  63       specified by the buffers in the sequence. The program must ensure the
  64       memory is valid until:\n
  65       \n
  66       [mdash] the last copy of `mb` is destroyed, or\n
  67       \n
  68       [mdash] the handler for the asynchronous operation is invoked,\n
  69       \n
  70       whichever comes first.\n
  71       \n
  72       If the operation completes successfully, sets `g` to the flags associated
  73       with the received data, then invokes the `ReadHandler` object `rh` with
  74       the number of bytes transferred. Otherwise, sets `g` to `0` and invokes
  75       `rh` with `0` bytes transferred.
  76     ]
  77   ]
  78   [
  79     [`a.send(b, cb, f, ec);`]
  80     [`size_t`]
  81     [
  82       pre: `a.is_open(b)`.\n
  83       \n
  84       Writes one or more bytes of data to a connected socket `b`.\n
  85       \n
  86       The constant buffer sequence `cb` specifies memory where the data to be
  87       written is located. The operation shall always write a buffer in the
  88       sequence completely before proceeding to the next.\n
  89       \n
  90       If successful, returns the number of bytes written. Otherwise returns `0`.
  91     ]
  92   ]
  93   [
  94     [`a.async_send(b, cb, f, wh);`]
  95     [`void`]
  96     [
  97       pre: `a.is_open(b)`.\n
  98       \n
  99       Initiates an asynchronous operation to write one or more bytes of data to
 100       a connected socket `b`. The operation is performed via the `io_service`
 101       object `a.get_io_service()` and behaves according to [link
 102       boost_asio.reference.asynchronous_operations asynchronous operation]
 103       requirements.\n
 104       \n
 105       The constant buffer sequence `cb` specifies memory where the data to be
 106       written is located. The operation shall always write a buffer in the
 107       sequence completely before proceeding to the next.\n
 108       \n
 109       The implementation shall maintain one or more copies of `cb` until such
 110       time as the write operation no longer requires access to the memory
 111       specified by the buffers in the sequence. The program must ensure the
 112       memory is valid until:\n
 113       \n
 114       [mdash] the last copy of `cb` is destroyed, or\n
 115       \n
 116       [mdash] the handler for the asynchronous operation is invoked,\n
 117       \n
 118       whichever comes first.\n
 119       \n
 120       If the operation completes successfully, the `WriteHandler` object `wh`
 121       is invoked with the number of bytes transferred. Otherwise it is invoked
 122       with `0`.
 123     ]
 124   ]
 125 ]
 126
 127 [endsect]