The base class for handles representing I/O endpoints: a file, TCP/UDP socket, pipe, TTY. More...

#include "handle-io.hpp"

Inheritance diagram for uv::io:

Public Types
using	uv_t = void

using	on_read_t = std::function< void(io _handle, ssize_t _nread, buffer _buffer, int64_t _offset, void *_info) >
	The function type of the callback called by `read_start()` when data was read from an I/O endpoint. More...

Public Types inherited from uv::handle
using	uv_t = ::uv_handle_t

using	on_destroy_t = std::function< void(void *_data) >
	The function type of the callback called when the handle has been closed and about to be destroyed. More...

Public Member Functions
	io (const io &)=default

io &	operator= (const io &)=default

	io (io &&) noexcept=default

io &	operator= (io &&) noexcept=default

std::size_t	write_queue_size () const noexcept
	The amount of queued bytes waiting to be written/sent to the I/O endpoint. More...

on_buffer_alloc_t &	on_alloc () const noexcept
	Set the input buffer allocation callback.

on_read_t &	on_read () const noexcept
	Set the read callback function.

int	read_start (std::size_t _size=0, int64_t _offset=-1) const
	Start reading incoming data from the I/O endpoint. More...

int	read_start (const on_buffer_alloc_t &_alloc_cb, const on_read_t &_read_cb, std::size_t _size=0, int64_t _offset=-1) const
	Start reading incoming data from the I/O endpoint with provided input buffer allocation callback (`_alloc_cb`) and read callback function (`_read_cb`). More...

int	read_stop () const
	Stop reading data from the I/O endpoint. More...

int	read_pause (bool _trigger_condition) const
	Pause reading data from the I/O endpoint. More...

int	read_resume (bool _trigger_condition)
	Resume reading data from the I/O endpoint after having been paused. More...

	operator const uv_t * () const noexcept

	operator uv_t * () noexcept

Public Member Functions inherited from uv::handle
	handle (const handle &_that)

handle &	operator= (const handle &_that)

	handle (handle &&_that) noexcept

handle &	operator= (handle &&_that) noexcept

void	swap (handle &_that) noexcept

std::uintptr_t	id () const noexcept
	The unique ID of the instance managed by this handle variable or 0 if the handle is void.

long	nrefs () const noexcept
	The current number of existing references to the same object as this handle variable refers to.

int	uv_status () const noexcept
	The status value returned by the last executed libuv API function on this handle.

on_destroy_t &	on_destroy () const noexcept

::uv_handle_type	type () const noexcept
	The tag indicating the libuv type of the handle.

const char *	type_name () const noexcept
	A string containing the name of the handle type.

uv::loop	loop () const noexcept
	The libuv loop where the handle is running on. More...

void *&	data () const noexcept
	The pointer to the user-defined arbitrary data. libuv and uvcc does not use this field.

int	is_active () const noexcept
	Check if the handle is active. More...

int	is_closing () const noexcept
	Check if the handle is closing or closed. More...

::uv_os_fd_t	fileno () const noexcept
	Get the platform dependent handle/file descriptor. More...

	operator const uv_t * () const noexcept

	operator uv_t * () noexcept

	operator bool () const noexcept
	Equivalent to `(id() and uv_status() >= 0)`.

void	attached (bool _state) const noexcept

bool	attached () const noexcept

Static Public Member Functions
static io	guess_handle (uv::loop &, ::uv_file)
	Create an `io` handle object which actual type is derived from an existing file descriptor. More...

Detailed Description

The base class for handles representing I/O endpoints: a file, TCP/UDP socket, pipe, TTY.

Encapsulates common I/O functions and properties.

Note: read_start()/read_stop() and read_pause()/read_resume() functions are mutually exclusive and thread-safe.

Definition at line 25 of file handle-io.hpp.

Member Typedef Documentation

◆ on_read_t

using uv::io::on_read_t = std::function< void(io _handle, ssize_t _nread, buffer _buffer, int64_t _offset, void *_info) >

The function type of the callback called by read_start() when data was read from an I/O endpoint.

The _offset parameter is the file offset the read operation has been performed at. For I/O endpoints that are not of uv::file type this appears to be an artificial value which is being properly calculated basing on the starting offset value from the read_start() call and summing the amount of all bytes previously read since that read_start() call.

The _info pointer is valid for the duration of the callback only and for uv::udp endpoint refers to the struct udp::io_info supplemental data, containing information on remote peer address and received message flags. For other I/O endpoint types it is a nullptr.

See also: libuv API documentation: uv_read_cb, uv_udp_recv_cb.

Note: On error and EOF state this callback is supplied with a dummy null-initialized _buffer.

On error and EOF state the libuv API calls the user provided uv_read_cb or uv_udp_recv_cb functions with a null-initialized uv_buf_t buffer structure (where buf->base = nullptr and buf->len = 0) and does not try to retrieve something from the uv_alloc_cb callback in such a cases. So the uvcc io::on_read_t callback is supplied with a dummy null-initialized _buffer.

Definition at line 58 of file handle-io.hpp.

Member Function Documentation

◆ write_queue_size()

std::size_t uv::io::write_queue_size ( ) const

inlinenoexcept

The amount of queued bytes waiting to be written/sent to the I/O endpoint.

See also: libuv API documentation: uv_stream_t.write_queue_size, uv_udp_t.send_queue_size.

Definition at line 149 of file handle-io.hpp.

◆ read_start() [1/2]

int uv::io::read_start	(	std::size_t	_size = `0`,
		int64_t	_offset = `-1`
	)		const

