DAG node carrying a callback, predecessor and successor links, and run-time state. More...

#include <graph_task.h>

Inheritance diagram for vlink::GraphTask:

Collaboration diagram for vlink::GraphTask:

Public Types
enum	Status : uint8_t { kStatusInActive = 0 , kStatusPending = 1 , kStatusRunning = 2 , kStatusDone = 3 }
	Run-time execution state of a node within an `execute` pass. More...

enum	Policy : uint8_t { kPolicyOnce = 0 , kPolicyMultiple = 1 , kPolicyWaitAll = 2 }
	Policy controlling how many times the task may run within a pass. More...

using	Callback = MoveFunction< void()>
	Callback type for void-returning work nodes. More...

using	ConditionCallback = MoveFunction< int()>
	Callback type for condition nodes; the return value selects an outgoing branch. More...

using	StatusCallback = MoveFunction< void(const std::string &, Status)>
	Status-change notification callback. More...

Public Member Functions
template<class GraphEngineT >
void	execute (GraphEngineT *graph_engine)
	Submits the reachable sub-graph to `graph_engine`. More...

void	cancel ()
	Cancels this node and propagates the cancellation downstream. More...

void	precede (const std::shared_ptr< GraphTask > &task)
	Declares that this node must complete before `task` starts. More...

void	succeed (const std::shared_ptr< GraphTask > &task)
	Declares that `task` must complete before this node starts. More...

uint32_t	register_status_callback (StatusCallback &&callback)
	Subscribes a callback to status transitions on this node. More...

bool	unregister_status_callback (uint32_t id)
	Removes a previously registered status callback by id. More...

void	clear_status_callbacks ()
	Removes every status callback subscription on this node. More...

void	set_name (const std::string &name)
	Sets the node name used in DOT output and status callbacks. More...

void	set_group_name (const std::string &name)
	Sets a group name used to visually cluster nodes in DOT output. More...

void	set_condition_number (int condition_number)
	Sets the number of outgoing condition branches. More...

void	set_priority (uint16_t priority)
	Sets the dispatch priority used by priority-aware engines. More...

void	set_max_recursion_depth (uint32_t depth)
	Sets the maximum recursion depth that bounds DFS traversals. More...

void	set_policy (Policy policy)
	Sets the execution policy for this node. More...

std::string	get_name () const
	Returns the node name. More...

std::string	get_group_name () const
	Returns the group name. More...

int	get_condition_number () const
	Returns the configured branch count. More...

uint16_t	get_priority () const
	Returns the configured dispatch priority. More...

uint32_t	get_max_recursion_depth () const
	Returns the maximum recursion depth used for cycle detection. More...

Policy	get_policy () const
	Returns the configured execution policy. More...

Status	get_status () const
	Returns the current execution status of this node. More...

void	remove_precede_task (const std::shared_ptr< GraphTask > &task)
	Removes an outgoing edge created by `precede`. More...

void	remove_succeed_task (const std::shared_ptr< GraphTask > &task)
	Removes an incoming edge created by `succeed`. More...

std::vector< std::weak_ptr< GraphTask > >	get_precede_task_list () const
	Returns the current predecessor list as weak pointers. More...

std::vector< std::weak_ptr< GraphTask > >	get_succeed_task_list () const
	Returns the current successor list as weak pointers. More...

bool	is_condition_task () const
	Reports whether this node was created via `create_condition`. More...

bool	has_cycle () const
	Detects whether the reachable sub-graph contains a cycle. More...

std::string	export_to_dot () const
	Exports the reachable sub-graph as a Graphviz DOT document. More...

Static Public Member Functions
static std::shared_ptr< GraphTask >	create (Callback &&callback, int condition_number=0)
	Creates a regular work node. More...

static std::shared_ptr< GraphTask >	create (const std::string &name, Callback &&callback, int condition_number=0)
	Creates a named regular work node. More...

static std::shared_ptr< GraphTask >	create_condition (ConditionCallback &&callback, int condition_number=0)
	Creates a condition node whose return value selects a successor branch. More...

static std::shared_ptr< GraphTask >	create_condition (const std::string &name, ConditionCallback &&callback, int condition_number=0)
	Creates a named condition node. More...

