]>
Commit | Line | Data |
---|---|---|
b32b8144 | 1 | // |
92f5a8d4 | 2 | // Copyright (c) 2016-2019 Vinnie Falco (vinnie dot falco at gmail dot com) |
b32b8144 FG |
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 | // Official repository: https://github.com/boostorg/beast | |
8 | // | |
9 | ||
10 | #ifndef BOOST_BEAST_STATIC_BUFFER_HPP | |
11 | #define BOOST_BEAST_STATIC_BUFFER_HPP | |
12 | ||
13 | #include <boost/beast/core/detail/config.hpp> | |
92f5a8d4 | 14 | #include <boost/beast/core/detail/buffers_pair.hpp> |
b32b8144 | 15 | #include <boost/asio/buffer.hpp> |
b32b8144 | 16 | #include <cstddef> |
b32b8144 FG |
17 | |
18 | namespace boost { | |
19 | namespace beast { | |
20 | ||
92f5a8d4 | 21 | /** A dynamic buffer providing a fixed size, circular buffer. |
b32b8144 | 22 | |
92f5a8d4 TL |
23 | A dynamic buffer encapsulates memory storage that may be |
24 | automatically resized as required, where the memory is | |
25 | divided into two regions: readable bytes followed by | |
26 | writable bytes. These memory regions are internal to | |
27 | the dynamic buffer, but direct access to the elements | |
28 | is provided to permit them to be efficiently used with | |
29 | I/O operations. | |
b32b8144 | 30 | |
92f5a8d4 TL |
31 | Objects of this type meet the requirements of <em>DynamicBuffer</em> |
32 | and have the following additional properties: | |
33 | ||
34 | @li A mutable buffer sequence representing the readable | |
35 | bytes is returned by @ref data when `this` is non-const. | |
36 | ||
37 | @li Buffer sequences representing the readable and writable | |
38 | bytes, returned by @ref data and @ref prepare, may have | |
39 | length up to two. | |
40 | ||
41 | @li All operations execute in constant time. | |
b32b8144 | 42 | |
92f5a8d4 TL |
43 | @li Ownership of the underlying storage belongs to the |
44 | derived class. | |
b32b8144 | 45 | |
92f5a8d4 TL |
46 | @note Variables are usually declared using the template class |
47 | @ref static_buffer; however, to reduce the number of template | |
48 | instantiations, objects should be passed `static_buffer_base&`. | |
49 | ||
50 | @see static_buffer | |
b32b8144 FG |
51 | */ |
52 | class static_buffer_base | |
53 | { | |
54 | char* begin_; | |
55 | std::size_t in_off_ = 0; | |
56 | std::size_t in_size_ = 0; | |
57 | std::size_t out_size_ = 0; | |
58 | std::size_t capacity_; | |
59 | ||
60 | static_buffer_base(static_buffer_base const& other) = delete; | |
61 | static_buffer_base& operator=(static_buffer_base const&) = delete; | |
62 | ||
63 | public: | |
b32b8144 FG |
64 | /** Constructor |
65 | ||
66 | This creates a dynamic buffer using the provided storage area. | |
67 | ||
68 | @param p A pointer to valid storage of at least `n` bytes. | |
69 | ||
70 | @param size The number of valid bytes pointed to by `p`. | |
71 | */ | |
92f5a8d4 TL |
72 | BOOST_BEAST_DECL |
73 | static_buffer_base(void* p, std::size_t size) noexcept; | |
74 | ||
75 | /** Clear the readable and writable bytes to zero. | |
76 | ||
77 | This function causes the readable and writable bytes | |
78 | to become empty. The capacity is not changed. | |
b32b8144 | 79 | |
92f5a8d4 TL |
80 | Buffer sequences previously obtained using @ref data or |
81 | @ref prepare become invalid. | |
82 | ||
83 | @esafe | |
84 | ||
85 | No-throw guarantee. | |
86 | */ | |
87 | BOOST_BEAST_DECL | |
88 | void | |
89 | clear() noexcept; | |
90 | ||
91 | //-------------------------------------------------------------------------- | |
92 | ||
93 | #if BOOST_BEAST_DOXYGEN | |
94 | /// The ConstBufferSequence used to represent the readable bytes. | |
95 | using const_buffers_type = __implementation_defined__; | |
96 | ||
92f5a8d4 TL |
97 | /// The MutableBufferSequence used to represent the writable bytes. |
98 | using mutable_buffers_type = __implementation_defined__; | |
99 | #else | |
100 | using const_buffers_type = detail::buffers_pair<false>; | |
f67539c2 | 101 | |
92f5a8d4 TL |
102 | using mutable_buffers_type = detail::buffers_pair<true>; |
103 | #endif | |
104 | ||
105 | /// Returns the number of readable bytes. | |
b32b8144 | 106 | std::size_t |
92f5a8d4 | 107 | size() const noexcept |
b32b8144 FG |
108 | { |
109 | return in_size_; | |
110 | } | |
111 | ||
92f5a8d4 | 112 | /// Return the maximum number of bytes, both readable and writable, that can ever be held. |
b32b8144 | 113 | std::size_t |
92f5a8d4 | 114 | max_size() const noexcept |
b32b8144 FG |
115 | { |
116 | return capacity_; | |
117 | } | |
118 | ||
92f5a8d4 | 119 | /// Return the maximum number of bytes, both readable and writable, that can be held without requiring an allocation. |
b32b8144 | 120 | std::size_t |
92f5a8d4 | 121 | capacity() const noexcept |
b32b8144 FG |
122 | { |
123 | return capacity_; | |
124 | } | |
125 | ||
92f5a8d4 TL |
126 | /// Returns a constant buffer sequence representing the readable bytes |
127 | BOOST_BEAST_DECL | |
b32b8144 | 128 | const_buffers_type |
92f5a8d4 | 129 | data() const noexcept; |
b32b8144 | 130 | |
92f5a8d4 TL |
131 | /// Returns a constant buffer sequence representing the readable bytes |
132 | const_buffers_type | |
133 | cdata() const noexcept | |
134 | { | |
135 | return data(); | |
136 | } | |
137 | ||
138 | /// Returns a mutable buffer sequence representing the readable bytes | |
139 | BOOST_BEAST_DECL | |
f67539c2 | 140 | mutable_buffers_type |
92f5a8d4 TL |
141 | data() noexcept; |
142 | ||
143 | /** Returns a mutable buffer sequence representing writable bytes. | |
144 | ||
145 | Returns a mutable buffer sequence representing the writable | |
146 | bytes containing exactly `n` bytes of storage. Memory may be | |
147 | reallocated as needed. | |
148 | ||
149 | All buffers sequences previously obtained using | |
150 | @ref data or @ref prepare are invalidated. | |
11fdf7f2 | 151 | |
92f5a8d4 TL |
152 | @param n The desired number of bytes in the returned buffer |
153 | sequence. | |
b32b8144 | 154 | |
92f5a8d4 | 155 | @throws std::length_error if `size() + n` exceeds `max_size()`. |
b32b8144 | 156 | |
92f5a8d4 TL |
157 | @esafe |
158 | ||
159 | Strong guarantee. | |
b32b8144 | 160 | */ |
92f5a8d4 | 161 | BOOST_BEAST_DECL |
b32b8144 | 162 | mutable_buffers_type |
92f5a8d4 | 163 | prepare(std::size_t n); |
b32b8144 | 164 | |
92f5a8d4 | 165 | /** Append writable bytes to the readable bytes. |
b32b8144 | 166 | |
92f5a8d4 TL |
167 | Appends n bytes from the start of the writable bytes to the |
168 | end of the readable bytes. The remainder of the writable bytes | |
169 | are discarded. If n is greater than the number of writable | |
170 | bytes, all writable bytes are appended to the readable bytes. | |
b32b8144 | 171 | |
92f5a8d4 TL |
172 | All buffers sequences previously obtained using |
173 | @ref data or @ref prepare are invalidated. | |
b32b8144 | 174 | |
92f5a8d4 TL |
175 | @param n The number of bytes to append. If this number |
176 | is greater than the number of writable bytes, all | |
177 | writable bytes are appended. | |
178 | ||
179 | @esafe | |
180 | ||
181 | No-throw guarantee. | |
b32b8144 | 182 | */ |
92f5a8d4 | 183 | BOOST_BEAST_DECL |
b32b8144 | 184 | void |
92f5a8d4 | 185 | commit(std::size_t n) noexcept; |
b32b8144 | 186 | |
92f5a8d4 | 187 | /** Remove bytes from beginning of the readable bytes. |
b32b8144 | 188 | |
92f5a8d4 | 189 | Removes n bytes from the beginning of the readable bytes. |
b32b8144 | 190 | |
92f5a8d4 TL |
191 | All buffers sequences previously obtained using |
192 | @ref data or @ref prepare are invalidated. | |
b32b8144 | 193 | |
92f5a8d4 TL |
194 | @param n The number of bytes to remove. If this number |
195 | is greater than the number of readable bytes, all | |
196 | readable bytes are removed. | |
b32b8144 | 197 | |
92f5a8d4 | 198 | @esafe |
b32b8144 | 199 | |
92f5a8d4 | 200 | No-throw guarantee. |
b32b8144 | 201 | */ |
92f5a8d4 | 202 | BOOST_BEAST_DECL |
b32b8144 | 203 | void |
92f5a8d4 | 204 | consume(std::size_t n) noexcept; |
b32b8144 FG |
205 | }; |
206 | ||
207 | //------------------------------------------------------------------------------ | |
208 | ||
92f5a8d4 TL |
209 | /** A dynamic buffer providing a fixed size, circular buffer. |
210 | ||
211 | A dynamic buffer encapsulates memory storage that may be | |
212 | automatically resized as required, where the memory is | |
213 | divided into two regions: readable bytes followed by | |
214 | writable bytes. These memory regions are internal to | |
215 | the dynamic buffer, but direct access to the elements | |
216 | is provided to permit them to be efficiently used with | |
217 | I/O operations. | |
218 | ||
219 | Objects of this type meet the requirements of <em>DynamicBuffer</em> | |
220 | and have the following additional properties: | |
221 | ||
222 | @li A mutable buffer sequence representing the readable | |
223 | bytes is returned by @ref data when `this` is non-const. | |
b32b8144 | 224 | |
92f5a8d4 TL |
225 | @li Buffer sequences representing the readable and writable |
226 | bytes, returned by @ref data and @ref prepare, may have | |
227 | length up to two. | |
228 | ||
229 | @li All operations execute in constant time. | |
b32b8144 FG |
230 | |
231 | @tparam N The number of bytes in the internal buffer. | |
232 | ||
233 | @note To reduce the number of template instantiations when passing | |
234 | objects of this type in a deduced context, the signature of the | |
235 | receiving function should use @ref static_buffer_base instead. | |
236 | ||
92f5a8d4 | 237 | @see static_buffer_base |
b32b8144 FG |
238 | */ |
239 | template<std::size_t N> | |
240 | class static_buffer : public static_buffer_base | |
241 | { | |
242 | char buf_[N]; | |
243 | ||
244 | public: | |
245 | /// Constructor | |
92f5a8d4 | 246 | static_buffer() noexcept |
b32b8144 FG |
247 | : static_buffer_base(buf_, N) |
248 | { | |
249 | } | |
250 | ||
92f5a8d4 TL |
251 | /// Constructor |
252 | static_buffer(static_buffer const&) noexcept; | |
253 | ||
b32b8144 | 254 | /// Assignment |
92f5a8d4 | 255 | static_buffer& operator=(static_buffer const&) noexcept; |
b32b8144 FG |
256 | |
257 | /// Returns the @ref static_buffer_base portion of this object | |
258 | static_buffer_base& | |
92f5a8d4 | 259 | base() noexcept |
b32b8144 FG |
260 | { |
261 | return *this; | |
262 | } | |
263 | ||
264 | /// Returns the @ref static_buffer_base portion of this object | |
265 | static_buffer_base const& | |
92f5a8d4 | 266 | base() const noexcept |
b32b8144 FG |
267 | { |
268 | return *this; | |
269 | } | |
270 | ||
271 | /// Return the maximum sum of the input and output sequence sizes. | |
272 | std::size_t constexpr | |
92f5a8d4 | 273 | max_size() const noexcept |
b32b8144 FG |
274 | { |
275 | return N; | |
276 | } | |
277 | ||
278 | /// Return the maximum sum of input and output sizes that can be held without an allocation. | |
279 | std::size_t constexpr | |
92f5a8d4 | 280 | capacity() const noexcept |
b32b8144 FG |
281 | { |
282 | return N; | |
283 | } | |
284 | }; | |
285 | ||
286 | } // beast | |
287 | } // boost | |
288 | ||
92f5a8d4 TL |
289 | #include <boost/beast/core/impl/static_buffer.hpp> |
290 | #ifdef BOOST_BEAST_HEADER_ONLY | |
b32b8144 | 291 | #include <boost/beast/core/impl/static_buffer.ipp> |
92f5a8d4 | 292 | #endif |
b32b8144 FG |
293 | |
294 | #endif |