task_handle.h File Reference

Observable handle returned by tracked task-posting APIs of MessageLoop and ThreadPool. More...

#include <cstdint>
#include <memory>
#include "./cancellation.h"
#include "./functional.h"
#include "./macros.h"

Include dependency graph for task_handle.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	vlink::PostTaskOptions
	Bundle of optional knobs accepted by tracked task-posting APIs. More...
class	vlink::TaskHandle
	Shared observable handle returned by tracked posting APIs. More...

Namespaces
	vlink

Enumerations
enum class	vlink::TaskExecutionState : uint8_t {   vlink::kInvalid = 0 , vlink::kQueued , vlink::kRunning , vlink::kCompleted ,   vlink::kCancelled , vlink::kDropped , vlink::kRejected , vlink::kFailed }
	Observable lifecycle stage of a tracked task. More...
enum class	vlink::TaskOverflowPolicy : uint8_t { vlink::kUseDispatcherStrategy = 0 , vlink::kReject , vlink::kBlock }
	Per-post override for the bounded-queue overflow strategy. More...
enum class	vlink::TaskDropPolicy : uint8_t { vlink::kDroppable = 0 , vlink::kProtected }
	Whether an accepted task may later be discarded by drop-oldest overflow paths. More...

Detailed Description

Observable handle returned by tracked task-posting APIs of MessageLoop and ThreadPool.

vlink::TaskHandle is a value-typed observer backed by a refcounted shared state block. Copying or moving a handle is cheap and every copy refers to the same task. Destroying every handle does not cancel the underlying task: the dispatcher retains its own reference for the duration of the task lifecycle.

Lifecycle of a tracked task:

*    created ---> kQueued -----> kRunning -----> kCompleted  (terminal)
*      |             |             |          \-> kFailed    (terminal)
*      |             v             v
*      |          kCancelled    kCancelled (cancel observed)
*      |          kDropped      (terminal)
*      v
*    kInvalid / kRejected (terminal)
* 

Types defined here:

Type	Role
TaskExecutionState	Lifecycle stage of a tracked task (queued / running / terminal).
TaskOverflowPolicy	Per-post override for bounded-queue overflow behaviour.
TaskDropPolicy	Whether an accepted task may be discarded by drop-oldest paths.
PostTaskOptions	Aggregate of optional knobs for tracked post_task overloads.
TaskHandle	Observer object handed to the caller.

Lock ordering

TaskHandle's internal state mutex is the innermost mutex in the dispatching layer. The expected order is MessageLoop::AliveState::mtx -> MessageLoop::Impl::mtx -> TaskHandle::State::mtx. TaskHandle::cancel() acquires the cancellation source's internal mutex only after releasing the handle mutex, so the cancellation source is never nested inside any dispatching-layer mutex. Callbacks added through cancellation_token() fire outside TaskHandle::State::mtx, so they may safely re-enter the handle.

Example

vlink::PostTaskOptions opts;
opts.cancellation_token = parent.token();
auto handle = loop.post_task_handle([] { work(); }, opts);
 
if (giving_up) {
  handle.cancel();
}
 
handle.wait();
 
if (handle.state() == vlink::TaskExecutionState::kFailed) {
  inspect_logs();
}

Note

Destroying a TaskHandle does not cancel the task; pair with cancel() when cancellation is required.