Protected Types
using	FindTaskCallback = MoveFunction< void(const std::shared_ptr< GraphTask > &)>

Protected Member Functions
	GraphTask (Callback &&callback, int condition_number)

	GraphTask (const std::string &name, Callback &&callback, int condition_number)

	GraphTask (ConditionCallback &&callback, int condition_number)

	GraphTask (const std::string &name, ConditionCallback &&callback, int condition_number)

	~GraphTask ()

void	process_and_traverse (FindTaskCallback &&callback)

Detailed Description

DAG node carrying a callback, predecessor and successor links, and run-time state.

Must be created through the create / create_condition factories so callbacks share std::enable_shared_from_this safely. execute traverses the reachable sub-graph and submits ready tasks to a user-supplied engine.

Member Typedef Documentation

◆ Callback

using vlink::GraphTask::Callback = MoveFunction<void()>

Callback type for void-returning work nodes.

◆ ConditionCallback

using vlink::GraphTask::ConditionCallback = MoveFunction<int()>

Callback type for condition nodes; the return value selects an outgoing branch.

◆ FindTaskCallback

using vlink::GraphTask::FindTaskCallback = MoveFunction<void(const std::shared_ptr<GraphTask>&)>

protected

◆ StatusCallback

using vlink::GraphTask::StatusCallback = MoveFunction<void(const std::string&, Status)>

Status-change notification callback.

Invoked with the task name and the new status whenever the node transitions.

Member Enumeration Documentation

◆ Policy

enum vlink::GraphTask::Policy : uint8_t

Policy controlling how many times the task may run within a pass.

Enumerator
kPolicyOnce	Run exactly once per `execute` pass (default).
kPolicyMultiple	Allow multiple invocations within the pass.
kPolicyWaitAll	Wait for every predecessor before running.

◆ Status

enum vlink::GraphTask::Status : uint8_t

Run-time execution state of a node within an execute pass.

Enumerator
kStatusInActive	Not yet submitted or cancelled.
kStatusPending	Waiting for predecessors to complete.
kStatusRunning	Currently executing.
kStatusDone	Execution finished.

Constructor & Destructor Documentation

◆ GraphTask() [1/4]

vlink::GraphTask::GraphTask	(	Callback &&	callback,
		int	condition_number
	)

explicitprotected

◆ GraphTask() [2/4]

vlink::GraphTask::GraphTask	(	const std::string &	name,
		Callback &&	callback,
		int	condition_number
	)

explicitprotected

◆ GraphTask() [3/4]

vlink::GraphTask::GraphTask	(	ConditionCallback &&	callback,
		int	condition_number
	)

explicitprotected

◆ GraphTask() [4/4]

vlink::GraphTask::GraphTask	(	const std::string &	name,
		ConditionCallback &&	callback,
		int	condition_number
	)

explicitprotected

◆ ~GraphTask()

vlink::GraphTask::~GraphTask ( )

protected

Member Function Documentation

◆ cancel()

void vlink::GraphTask::cancel ( )

Cancels this node and propagates the cancellation downstream.

Sets this node's status to kStatusInActive and walks the successor list forward marking every reachable node inactive. Predecessors are unaffected. Inactive nodes are skipped by the engine and by downstream kPolicyWaitAll counters.

◆ clear_status_callbacks()

void vlink::GraphTask::clear_status_callbacks ( )

Removes every status callback subscription on this node.

◆ create() [1/2]

static std::shared_ptr<GraphTask> vlink::GraphTask::create	(	Callback &&	callback,
		int	condition_number = `0`
	)

static

Creates a regular work node.

Parameters

callback	Work function.
condition_number	Number of outgoing branches (`0` disables branching).

Returns: Shared pointer to the new task.

◆ create() [2/2]

static std::shared_ptr<GraphTask> vlink::GraphTask::create	(	const std::string &	name,
		Callback &&	callback,
		int	condition_number = `0`
	)

static

Creates a named regular work node.

Parameters

name	Node name used in DOT output and status callbacks.
callback	Work function.
condition_number	Number of outgoing branches.

Returns: Shared pointer to the new task.

◆ create_condition() [1/2]

