UV module

Handle

Wrapper class for managing uv_handle_t variants.

Handle

#include <icy/handle.h>

Subclassed by: Stream< uv_pipe_t >, Stream< uv_tcp_t >, Stream< T >

Wrapper class for managing uv_handle_t variants.

This class manages the handle during its lifecycle and safely handles the asynchronous destruction mechanism.

Public Methods

Return	Name	Description
	`Handle` `inline`	Construct the handle bound to the given event loop.
`bool`	`init` `inline`	Initialize the underlying libuv handle by calling `f` with the loop, the raw handle pointer, and any additional `args`.
`bool`	`invoke` `inline`	Invoke a libuv function `f` with `args` on the initialized handle.
`void`	`invokeOrThrow` `inline`	Invoke a libuv function `f` with `args`, throwing on failure.
`void`	`close` `virtual` `inline`	Close and destroy the handle.
`void`	`ref` `inline`	Re-reference the handle with the event loop after a previous `[unref()](#unref)`.
`void`	`unref` `inline`	Unreference the handle from the event loop.
`bool`	`initialized` `const` `inline`	Return `true` if the handle has been successfully initialized via `[init()](#init-8)`.
`bool`	`active` `virtual` `const` `inline`	Return `true` when the handle is active (libuv `uv_is_active`).
`bool`	`closing` `virtual` `const` `inline`	Return `true` if `uv_close` has been called and the handle is awaiting its close callback (libuv `uv_is_closing`).
`bool`	`closed` `virtual` `const` `inline`	Return `true` if the handle has been fully closed (context released).
`const icy::Error &`	`error` `const` `inline`	Return the last error set on this handle, or a default-constructed `[Error](icy-Error.html#error)` if no error has occurred.
`void`	`setError` `virtual` `inline`	Set the error state and invoke `[onError()](#onerror)`.
`void`	`setUVError` `inline`	Translate a libuv error code into an `[Error](icy-Error.html#error)` and call `[setError()](#seterror-1)`.
`void`	`setAndThrowError` `inline`	Set the error state from a libuv error code and throw a `std::runtime_error`.
`void`	`throwLastError` `inline`	Throw a `std::runtime_error` if the handle currently holds an error.
`uv::Loop *`	`loop` `const` `inline`	Return the event loop this handle is bound to.
`void`	`reset` `inline`	Close the current handle (if open) and allocate a fresh `[Context](icy-uv-Context.html#context-2)`, leaving the handle ready to be re-initialized via `[init()](#init-8)`.
`Handle *`	`get` `const` `inline`	Return the raw libuv handle pointer cast to `[Handle](#handle-6)`.
`std::thread::id`	`tid` `const` `inline`	Return the ID of the thread that constructed this handle.
`IntrusivePtr< Context< T > >`	`context` `const` `inline`	Return the raw `[Context](icy-uv-Context.html#context-2)` that owns the libuv handle memory.
`void`	`setCloseCleanup` `inline`
`void`	`clearCloseCleanup` `inline`
`void`	`assertThread` `const` `inline`	Throw `std::logic_error` if called from any thread other than the thread that constructed this handle.

Handle

inline

inline Handle(uv::Loop * loop)

Construct the handle bound to the given event loop.

Parameters

loop Event loop to associate this handle with. Defaults to the process-wide default loop.

init

inline

template<typename F, typename... Args> inline bool init(F && f, Args &&... args)

Initialize the underlying libuv handle by calling f with the loop, the raw handle pointer, and any additional args.

Must be called exactly once before any other operations. Throws std::logic_error if the handle is already initialized or the context is invalid.

Parameters

f libuv init function (e.g. uv_tcp_init).
args Additional arguments forwarded after the loop and handle pointer.

Returns

true on success; false and sets the error state on failure.

invoke

inline

template<typename F, typename... Args> inline bool invoke(F && f, Args &&... args)

Invoke a libuv function f with args on the initialized handle.

Throws std::logic_error if the handle is not yet initialized. Sets the error state and returns false if f returns a libuv error code.

Parameters

f libuv function to call.
args Arguments forwarded to f.

Returns

true on success; false on libuv error.

invokeOrThrow

inline

template<typename F, typename... Args> inline void invokeOrThrow(const std::string & message, F && f, Args &&... args)

Invoke a libuv function f with args, throwing on failure.

