The asio::buffer function is used to create a buffer object to represent raw memory, an array of POD elements, a vector of POD elements, or a std::string. More...
Functions | |
| mutable_buffers_1 | asio::buffer (const mutable_buffer &b) |
| Create a new modifiable buffer from an existing buffer. | |
| mutable_buffers_1 | asio::buffer (const mutable_buffer &b, std::size_t max_size_in_bytes) |
| Create a new modifiable buffer from an existing buffer. | |
| const_buffers_1 | asio::buffer (const const_buffer &b) |
| Create a new non-modifiable buffer from an existing buffer. | |
| const_buffers_1 | asio::buffer (const const_buffer &b, std::size_t max_size_in_bytes) |
| Create a new non-modifiable buffer from an existing buffer. | |
| mutable_buffers_1 | asio::buffer (void *data, std::size_t size_in_bytes) |
| Create a new modifiable buffer that represents the given memory range. | |
| const_buffers_1 | asio::buffer (const void *data, std::size_t size_in_bytes) |
| Create a new non-modifiable buffer that represents the given memory range. | |
| template<typename PodType , std::size_t N> | |
| mutable_buffers_1 | asio::buffer (PodType(&data)[N]) |
| Create a new modifiable buffer that represents the given POD array. | |
| template<typename PodType , std::size_t N> | |
| mutable_buffers_1 | asio::buffer (PodType(&data)[N], std::size_t max_size_in_bytes) |
| Create a new modifiable buffer that represents the given POD array. | |
| template<typename PodType , std::size_t N> | |
| const_buffers_1 | asio::buffer (const PodType(&data)[N]) |
| Create a new non-modifiable buffer that represents the given POD array. | |
| template<typename PodType , std::size_t N> | |
| const_buffers_1 | asio::buffer (const PodType(&data)[N], std::size_t max_size_in_bytes) |
| Create a new non-modifiable buffer that represents the given POD array. | |
| template<typename PodType , std::size_t N> | |
| mutable_buffers_1 | asio::buffer (boost::array< PodType, N > &data) |
| Create a new modifiable buffer that represents the given POD array. | |
| template<typename PodType , std::size_t N> | |
| mutable_buffers_1 | asio::buffer (boost::array< PodType, N > &data, std::size_t max_size_in_bytes) |
| Create a new modifiable buffer that represents the given POD array. | |
| template<typename PodType , std::size_t N> | |
| const_buffers_1 | asio::buffer (boost::array< const PodType, N > &data) |
| Create a new non-modifiable buffer that represents the given POD array. | |
| template<typename PodType , std::size_t N> | |
| const_buffers_1 | asio::buffer (boost::array< const PodType, N > &data, std::size_t max_size_in_bytes) |
| Create a new non-modifiable buffer that represents the given POD array. | |
| template<typename PodType , typename Allocator > | |
| mutable_buffers_1 | asio::buffer (std::vector< PodType, Allocator > &data) |
| Create a new modifiable buffer that represents the given POD vector. | |
| template<typename PodType , typename Allocator > | |
| mutable_buffers_1 | asio::buffer (std::vector< PodType, Allocator > &data, std::size_t max_size_in_bytes) |
| Create a new modifiable buffer that represents the given POD vector. | |
| template<typename PodType , typename Allocator > | |
| const_buffers_1 | asio::buffer (const std::vector< PodType, Allocator > &data) |
| Create a new non-modifiable buffer that represents the given POD vector. | |
| template<typename PodType , typename Allocator > | |
| const_buffers_1 | asio::buffer (const std::vector< PodType, Allocator > &data, std::size_t max_size_in_bytes) |
| Create a new non-modifiable buffer that represents the given POD vector. | |
| const_buffers_1 | asio::buffer (const std::string &data) |
| Create a new non-modifiable buffer that represents the given string. | |
| const_buffers_1 | asio::buffer (const std::string &data, std::size_t max_size_in_bytes) |
| Create a new non-modifiable buffer that represents the given string. | |
The asio::buffer function is used to create a buffer object to represent raw memory, an array of POD elements, a vector of POD elements, or a std::string.
A buffer object represents a contiguous region of memory as a 2-tuple consisting of a pointer and size in bytes. A tuple of the form {void*, size_t} specifies a mutable (modifiable) region of memory. Similarly, a tuple of the form {const void*, size_t} specifies a const (non-modifiable) region of memory. These two forms correspond to the classes mutable_buffer and const_buffer, respectively. To mirror C++'s conversion rules, a mutable_buffer is implicitly convertible to a const_buffer, and the opposite conversion is not permitted.
The simplest use case involves reading or writing a single buffer of a specified size:
sock.send(asio::buffer(data, size));
In the above example, the return value of asio::buffer meets the requirements of the ConstBufferSequence concept so that it may be directly passed to the socket's write function. A buffer created for modifiable memory also meets the requirements of the MutableBufferSequence concept.
An individual buffer may be created from a builtin array, std::vector or boost::array of POD elements. This helps prevent buffer overruns by automatically determining the size of the buffer:
char d1[128]; size_t bytes_transferred = sock.receive(asio::buffer(d1)); std::vector<char> d2(128); bytes_transferred = sock.receive(asio::buffer(d2)); boost::array<char, 128> d3; bytes_transferred = sock.receive(asio::buffer(d3));
In all three cases above, the buffers created are exactly 128 bytes long. Note that a vector is never automatically resized when creating or using a buffer. The buffer size is determined using the vector's size() member function, and not its capacity.
The contents of a buffer may be accessed using the asio::buffer_size and asio::buffer_cast functions:
asio::mutable_buffer b1 = ...; std::size_t s1 = asio::buffer_size(b1); unsigned char* p1 = asio::buffer_cast<unsigned char*>(b1); asio::const_buffer b2 = ...; std::size_t s2 = asio::buffer_size(b2); const void* p2 = asio::buffer_cast<const void*>(b2);
The asio::buffer_cast function permits violations of type safety, so uses of it in application code should be carefully considered.
A buffer object does not have any ownership of the memory it refers to. It is the responsibility of the application to ensure the memory region remains valid until it is no longer required for an I/O operation. When the memory is no longer available, the buffer is said to have been invalidated.
For the asio::buffer overloads that accept an argument of type std::vector, the buffer objects returned are invalidated by any vector operation that also invalidates all references, pointers and iterators referring to the elements in the sequence (C++ Std, 23.2.4)
For the asio::buffer overloads that accept an argument of type std::string, the buffer objects returned are invalidated according to the rules defined for invalidation of references, pointers and iterators referring to elements of the sequence (C++ Std, 21.3).
Buffer objects may be manipulated using simple arithmetic in a safe way which helps prevent buffer overruns. Consider an array initialised as follows:
boost::array<char, 6> a = { 'a', 'b', 'c', 'd', 'e' };
A buffer object b1 created using:
b1 = asio::buffer(a);
represents the entire array, { 'a', 'b', 'c', 'd', 'e' }. An optional second argument to the asio::buffer function may be used to limit the size, in bytes, of the buffer:
b2 = asio::buffer(a, 3);
such that b2 represents the data { 'a', 'b', 'c' }. Even if the size argument exceeds the actual size of the array, the size of the buffer object created will be limited to the array size.
An offset may be applied to an existing buffer to create a new one:
b3 = b1 + 2;
where b3 will set to represent { 'c', 'd', 'e' }. If the offset exceeds the size of the existing buffer, the newly created buffer will be empty.
Both an offset and size may be specified to create a buffer that corresponds to a specific range of bytes within an existing buffer:
b4 = asio::buffer(b1 + 1, 3);
so that b4 will refer to the bytes { 'b', 'c', 'd' }.
To read or write using multiple buffers (i.e. scatter-gather I/O), multiple buffer objects may be assigned into a container that supports the MutableBufferSequence (for read) or ConstBufferSequence (for write) concepts:
char d1[128]; std::vector<char> d2(128); boost::array<char, 128> d3; boost::array<mutable_buffer, 3> bufs1 = { asio::buffer(d1), asio::buffer(d2), asio::buffer(d3) }; bytes_transferred = sock.receive(bufs1); std::vector<const_buffer> bufs2; bufs2.push_back(asio::buffer(d1)); bufs2.push_back(asio::buffer(d2)); bufs2.push_back(asio::buffer(d3)); bytes_transferred = sock.send(bufs2);
| mutable_buffers_1 asio::buffer | ( | const mutable_buffer & | b | ) | [inline] |
Create a new modifiable buffer from an existing buffer.
mutable_buffers_1(b). Definition at line 596 of file buffer.hpp.
| mutable_buffers_1 asio::buffer | ( | const mutable_buffer & | b, |
| std::size_t | max_size_in_bytes | ||
| ) | [inline] |
Create a new modifiable buffer from an existing buffer.
mutable_buffers_1(
buffer_cast<void*>(b),
min(buffer_size(b), max_size_in_bytes));
Definition at line 608 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | const const_buffer & | b | ) | [inline] |
Create a new non-modifiable buffer from an existing buffer.
const_buffers_1(b). Definition at line 625 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | const const_buffer & | b, |
| std::size_t | max_size_in_bytes | ||
| ) | [inline] |
Create a new non-modifiable buffer from an existing buffer.
const_buffers_1(
buffer_cast<const void*>(b),
min(buffer_size(b), max_size_in_bytes));
Definition at line 637 of file buffer.hpp.
| mutable_buffers_1 asio::buffer | ( | void * | data, |
| std::size_t | size_in_bytes | ||
| ) | [inline] |
Create a new modifiable buffer that represents the given memory range.
mutable_buffers_1(data, size_in_bytes). Definition at line 654 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | const void * | data, |
| std::size_t | size_in_bytes | ||
| ) | [inline] |
Create a new non-modifiable buffer that represents the given memory range.
const_buffers_1(data, size_in_bytes). Definition at line 663 of file buffer.hpp.
| mutable_buffers_1 asio::buffer | ( | PodType(&) | data[N] | ) | [inline] |
Create a new modifiable buffer that represents the given POD array.
mutable_buffers_1(
static_cast<void*>(data),
N * sizeof(PodType));
Definition at line 677 of file buffer.hpp.
| mutable_buffers_1 asio::buffer | ( | PodType(&) | data[N], |
| std::size_t | max_size_in_bytes | ||
| ) | [inline] |
Create a new modifiable buffer that represents the given POD array.
mutable_buffers_1(
static_cast<void*>(data),
min(N * sizeof(PodType), max_size_in_bytes));
Definition at line 690 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | const PodType(&) | data[N] | ) | [inline] |
Create a new non-modifiable buffer that represents the given POD array.
const_buffers_1(
static_cast<const void*>(data),
N * sizeof(PodType));
Definition at line 707 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | const PodType(&) | data[N], |
| std::size_t | max_size_in_bytes | ||
| ) | [inline] |
Create a new non-modifiable buffer that represents the given POD array.
const_buffers_1(
static_cast<const void*>(data),
min(N * sizeof(PodType), max_size_in_bytes));
Definition at line 720 of file buffer.hpp.
| mutable_buffers_1 asio::buffer | ( | boost::array< PodType, N > & | data | ) | [inline] |
Create a new modifiable buffer that represents the given POD array.
mutable_buffers_1(
data.data(),
data.size() * sizeof(PodType));
Definition at line 808 of file buffer.hpp.
| mutable_buffers_1 asio::buffer | ( | boost::array< PodType, N > & | data, |
| std::size_t | max_size_in_bytes | ||
| ) | [inline] |
Create a new modifiable buffer that represents the given POD array.
mutable_buffers_1(
data.data(),
min(data.size() * sizeof(PodType), max_size_in_bytes));
Definition at line 822 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | boost::array< const PodType, N > & | data | ) | [inline] |
Create a new non-modifiable buffer that represents the given POD array.
const_buffers_1(
data.data(),
data.size() * sizeof(PodType));
Definition at line 839 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | boost::array< const PodType, N > & | data, |
| std::size_t | max_size_in_bytes | ||
| ) | [inline] |
Create a new non-modifiable buffer that represents the given POD array.
const_buffers_1(
data.data(),
min(data.size() * sizeof(PodType), max_size_in_bytes));
Definition at line 853 of file buffer.hpp.
| mutable_buffers_1 asio::buffer | ( | std::vector< PodType, Allocator > & | data | ) | [inline] |
Create a new modifiable buffer that represents the given POD vector.
mutable_buffers_1(
data.size() ? &data[0] : 0,
data.size() * sizeof(PodType));
Definition at line 907 of file buffer.hpp.
| mutable_buffers_1 asio::buffer | ( | std::vector< PodType, Allocator > & | data, |
| std::size_t | max_size_in_bytes | ||
| ) | [inline] |
Create a new modifiable buffer that represents the given POD vector.
mutable_buffers_1(
data.size() ? &data[0] : 0,
min(data.size() * sizeof(PodType), max_size_in_bytes));
Definition at line 930 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | const std::vector< PodType, Allocator > & | data | ) | [inline] |
Create a new non-modifiable buffer that represents the given POD vector.
const_buffers_1(
data.size() ? &data[0] : 0,
data.size() * sizeof(PodType));
Definition at line 956 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | const std::vector< PodType, Allocator > & | data, |
| std::size_t | max_size_in_bytes | ||
| ) | [inline] |
Create a new non-modifiable buffer that represents the given POD vector.
const_buffers_1(
data.size() ? &data[0] : 0,
min(data.size() * sizeof(PodType), max_size_in_bytes));
Definition at line 980 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | const std::string & | data | ) | [inline] |
Create a new non-modifiable buffer that represents the given string.
const_buffers_1(data.data(), data.size()).Definition at line 1002 of file buffer.hpp.
| const_buffers_1 asio::buffer | ( | const std::string & | data, |
| std::size_t | max_size_in_bytes | ||
| ) | [inline] |
Create a new non-modifiable buffer that represents the given string.
const_buffers_1(
data.data(),
min(data.size(), max_size_in_bytes));
Definition at line 1021 of file buffer.hpp.