static std::shared_ptr<GraphTask> vlink::GraphTask::create_condition	(	ConditionCallback &&	callback,
		int	condition_number = `0`
	)

static

Creates a condition node whose return value selects a successor branch.

Parameters

callback	Predicate returning the branch index.
condition_number	Number of branches accepted; out-of-range returns skip all successors.

Returns: Shared pointer to the new condition task.

◆ create_condition() [2/2]

static std::shared_ptr<GraphTask> vlink::GraphTask::create_condition	(	const std::string &	name,
		ConditionCallback &&	callback,
		int	condition_number = `0`
	)

static

Creates a named condition node.

Parameters

name	Node name.
callback	Predicate returning the branch index.
condition_number	Branch count.

Returns: Shared pointer to the new condition task.

◆ execute()

template<class GraphEngineT >

void vlink::GraphTask::execute ( GraphEngineT * graph_engine )

inline

Submits the reachable sub-graph to graph_engine.

Details.

Traverses the sub-graph, identifies ready nodes and posts them via post_task or post_task_with_priority when available. Compatible with MessageLoop, MultiLoop and ThreadPool.

Template Parameters

GraphEngineT Engine type exposing post_task and optionally post_task_with_priority.

Parameters

graph_engine Target engine instance.

Here is the call graph for this function:

◆ export_to_dot()

std::string vlink::GraphTask::export_to_dot ( ) const

Exports the reachable sub-graph as a Graphviz DOT document.

Returns: DOT source string.

◆ get_condition_number()

int vlink::GraphTask::get_condition_number ( ) const

Returns the configured branch count.

Returns: Branch count.

◆ get_group_name()

std::string vlink::GraphTask::get_group_name ( ) const

Returns the group name.

Returns: Group name.

◆ get_max_recursion_depth()

uint32_t vlink::GraphTask::get_max_recursion_depth ( ) const

Returns the maximum recursion depth used for cycle detection.

Returns: Recursion depth bound.

◆ get_name()

std::string vlink::GraphTask::get_name ( ) const

Returns the node name.

Returns: Node name.

◆ get_policy()

Policy vlink::GraphTask::get_policy ( ) const

Returns the configured execution policy.

Returns: Policy enumerator.

◆ get_precede_task_list()

std::vector<std::weak_ptr<GraphTask> > vlink::GraphTask::get_precede_task_list ( ) const

Returns the current predecessor list as weak pointers.

Returns: Vector of weak predecessor pointers.

◆ get_priority()

uint16_t vlink::GraphTask::get_priority ( ) const

Returns the configured dispatch priority.

Returns: Priority value.

◆ get_status()

Status vlink::GraphTask::get_status ( ) const

Returns the current execution status of this node.

Returns: Status enumerator.

◆ get_succeed_task_list()

std::vector<std::weak_ptr<GraphTask> > vlink::GraphTask::get_succeed_task_list ( ) const

Returns the current successor list as weak pointers.

Returns: Vector of weak successor pointers.

◆ has_cycle()

bool vlink::GraphTask::has_cycle ( ) const

Detects whether the reachable sub-graph contains a cycle.

Iterative DFS with a recursion stack. Acquires per-node mutexes one at a time and does not take the global topology mutex; safe to call from status callbacks fired by invoke or cancel.

Returns: true when a cycle is found or the recursion bound is exceeded.

◆ is_condition_task()

bool vlink::GraphTask::is_condition_task ( ) const

Reports whether this node was created via create_condition.

Returns: true for condition nodes.

◆ precede()

void vlink::GraphTask::precede ( const std::shared_ptr< GraphTask > & task )

Declares that this node must complete before task starts.

Runs a reachability pre-check on task 's downstream cone before mutating any list; the edge is rejected (with an error log) if it would form a cycle. On success task is appended to this node's successor list and this node is appended to task 's predecessor list. Topology mutation is serialised by a process-wide recursive mutex shared across every GraphTask instance, so concurrent writers are safe; read paths (execute, has_cycle, export_to_dot) read per-node snapshots without taking that mutex.

Parameters

task	Successor node.

◆ process_and_traverse()

void vlink::GraphTask::process_and_traverse ( FindTaskCallback && callback )

protected

Here is the caller graph for this function:

