]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
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] |