Handle

#include <icy/handle.h>

template<typename T>
class Handle

Defined in src/base/include/icy/handle.h:133

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.
	`~Handle` virtual inline
`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()`.
`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()`.
`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` if no error has occurred.
`void`	`setError` virtual inline	Set the error state and invoke `onError()`.
`void`	`setUVError` inline	Translate a libuv error code into an `Error` and call `setError()`.
`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`, leaving the handle ready to be re-initialized via `init()`.
`Handle` *	`get` const inline	Return the raw libuv handle pointer cast to `Handle`.
`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` that owns the libuv handle memory.
`T *`	`rawPtr` const inline	Return the raw libuv handle pointer without retaining the `Context`.
`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.

inline

inline Handle(uv::Loop * loop = uv::defaultLoop())

Defined in src/base/include/icy/handle.h:140

Construct the handle bound to the given event loop.

Parameters

Parameter	Type	Description
`loop`	`uv::Loop` *	Event loop to associate this handle with. Defaults to the process-wide default loop.

~Handle

virtual inline

virtual inline ~Handle()

Defined in src/base/include/icy/handle.h:146

init

inline

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

Defined in src/base/include/icy/handle.h:161

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.

Returns

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

Parameters

Parameter	Type	Description
`f`	`F &&`	libuv init function (e.g. `uv_tcp_init`).
`args`	`Args &&...`	Additional arguments forwarded after the loop and handle pointer.

invoke

inline

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

Defined in src/base/include/icy/handle.h:183

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.

Returns

true on success; false on libuv error.

Parameters

Parameter	Type	Description
`f`	`F &&`	libuv function to call.
`args`	`Args &&...`	Arguments forwarded to `f`.

invokeOrThrow

inline

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

Defined in src/base/include/icy/handle.h:204

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

Identical to 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

Parameter	Type	Description
`message`	`const std::string &`	Error message prefix used in the thrown exception.
`f`	`F &&`	libuv function to call.
`args`	`Args &&...`	Arguments forwarded to `f`.

close

virtual inline

virtual inline void close()

Defined in src/base/include/icy/handle.h:218

Close and destroy the handle.

Releases the Context (which schedules the async uv_close) and then fires onClose(). Safe to call more than once; subsequent calls are no-ops.

Reimplemented by

ref

inline

inline void ref()

Defined in src/base/include/icy/handle.h:235

Re-reference the handle with the event loop after a previous 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()

Defined in src/base/include/icy/handle.h:245

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

Defined in src/base/include/icy/handle.h:252

Return true if the handle has been successfully initialized via init().

active

virtual const inline

virtual inline bool active() const

Defined in src/base/include/icy/handle.h:261

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

Defined in src/base/include/icy/handle.h:268

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

Defined in src/base/include/icy/handle.h:274

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

Reimplemented by

error

const inline

inline const icy::Error & error() const

Defined in src/base/include/icy/handle.h:281

Return the last error set on this handle, or a default-constructed Error if no error has occurred.

setError

virtual inline

virtual inline void setError(const Error & error)

Defined in src/base/include/icy/handle.h:289

Set the error state and invoke onError().

Reimplemented by

Parameters

Parameter	Type	Description
`error`	const `Error` &	Error value to store and propagate.

setUVError

inline

inline void setUVError(int err, std::string prefix = "UV Error")

Defined in src/base/include/icy/handle.h:303

Translate a libuv error code into an Error and call setError().

Safe to call from inside libuv callbacks.

Parameters

Parameter	Type	Description
`err`	`int`	libuv error code (negative integer).
`prefix`	`std::string`	Human-readable prefix prepended to the formatted message.

setAndThrowError

inline

inline void setAndThrowError(int err, std::string prefix = "UV Error")

Defined in src/base/include/icy/handle.h:317

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() there.

Parameters

Parameter	Type	Description
`err`	`int`	libuv error code (negative integer).
`prefix`	`std::string`	Human-readable prefix prepended to the thrown message.

throwLastError

inline

inline void throwLastError(std::string prefix = "UV Error")

Defined in src/base/include/icy/handle.h:329

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

Parameter	Type	Description
`prefix`	`std::string`	Human-readable prefix used when re-formatting the message.

loop

const inline

inline uv::Loop * loop() const

Defined in src/base/include/icy/handle.h:340

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()

Defined in src/base/include/icy/handle.h:348

Close the current handle (if open) and allocate a fresh Context, leaving the handle ready to be re-initialized via init().

get

const inline

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

Defined in src/base/include/icy/handle.h:363

Return the raw libuv handle pointer cast to Handle.

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

Returns

Pointer to the underlying libuv handle, or nullptr.

tid

const inline

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

Defined in src/base/include/icy/handle.h:374

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

Defined in src/base/include/icy/handle.h:385

Return the raw Context 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, or an empty reference if closed.

rawPtr

const inline

inline T * rawPtr() const

Defined in src/base/include/icy/handle.h:398

Return the raw libuv handle pointer without retaining the Context.

The intrusive refcount is non-atomic and owned by the loop thread, so cross-thread callers (e.g. Synchronizer::post()) must use this accessor with external synchronization against close() rather than copying the context.

Returns

Pointer to the underlying libuv handle, or nullptr if closed.

setCloseCleanup

inline

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

Defined in src/base/include/icy/handle.h:404

clearCloseCleanup

inline

inline void clearCloseCleanup()

Defined in src/base/include/icy/handle.h:413

assertThread

const inline

inline void assertThread() const

Defined in src/base/include/icy/handle.h:421

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

Type: uv::Loop *

Defined in src/base/include/icy/handle.h:456

_context

IntrusivePtr< Context< T > > _context

Type: IntrusivePtr< Context< T > >

Defined in src/base/include/icy/handle.h:457

_tid

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

Defined in src/base/include/icy/handle.h:458

_error

Error _error

Type: Error

Defined in src/base/include/icy/handle.h:459

Protected Methods

Return	Name	Description
`void`	`onError` virtual inline	Called by `setError()` after the error state has been updated.
`void`	`onClose` virtual inline	Called by `close()` after the context has been released.
	`Handle`	NonCopyable and NonMovable.
`Handle` &	`operator=`	Deleted assignment operator.
	`Handle`	Deleted constructor.
`Handle` &	`operator=`	Deleted assignment operator.

onError

virtual inline

virtual inline void onError(const Error & error)

Defined in src/base/include/icy/handle.h:437

Called by setError() after the error state has been updated.

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

Reimplemented by

Parameters

Parameter	Type	Description
`error`	const `Error` &	The error that was set.

onClose

virtual inline

virtual inline void onClose()

Defined in src/base/include/icy/handle.h:445

Called by close() after the context has been released.

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

Reimplemented by

Handle

Handle(const Handle &) = delete

Defined in src/base/include/icy/handle.h:451

NonCopyable and NonMovable.

operator=

Handle & operator=(const Handle &) = delete

Defined in src/base/include/icy/handle.h:452

Deleted assignment operator.

Handle

Handle(Handle &&) = delete

Defined in src/base/include/icy/handle.h:453

Deleted constructor.

operator=

Handle & operator=(Handle &&) = delete

Defined in src/base/include/icy/handle.h:454

Deleted assignment operator.

Public Types

Name	Description
`Type`	Define the native handle type.

Type

using Type = T

Defined in src/base/include/icy/handle.h:429

Define the native handle type.