]>
Commit | Line | Data |
---|---|---|
7c673cae FG |
1 | [/ |
2 | Copyright (c) 2013-2017 Vinnie Falco (vinnie dot falco at gmail 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:DynamicBuffer DynamicBuffer requirements] | |
9 | ||
10 | A dynamic buffer encapsulates memory storage that may be automatically resized | |
11 | as required, where the memory is divided into an input sequence followed by an | |
12 | output sequence. These memory regions are internal to the dynamic buffer, but | |
13 | direct access to the elements is provided to permit them to be efficiently used | |
14 | with I/O operations, such as the send or receive operations of a socket. Data | |
15 | written to the output sequence of a dynamic buffer object is appended to the | |
16 | input sequence of the same object. | |
17 | ||
18 | The interface to this concept is intended to permit the following | |
19 | implementation strategies: | |
20 | ||
21 | * A single contiguous octet array, which is reallocated as necessary to | |
22 | accommodate changes in the size of the octet sequence. This is the | |
23 | implementation approach currently offered by | |
24 | [link beast.ref.basic_flat_streambuf `basic_flat_streambuf`]. | |
25 | ||
26 | * A sequence of one or more octet arrays, where each array is of the same | |
27 | size. Additional octet array objects are appended to the sequence to | |
28 | accommodate changes in the size of the octet sequence. | |
29 | ||
30 | * A sequence of one or more octet arrays of varying sizes. Additional octet | |
31 | array objects are appended to the sequence to accommodate changes in the | |
32 | size of the character sequence. This is the implementation approach | |
33 | currently offered by [link beast.ref.basic_streambuf `basic_streambuf`]. | |
34 | ||
35 | In the table below: | |
36 | ||
37 | * `X` denotes a dynamic buffer class. | |
38 | * `a` denotes a value of type `X`. | |
39 | * `c` denotes a (possibly const) value of type `X`. | |
40 | * `n` denotes a value of type `std::size_t`. | |
41 | * `T` denotes a type meeting the requirements for [@http://www.boost.org/doc/libs/1_61_0/doc/html/boost_asio/reference/ConstBufferSequence.html `ConstBufferSequence`]. | |
42 | * `U` denotes a type meeting the requirements for [@http://www.boost.org/doc/libs/1_61_0/doc/html/boost_asio/reference/MutableBufferSequence.html `MutableBufferSequence`]. | |
43 | ||
44 | [table DynamicBuffer requirements | |
45 | [[operation] [type] [semantics, pre/post-conditions]] | |
46 | [ | |
47 | [`X::const_buffers_type`] | |
48 | [`T`] | |
49 | [ | |
50 | This type represents the memory associated with the input sequence. | |
51 | ] | |
52 | ] | |
53 | [ | |
54 | [`X::mutable_buffers_type`] | |
55 | [`U`] | |
56 | [ | |
57 | This type represents the memory associated with the output sequence. | |
58 | ] | |
59 | ] | |
60 | [ | |
61 | [`c.size()`] | |
62 | [`std::size_t`] | |
63 | [ | |
64 | Returns the size, in bytes, of the input sequence. | |
65 | ] | |
66 | ] | |
67 | [ | |
68 | [`c.max_size()`] | |
69 | [`std::size_t`] | |
70 | [ | |
71 | Returns the permitted maximum of the sum of the sizes of the input | |
72 | sequence and output sequence. | |
73 | ] | |
74 | ] | |
75 | [ | |
76 | [`c.capacity()`] | |
77 | [`std::size_t`] | |
78 | [ | |
79 | Returns the maximum sum of the sizes of the input sequence and output | |
80 | sequence that the dynamic buffer can hold without requiring reallocation. | |
81 | ] | |
82 | ] | |
83 | [ | |
84 | [`c.data()`] | |
85 | [`X::const_buffers_type`] | |
86 | [ | |
87 | Returns a constant buffer sequence u that represents the memory | |
88 | associated with the input sequence, and where `buffer_size(u) == size()`. | |
89 | ] | |
90 | ] | |
91 | [ | |
92 | [`a.prepare(n)`] | |
93 | [`X::mutable_buffers_type`] | |
94 | [ | |
95 | Returns a mutable buffer sequence u representing the output sequence, | |
96 | and where `buffer_size(u) == n`. The dynamic buffer reallocates memory | |
97 | as required. All constant or mutable buffer sequences previously | |
98 | obtained using `data()` or `prepare()` are invalidated. | |
99 | ||
100 | Throws: `length_error` if `size() + n` exceeds `max_size()`. | |
101 | ] | |
102 | ] | |
103 | [ | |
104 | [`a.commit(n)`] | |
105 | [ ] | |
106 | [ | |
107 | Appends `n` bytes from the start of the output sequence to the end of | |
108 | the input sequence. The remainder of the output sequence is discarded. | |
109 | If `n` is greater than the size of the output sequence, the entire | |
110 | output sequence is appended to the input sequence. All constant or | |
111 | mutable buffer sequences previously obtained using `data()` or | |
112 | `prepare()` are invalidated. | |
113 | ] | |
114 | ] | |
115 | [ | |
116 | [`a.consume(n)`] | |
117 | [ ] | |
118 | [ | |
119 | Removes `n` bytes from beginning of the input sequence. If `n` is | |
120 | greater than the size of the input sequence, the entire input sequence | |
121 | is removed. All constant or mutable buffer sequences previously | |
122 | obtained using `data()` or `prepare()` are invalidated. | |
123 | ] | |
124 | ] | |
125 | ] | |
126 | ||
127 | [endsect] |