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