Buffer for I/O operations

Classes
class	uv::buffer
	Encapsulates uv_buf_t data type and provides uv_buf_t[] functionality. More...

Typedefs
using	uv::on_buffer_alloc_t = std::function< buffer(handle _handle, std::size_t _suggested_size) >
	The function type of the callback called by io::read_start() and udp::recv_start()... More...

Detailed Description

libuv uses the uv_buf_t structure to describe the I/O buffer. It is made up in accordance with system depended type iovec on Unix-like OSes and with WSABUF on Windows. An array of uv_buf_t structures is used to allow writing multiple buffers in a single uv::write request.

The class uv::buffer encapsulates uv_buf_t structure and provides uv_buf_t[] array functionality.

See also

documentation for uv::buffer::buffer() constructors.

For the following example here is the diagram illustrating the internals of the uv::buffer object while executing foo(BUF):

buffer BUF{100, 200, 0, 300};

void foo(buffer _b)  { /*...*/ }

int main() {
  foo(BUF);
}

         BUF                         buffer::instance
 ╔═══════════════╗       ╔═════════════════════════════════════╗
 ║ uv_buf_t* ptr ╫────┐  ║ ref_count refs = 2                  ║
 ╚═══════════════╝    │  ╟─────────────────────────────────────╢
                      │  ║ size_t    buf_count = 4             ║
                      │  ╟─────────────────┬───────────────────╢
         _b        ┌─►└─►║ uv_buf_t buf[0] │ char*  .base      ╫───┐
 ╔═══════════════╗ │     ║                 │ size_t .len = 100 ║   │
 ║ uv_buf_t* ptr ╫─┘     ╚═════════════════╧═══════════════════╝   │
 ╚═══════════════╝       │ uv_buf_t buf[1] │ char*  .base      ┼───│───┐
                         │                 │ size_t .len = 200 │   │   │
                         ├─────────────────┼───────────────────┤   │   │
                         │ uv_buf_t buf[2] │ char*  .base      ┼───│───│───┐
                         │                 │ size_t .len = 0   │   │   │   │
                         ├─────────────────┼───────────────────┤   │   │   │
                         │ uv_buf_t buf[3] │ char*  .base      ┼───│───│───│───┐
                         │                 │ size_t .len = 300 │   │   │   │   │
                         ├─────────────────┴───────────────────┤   │   │   │   │
                         │ ... std::max_align_t padding ...    │   │   │   │   │
                         ├─────────────────────────────────────┤   │   │   │   │
                         │                                     │◄──┘   │   │   │
                         │ ... 100 bytes ...                   │       │   │   │
                         │                                     │       │   │   │
                         ├─────────────────────────────────────┤       │   │   │
                         │                                     │◄──────┘   │   │
                         │                                     │           │   │
                         │ ... 200 bytes ...                   │           │   │
                         │                                     │           │   │
                         │                                     │           │   │
                         ├─────────────────────────────────────┤           │   │
                         │                                     │◄──────────┘◄──┘
                         │                                     │
                         │                                     │
                         │ ... 300 bytes ...                   │
                         │                                     │
                         │                                     │
                         │                                     │
                         └─────────────────────────────────────┘

The default constructor uv::buffer::buffer() creates a null-initialized uv_buf_t structure. One can manually fill in a null-initialized uv_buf_t structure to make it pointing to manually allocated memory area in the following ways:

buffer buf;

const size_t len = /*...*/

buf[0] = uv_buf_init(new char[len], len);

// or

buf.base() = new char[len];
buf.len() = len;

Warning

Do not return such a manually initialized buffer objects from the buffer allocation callbacks (of uv::on_buffer_alloc_t function type) that should be passed to io::read_start() and udp::recv_start() functions. Merely a copy of the first uv_buf_t structure held in a buffer object is passed to libuv API functions and there is no way to reconstruct the buffer object's address (which is needed for the uvcc reference counting mechanism to work properly) from the uv_buf_t.base pointer referencing the manually allocated external memory.

Also, the buffer objects that contain an array of uv_buf_t structures are not supported as a valid result of the uv::on_buffer_alloc_t callback functions. Only a single uv_buf_t structure in a buffer object is currently supported for the purposes of the io::read_start() and udp::recv_start() functions.

See also

libuv documentation: uv_buf_init().

Typedef Documentation

on_buffer_alloc_t

using uv::on_buffer_alloc_t = typedef std::function< buffer(handle _handle, std::size_t _suggested_size) >

The function type of the callback called by io::read_start() and udp::recv_start()...

...to supply the input operation with a preallocated buffer. The callback should return a uv::buffer instance initialized with a _suggested_size (the value provided by libuv API is a constant of 65536 bytes) or with whatever size, as long as it’s > 0.

See also

libuv API documentation: uv_alloc_cb.

The following is an example of the trivial callback that is ready for general use:

buffer alloc_cb(handle, std::size_t _suggested_size)
{
  return buffer{ _suggested_size };
}

Definition at line 266 of file buffer.hpp.