inline

Start reading incoming data from the I/O endpoint.

The appropriate input buffer allocation and read callbacks should be explicitly provided before with on_alloc() and on_read() functions. Otherwise, UV_EINVAL error is returned with no involving any libuv API function.

Repeated call to this function results in the automatic call to read_stop() first.

Parameters are:

_size - can be set to specify suggested length of the read buffer.
_offset - the starting offset for reading from. It is primarily intended for uv::file I/O endpoints and the default value of -1 means using of the current file position. For other I/O endpoint types it is used as a starting value for _offset argument of io::on_read_t callback function, and the default value of -1 means to continue calculating from the offset calculated and internally stored after the last read operation (or, if it has never been started yet, from the initial value of 0).

Note: On successful start this function adds an extra reference to the handle instance, which is released when the counterpart function read_stop() (or read_pause()) is called.

For uv::stream and uv::udp endpoints the function is just a wrapper around uv_read_start() and uv_udp_recv_start() libuv facilities.

For uv::file endpoint it implements a chain of calls for uv_fs_read() libuv API function with the user provided callback function. If the user callback does not stop the read loop by calling read_stop() function, the next call is automatically performed after the callback returns. The user callback receives a number of bytes read during the current iteration, or EOF or error state just like if it would be a uv_read_cb callback for uv::stream endpoint. Note that even on EOF or error state having been reached the loop keeps trying to read from the file until read_stop() is explicitly called.

See also: libuv API documentation: uv_fs_read(), uv_read_start(), uv_udp_recv_start().

Definition at line 191 of file handle-io.hpp.

◆ read_start() [2/2]

int uv::io::read_start	(	const on_buffer_alloc_t &	_alloc_cb,
		const on_read_t &	_read_cb,
		std::size_t	_size = `0`,
		int64_t	_offset = `-1`
	)		const

inline

Start reading incoming data from the I/O endpoint with provided input buffer allocation callback (_alloc_cb) and read callback function (_read_cb).

This is equivalent for

io.on_alloc() = _alloc_cb;
io.on_read() = _read_cb;
io.read_start(_size, _offset);

See also: io::read_start()

Definition at line 241 of file handle-io.hpp.

◆ read_stop()

int uv::io::read_stop ( ) const

inline

Stop reading data from the I/O endpoint.

See also: libuv API documentation: uv_read_stop(), uv_udp_recv_stop().

Definition at line 254 of file handle-io.hpp.

◆ read_pause()

int uv::io::read_pause ( bool _trigger_condition ) const

inline

Pause reading data from the I/O endpoint.

read_pause(true) - a "pause" command that is functionally equivalent to read_stop(). Returns 0 or relevant libuv error code. Exit code of 2 is returned if the handle is not currently in reading state.
read_pause(false) - a no-op command that returns immediately with exit code of 1.

To be used in conjunction with read_resume() control command.

See also: io::read_resume()

Definition at line 289 of file handle-io.hpp.

◆ read_resume()

int uv::io::read_resume ( bool _trigger_condition )

inline

Resume reading data from the I/O endpoint after having been paused.

read_resume(true) - a "resume" command that is functionally equivalent to read_start() except that it cannot "start" and is refused if the previous control command was not "pause" (i.e. read_pause()). Returns 0 or relevant libuv error code. Exit code of 2 is returned if the handle is not in read pause state.
read_resume(false) - a no-op command that returns immediately with exit code of 1.

To be used in conjunction with read_pause() control command.

Note: On successful resuming this function adds an extra reference to the handle instance, which is released when the counterpart function read_pause() (or read_stop()) is called.

The different control command interoperating semantics is described as follows:

                     ║ The command having been executed previously                                 
   The command to    ╟─────────┬──────────────┬───────────────────┬─────────────┬──────────────────
   be currently      ║ No      │ read_start() │ read_resume(true) │ read_stop() │ read_pause(true) 
   executed          ║ command │              │                   │             │                  
  ═══════════════════╬═════════╪══════════════╪═══════════════════╪═════════════╪══════════════════
   read_start()      ║ "start" │ "restart"    │ "restart"         │ "start"     │ "start"          
   read_resume(true) ║ -       │ -            │ -                 │ -           │ "resume"         
   read_stop()       ║ "stop"  │ "stop"       │ "stop"            │ "stop"      │ "stop"           
   read_pause(true)  ║ -       │ "pause"      │ "pause"           │ -           │ -                

  "resume" is functionally equivalent to "start"
  "pause" is functionally equivalent to "stop"
  "restart" is functionally equivalent to "stop" followed by "start"

read_pause()/read_resume() commands are intended for temporary pausing the read process for example in such a cases when a consumer which the data being read is sent to becomes overwhelmed with them and its input queue (and/or a sender output queue) has been considerably increased.

Definition at line 346 of file handle-io.hpp.

◆ guess_handle()

io uv::io::guess_handle	(	uv::loop &	_loop,
		::uv_file	_fd
	)

inlinestatic

Create an io handle object which actual type is derived from an existing file descriptor.

Supported file desctriptors:

Windows: pipe, tty, file
Unix-like systems: pipe, tty, file, tcp/udp socket

See also: libuv API documentation: uv_guess_handle().

Definition at line 408 of file handle-io.hpp.

The documentation for this class was generated from the following file:

handle-io.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ on_read_t

Member Function Documentation

◆ write_queue_size()

◆ read_start() [1/2]

◆ read_start() [2/2]

◆ read_stop()

◆ read_pause()

◆ read_resume()

◆ guess_handle()