◆ register_status_callback()

uint32_t vlink::GraphTask::register_status_callback ( StatusCallback && callback )

Subscribes a callback to status transitions on this node.

Each call appends a new subscriber. On every status change the node snapshots the current subscriber set under status_callbacks_mtx, releases the lock, then invokes the snapshot in unspecified order. Because callbacks fire without the mutex held they may freely register / unregister callbacks on the same node; such mutations apply on the next transition. Exceptions are caught and logged; remaining subscribers still fire.

Parameters

callback Status change callback.

Returns: Subscription id (>0). Returns 0 when callback is empty.

◆ remove_precede_task()

void vlink::GraphTask::remove_precede_task ( const std::shared_ptr< GraphTask > & task )

Removes an outgoing edge created by precede.

Removes task from the successor list and removes this node from task 's predecessor list. Logs an error when the edge does not exist.

Parameters

task	Previously attached successor.

◆ remove_succeed_task()

void vlink::GraphTask::remove_succeed_task ( const std::shared_ptr< GraphTask > & task )

Removes an incoming edge created by succeed.

Parameters

task	Previously attached predecessor.

◆ set_condition_number()

void vlink::GraphTask::set_condition_number ( int condition_number )

Sets the number of outgoing condition branches.

Parameters

condition_number Branch count.

◆ set_group_name()

void vlink::GraphTask::set_group_name ( const std::string & name )

Sets a group name used to visually cluster nodes in DOT output.

Parameters

name	Group name.

◆ set_max_recursion_depth()

void vlink::GraphTask::set_max_recursion_depth ( uint32_t depth )

Sets the maximum recursion depth that bounds DFS traversals.

Traversals exceeding this depth treat the graph as conservatively cyclic. Default: 10000.

Parameters

depth Maximum recursion depth.

◆ set_name()

void vlink::GraphTask::set_name ( const std::string & name )

Sets the node name used in DOT output and status callbacks.

Parameters

name	Node name.

◆ set_policy()

void vlink::GraphTask::set_policy ( Policy policy )

Sets the execution policy for this node.

Parameters

policy Policy enumerator.

◆ set_priority()

void vlink::GraphTask::set_priority ( uint16_t priority )

Sets the dispatch priority used by priority-aware engines.

Parameters

priority Priority value.

◆ succeed()

void vlink::GraphTask::succeed ( const std::shared_ptr< GraphTask > & task )

Declares that task must complete before this node starts.

Mirror of precede; rejects edges that would form a cycle. Shares the same single-writer topology mutex as precede.

Parameters

task	Predecessor node.

◆ unregister_status_callback()

bool vlink::GraphTask::unregister_status_callback ( uint32_t id )

Removes a previously registered status callback by id.

Parameters

id	Subscription id returned by `register_status_callback`.

Returns: true when the subscription was found and removed.

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

include/vlink/base/graph_task.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Detailed Description

Member Typedef Documentation

◆ Callback

◆ ConditionCallback

◆ FindTaskCallback

◆ StatusCallback

Member Enumeration Documentation

◆ Policy

◆ Status

Constructor & Destructor Documentation

◆ GraphTask() [1/4]

◆ GraphTask() [2/4]

◆ GraphTask() [3/4]

◆ GraphTask() [4/4]

◆ ~GraphTask()

Member Function Documentation

◆ cancel()

◆ clear_status_callbacks()

◆ create() [1/2]

◆ create() [2/2]

◆ create_condition() [1/2]

◆ create_condition() [2/2]

◆ execute()

◆ export_to_dot()

◆ get_condition_number()

◆ get_group_name()

◆ get_max_recursion_depth()

◆ get_name()

◆ get_policy()

◆ get_precede_task_list()

◆ get_priority()

◆ get_status()

◆ get_succeed_task_list()

◆ has_cycle()

◆ is_condition_task()

◆ precede()

◆ process_and_traverse()

◆ register_status_callback()

◆ remove_precede_task()

◆ remove_succeed_task()

◆ set_condition_number()

◆ set_group_name()

◆ set_max_recursion_depth()

◆ set_name()

◆ set_policy()

◆ set_priority()

◆ succeed()

◆ unregister_status_callback()