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.

List of all members

Name	Kind	Owner
`Handle`	`function`	Declared here
`~Handle`	`function`	Declared here
`init`	`function`	Declared here
`invoke`	`function`	Declared here
`invokeOrThrow`	`function`	Declared here
`close`	`function`	Declared here
`ref`	`function`	Declared here
`unref`	`function`	Declared here
`initialized`	`function`	Declared here
`active`	`function`	Declared here
`closing`	`function`	Declared here
`closed`	`function`	Declared here
`error`	`function`	Declared here
`setError`	`function`	Declared here
`setUVError`	`function`	Declared here
`setAndThrowError`	`function`	Declared here
`throwLastError`	`function`	Declared here
`loop`	`function`	Declared here
`reset`	`function`	Declared here
`get`	`function`	Declared here
`tid`	`function`	Declared here
`context`	`function`	Declared here
`setCloseCleanup`	`function`	Declared here
`clearCloseCleanup`	`function`	Declared here
`assertThread`	`function`	Declared here
`_loop`	`variable`	Declared here
`_context`	`variable`	Declared here
`_tid`	`variable`	Declared here
`_error`	`variable`	Declared here
`onError`	`function`	Declared here
`onClose`	`function`	Declared here
`Handle`	`function`	Declared here
`operator=`	`function`	Declared here
`Handle`	`function`	Declared here
`operator=`	`function`	Declared here
`Type`	`typedef`	Declared here

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 = uv::defaultLoop())

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

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)

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.

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)

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.

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)

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

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

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

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.

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()](#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()](#init-8).

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](icy-Error.html#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()](#onerror).

Parameters

error Error value to store and propagate.

Reimplemented by

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](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 = "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()](#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 = "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

prefix 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](uv.html#loop-1).

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](icy-uv-Context.html#context-2), leaving the handle ready to be re-initialized via [init()](#init-8).

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](#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

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

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

clearCloseCleanup

inline

inline void clearCloseCleanup()

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

assertThread

const inline

inline void assertThread() const

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

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

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

_context

IntrusivePtr< Context< T > > _context

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

_tid

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

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

_error

Error _error

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

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)

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

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.

Reimplemented by

onClose

virtual inline

virtual inline void onClose()

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

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.

Reimplemented by

Handle

Handle(const Handle &) = delete

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

NonCopyable and NonMovable.

Handle

Handle(Handle &&) = delete

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

Deleted constructor.

Public Types

Name	Description
`Type`	Define the native handle type.

Type

using Type = T

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

Define the native handle type.