Identical to [invoke()](#invoke) but throws a std::runtime_error with message prepended if f returns a libuv error code. Must not be called from inside a libuv callback.

Parameters

message Error message prefix used in the thrown exception.
f libuv function to call.
args Arguments forwarded to f.

close

virtual inline

virtual inline void close()

Close and destroy the handle.

Releases the [Context](icy-uv-Context.html#context-2) (which schedules the async uv_close) and then fires [onClose()](#onclose). Safe to call more than once; subsequent calls are no-ops.

ref

inline

inline void ref()

Re-reference the handle with the event loop after a previous [unref()](#unref).

When all handles are unref'd the loop exits automatically. This call reverses that. Has no effect if the handle is not initialized.

unref

inline

inline void unref()

Unreference the handle from the event loop.

The loop will exit when all active handles are unref'd, even if this handle is still alive. Has no effect if the handle is not initialized.

initialized

const inline

inline bool initialized() const

Return true if the handle has been successfully initialized via [init()](#init-8).

active

virtual const inline

virtual inline bool active() const

Return true when the handle is active (libuv uv_is_active).

"Active" has type-specific meaning: a timer is active while counting, a stream is active while connected, etc.

closing

virtual const inline

virtual inline bool closing() const

Return true if uv_close has been called and the handle is awaiting its close callback (libuv uv_is_closing).

closed

virtual const inline

virtual inline bool closed() const

Return true if the handle has been fully closed (context released).

error

const inline

inline const icy::Error & error() const

Return the last error set on this handle, or a default-constructed [Error](icy-Error.html#error) if no error has occurred.

setError

virtual inline

virtual inline void setError(const Error & error)

Set the error state and invoke [onError()](#onerror).

Parameters

error Error value to store and propagate.

setUVError

inline

inline void setUVError(int err, std::string prefix)

Translate a libuv error code into an [Error](icy-Error.html#error) and call [setError()](#seterror-1).

Safe to call from inside libuv callbacks.

Parameters

err libuv error code (negative integer).
prefix Human-readable prefix prepended to the formatted message.

setAndThrowError

inline

inline void setAndThrowError(int err, std::string prefix)

Set the error state from a libuv error code and throw a std::runtime_error.

Must not be called from inside libuv callbacks; use [setUVError()](#setuverror) there.

Parameters

err libuv error code (negative integer).
prefix Human-readable prefix prepended to the thrown message.

throwLastError

inline

inline void throwLastError(std::string prefix)

Throw a std::runtime_error if the handle currently holds an error.

The stored error's message is re-formatted with prefix before throwing. No-op if the handle is not in an error state.

Parameters

prefix Human-readable prefix used when re-formatting the message.

loop

const inline

inline uv::Loop * loop() const

Return the event loop this handle is bound to.

Asserts that the caller is on the owning thread.

Returns

Pointer to the associated uv::Loop.

reset

inline

inline void reset()

Close the current handle (if open) and allocate a fresh [Context](icy-uv-Context.html#context-2), leaving the handle ready to be re-initialized via [init()](#init-8).

get

const inline

template<typename Handle> inline Handle * get() const

Return the raw libuv handle pointer cast to [Handle](#handle-6).

Returns nullptr if the context has been released (handle closed). Asserts that the caller is on the owning thread.

Parameters

[Handle](#handle-6) Target type; defaults to the native handle type T.

Returns

Pointer to the underlying libuv handle, or nullptr.

tid

const inline

inline std::thread::id tid() const

Return the ID of the thread that constructed this handle.

All handle operations must be performed on this thread.

Returns

std::thread::id of the owning thread.

context

const inline

inline IntrusivePtr< Context< T > > context() const

Return the raw [Context](icy-uv-Context.html#context-2) that owns the libuv handle memory.

Primarily for use by subclasses and libuv callbacks that need to access the underlying libuv handle memory.

Returns

A retained reference to the [Context](icy-uv-Context.html#context-2), or an empty reference if closed.

setCloseCleanup

inline

template<typename U> inline void setCloseCleanup(U * data)

clearCloseCleanup

inline

inline void clearCloseCleanup()

assertThread

const inline

inline void assertThread() const

Throw std::logic_error if called from any thread other than the thread that constructed this handle.

Protected Attributes

Return	Name	Description
`uv::Loop *`	`_loop`
`IntrusivePtr< Context< T > >`	`_context`
`std::thread::id`	`_tid`
`Error`	`_error`

_loop

uv::Loop * _loop

_context

IntrusivePtr< Context< T > > _context

_tid

std::thread::id _tid = std::this_thread::get_id()

_error

Error _error

Protected Methods

Return	Name	Description
`void`	`onError` `virtual` `inline`	Called by `[setError()](#seterror-1)` after the error state has been updated.
`void`	`onClose` `virtual` `inline`	Called by `[close()](#close-18)` after the context has been released.
	`Handle`	NonCopyable and NonMovable.
	`Handle`	Deleted constructor.

onError

virtual inline

virtual inline void onError(const Error & error)

Called by [setError()](#seterror-1) after the error state has been updated.

Override to react to errors. The default implementation is a no-op.

Parameters

error The error that was set.

onClose

virtual inline

virtual inline void onClose()

Called by [close()](#close-18) after the context has been released.

Override to perform cleanup on handle closure. The default implementation is a no-op.

Handle

Handle(const Handle &) = delete

NonCopyable and NonMovable.

Handle

Handle(Handle &&) = delete

Deleted constructor.

Public Types

Name	Description
`Type`	Define the native handle type.

Type

T Type()

Define the native handle type.

Built with