1[/
2 / Copyright (c) 2003-2015 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
10A random access handle service must meet the requirements for a [link
11boost_asio.reference.HandleService handle service], as well as the additional
12requirements listed below.
13
14In the table below, `X` denotes a random access handle service class, `a`
15denotes a value of type `X`, `b` denotes a value of type
16`X::implementation_type`, `ec` denotes a value of type `error_code`, `o`
17denotes an offset of type boost::uint64_t, `mb` denotes a value satisfying
18[link boost_asio.reference.MutableBufferSequence mutable buffer sequence]
19requirements, `rh` denotes a value meeting [link boost_asio.reference.ReadHandler
20`ReadHandler`] requirements, `cb` denotes a value satisfying [link
21boost_asio.reference.ConstBufferSequence constant buffer sequence] requirements, and
22`wh` denotes a value meeting [link boost_asio.reference.WriteHandler `WriteHandler`]
23requirements.
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]
134