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