vlink::TaskHandle Class Reference

Shared observable handle returned by tracked posting APIs. More...

#include <task_handle.h>

Collaboration diagram for vlink::TaskHandle:

Public Member Functions
	TaskHandle () noexcept
	Constructs an invalid handle that references no task. More...
	~TaskHandle ()
	Destroys the handle reference. More...
	TaskHandle (const TaskHandle &) noexcept
	Copy-constructs a handle that shares state with other. More...
TaskHandle &	operator= (const TaskHandle &) noexcept
	Copy-assigns from another handle; both handles share state afterwards. More...
	TaskHandle (TaskHandle &&) noexcept
	Move-constructs a handle, transferring the shared state from the source. More...
TaskHandle &	operator= (TaskHandle &&) noexcept
	Move-assigns from another handle, transferring its shared state. More...
bool	valid () const noexcept
	Reports whether this handle refers to a live task state block. More...
TaskExecutionState	state () const noexcept
	Returns the current lifecycle stage of the task. More...
bool	is_done () const noexcept
	Reports whether the task has reached a terminal state. More...
CancellationToken	cancellation_token () const noexcept
	Returns the task-local cancellation token associated with this handle. More...
bool	cancel () const
	Requests cooperative cancellation of the task. More...
bool	wait (int timeout_ms=kInfinite) const
	Blocks until the task reaches a terminal state or the timeout elapses. More...

Static Public Attributes
static constexpr int	kInfinite {-1}
	Sentinel timeout value for wait() meaning wait indefinitely. More...

Friends
class	MessageLoop
class	ThreadPool
class	TrackedTask

Detailed Description

Shared observable handle returned by tracked posting APIs.

Backed by a std::shared_ptr to an internal state block, so copies and moves all point at the same task. Provides cooperative cancellation, blocking wait on the terminal state, and a task-local CancellationToken that running callbacks can poll.

Constructor & Destructor Documentation

TaskHandle() [1/3]

vlink::TaskHandle::TaskHandle ( )

noexcept

Constructs an invalid handle that references no task.

valid() returns false and state() returns TaskExecutionState::kInvalid.

~TaskHandle()

vlink::TaskHandle::~TaskHandle

(

)

Destroys the handle reference.

Note

Destruction does not cancel the associated task; the dispatcher retains its own reference to the state block.

TaskHandle() [2/3]

vlink::TaskHandle::TaskHandle ( const TaskHandle &  )

noexcept

Copy-constructs a handle that shares state with other.

TaskHandle() [3/3]

vlink::TaskHandle::TaskHandle ( TaskHandle &&  )

noexcept

Move-constructs a handle, transferring the shared state from the source.

Member Function Documentation

cancel()

bool vlink::TaskHandle::cancel

(

)

const

Requests cooperative cancellation of the task.

No-op when the handle is invalid or already terminal. When the task has not started running (kInvalid or kQueued) this call transitions the state to kCancelled; in any non-terminal case it also flips the cancellation source so running callbacks polling the token observe the request.

Returns

true when this call either transitioned the state or flipped the source; false when the handle was invalid or already terminal.

cancellation_token()

CancellationToken vlink::TaskHandle::cancellation_token ( ) const

noexcept

Returns the task-local cancellation token associated with this handle.

Running callbacks may poll this token for cooperative abort. Callbacks registered on the token fire outside the handle mutex, so they may safely re-enter the handle.

Returns

Associated token; an empty token when the handle is not valid.

is_done()

bool vlink::TaskHandle::is_done ( ) const

noexcept

Reports whether the task has reached a terminal state.

Returns

true once state() is one of kCompleted, kCancelled, kDropped, kRejected or kFailed.

operator=() [1/2]

TaskHandle& vlink::TaskHandle::operator= ( const TaskHandle &  )

noexcept

Copy-assigns from another handle; both handles share state afterwards.

Returns

Reference to *this.

operator=() [2/2]

TaskHandle& vlink::TaskHandle::operator= ( TaskHandle &&  )

noexcept

Move-assigns from another handle, transferring its shared state.

Returns

Reference to *this.

state()

TaskExecutionState vlink::TaskHandle::state ( ) const

noexcept

Returns the current lifecycle stage of the task.

Returns

Latest TaskExecutionState; kInvalid when the handle is not valid.

valid()

bool vlink::TaskHandle::valid ( ) const

noexcept

Reports whether this handle refers to a live task state block.

Returns

false when default-constructed or moved-from.

wait()

bool vlink::TaskHandle::wait

(

int

timeout_ms = kInfinite

)

const

Blocks until the task reaches a terminal state or the timeout elapses.

Never throws on cancellation; inspect state() after the call to distinguish the possible outcomes.

Parameters

timeout_ms

Maximum wait in milliseconds; kInfinite waits forever.

Returns

true when a terminal state was reached before the deadline.

Friends And Related Function Documentation

MessageLoop

friend class MessageLoop

friend

ThreadPool

friend class ThreadPool

friend

TrackedTask

friend class TrackedTask

friend

Member Data Documentation

kInfinite

constexpr int vlink::TaskHandle::kInfinite {-1}

staticconstexpr

Sentinel timeout value for wait() meaning wait indefinitely.

---

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

• include/vlink/base/task_handle.h