Node in a directed acyclic task graph supporting condition branching and parallel execution. 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 }
	Execution state of the task within a single `execute()` pass. More...
enum	Policy : uint8_t { kPolicyOnce = 0 , kPolicyMultiple = 1 , kPolicyWaitAll = 2 }
	Execution policy controlling how many times and when the task runs. More...
using	Callback = std::function<void()>
	Callback type for regular (void-returning) tasks.
using	ConditionCallback = std::function<int()>
	Callback type for condition tasks; returns the branch index to activate.
using	StatusCallback = std::function<void(const std::string&, Status)>
	Callback for status change notifications.

Public Member Functions
template<class GraphEngineT>
void	execute (GraphEngineT *graph_engine)
	Submits this task (and all reachable successors) to a graph execution engine.
void	cancel ()
	Cancels this task; sets its status to `kStatusInActive`.
void	precede (const std::shared_ptr< GraphTask > &task)
	Declares that this task must complete before `task` starts.
void	succeed (const std::shared_ptr< GraphTask > &task)
	Declares that `task` must complete before this task starts.
void	register_status_callback (StatusCallback &&callback)
	Registers a callback invoked whenever this task's status changes.
void	set_name (const std::string &name)
	Sets the task name used in DOT export and status callbacks.
void	set_group_name (const std::string &name)
	Sets a group name for visual grouping in DOT export.
void	set_condition_number (int condition_number)
	Sets the number of condition branches this task can select.
void	set_priority (uint16_t priority)
	Sets the task dispatch priority (used by priority-aware engines).
void	set_max_recursion_depth (uint32_t depth)
	Sets the maximum recursion depth to guard against infinitely deep graphs.
void	set_policy (Policy policy)
	Sets the execution policy.
std::string	get_name () const
	Returns the task name.
std::string	get_group_name () const
	Returns the group name.
int	get_condition_number () const
	Returns the number of condition branches.
uint16_t	get_priority () const
	Returns the dispatch priority.
uint32_t	get_max_recursion_depth () const
	Returns the maximum recursion depth.
Policy	get_policy () const
	Returns the execution policy.
Status	get_status () const
	Returns the current execution status of this task.
void	remove_precede_task (const std::shared_ptr< GraphTask > &task)
	Removes a previously added predecessor dependency.
void	remove_succeed_task (const std::shared_ptr< GraphTask > &task)
	Removes a previously added successor dependency.
std::vector< std::weak_ptr< GraphTask > >	get_precede_task_list () const
	Returns the list of predecessor tasks (this task depends on them).
std::vector< std::weak_ptr< GraphTask > >	get_succeed_task_list () const
	Returns the list of successor tasks (they depend on this task).
bool	is_condition_task () const
	Returns `true` if this task was created with `create_condition()`.
bool	has_cycle () const
	Detects whether the reachable sub-graph contains any cycles.
std::string	export_to_dot () const
	Exports the reachable sub-graph as a Graphviz DOT string.

Static Public Member Functions
static std::shared_ptr< GraphTask >	create (Callback &&callback, int condition_number=0)
	Creates a regular (void) task node.
static std::shared_ptr< GraphTask >	create (const std::string &name, Callback &&callback, int condition_number=0)
	Creates a named regular (void) task node.
static std::shared_ptr< GraphTask >	create_condition (ConditionCallback &&callback, int condition_number=0)
	Creates a condition task that returns a branch index.
static std::shared_ptr< GraphTask >	create_condition (const std::string &name, ConditionCallback &&callback, int condition_number=0)
	Creates a named condition task.

Protected Types
using	FindTaskCallback = std::function<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 (const FindTaskCallback &callback)

Detailed Description

Node in a directed acyclic task graph supporting condition branching and parallel execution.

Must be created via one of the static factory methods (create / create_condition). Inherits from std::enable_shared_from_this to safely pass shared_ptr to internal callbacks.

Member Typedef Documentation

◆ Callback

using vlink::GraphTask::Callback = std::function<void()>

Callback type for regular (void-returning) tasks.

◆ ConditionCallback

using vlink::GraphTask::ConditionCallback = std::function<int()>

Callback type for condition tasks; returns the branch index to activate.

◆ FindTaskCallback

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

protected

◆ StatusCallback

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

Callback for status change notifications.

Called whenever the task's Status changes. First argument is the task name; second is the new status.

Member Enumeration Documentation

◆ Policy

enum vlink::GraphTask::Policy : uint8_t

Execution policy controlling how many times and when the task runs.

Enumerator
kPolicyOnce	Run exactly once per execute() call (default).
kPolicyMultiple	Allow multiple invocations in a single pass.
kPolicyWaitAll	Wait for ALL predecessors before running.

◆ Status

enum vlink::GraphTask::Status : uint8_t

Execution state of the task within a single execute() pass.

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

Constructor & Destructor Documentation

◆ GraphTask() [1/4]

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

explicitprotected

Here is the caller graph for this function:

◆ 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 task; sets its status to kStatusInActive.

A cancelled task will not be executed even if all its predecessors complete.

◆ create() [1/2]

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

staticnodiscard

Creates a regular (void) task node.

Parameters

callback	Work function to execute.
condition_number	Number of successor branches available. 0 = no branches.

Returns: Shared pointer to the new task.

◆ create() [2/2]

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

staticnodiscard

Creates a named regular (void) task node.

Parameters

name	Task name (used in DOT export and status callbacks).
callback	Work function to execute.
condition_number	Number of successor branches available. 0 = no branches.

Returns: Shared pointer to the new task.

◆ create_condition() [1/2]

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

staticnodiscard

Creates a condition task that returns a branch index.

The integer returned by callback selects which successor sub-graph to activate. Return values outside [0, condition_number) skip all successors.

Parameters

callback	Condition function returning the branch index.
condition_number	Number of possible branches.

Returns: Shared pointer to the new condition task.

◆ create_condition() [2/2]

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

staticnodiscard

Creates a named condition task.

Parameters

name	Task name.
callback	Condition function returning the branch index.
condition_number	Number of possible branches.

Returns: Shared pointer to the new condition task.

Here is the call graph for this function:

◆ execute()

template<class GraphEngineT>

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

inline

Submits this task (and all reachable successors) to a graph execution engine.

Details.

Traverses the reachable sub-graph, identifies tasks whose predecessors have all completed, and posts them to graph_engine using either post_task() or post_task_with_priority() (if available).

Template Parameters

GraphEngineT Any type providing post_task(Callback) and optionally post_task_with_priority(Callback, uint16_t). MessageLoop, MultiLoop and ThreadPool all satisfy this.

Parameters

graph_engine Pointer to the execution engine.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ export_to_dot()

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

nodiscard

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

The DOT output can be passed to dot -Tpng to produce a dependency diagram.

Returns: DOT language string representing the task graph.

◆ get_condition_number()

int vlink::GraphTask::get_condition_number ( ) const

nodiscard

Returns the number of condition branches.

Returns: Condition number.

◆ get_group_name()

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

nodiscard

Returns the group name.

Returns: Group name string.

◆ get_max_recursion_depth()

uint32_t vlink::GraphTask::get_max_recursion_depth ( ) const

nodiscard

Returns the maximum recursion depth.

Returns: Max recursion depth. Default is 10000.

◆ get_name()

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

nodiscard

Returns the task name.

Returns: Task name string.

◆ get_policy()

Policy vlink::GraphTask::get_policy ( ) const

nodiscard

Returns the execution policy.

Returns: Policy value.

◆ get_precede_task_list()

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

nodiscard

Returns the list of predecessor tasks (this task depends on them).

Returns: Vector of weak pointers to predecessor tasks.

◆ get_priority()

uint16_t vlink::GraphTask::get_priority ( ) const

nodiscard

Returns the dispatch priority.

Returns: Priority value.

◆ get_status()

Status vlink::GraphTask::get_status ( ) const

nodiscard

Returns the current execution status of this task.

Returns: Status value.

◆ get_succeed_task_list()

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

nodiscard

Returns the list of successor tasks (they depend on this task).

Returns: Vector of weak pointers to successor tasks.

◆ has_cycle()

bool vlink::GraphTask::has_cycle ( ) const

nodiscard

Detects whether the reachable sub-graph contains any cycles.

Uses DFS with a recursion stack to find back edges. A cycle-free graph is required for correct execute() behaviour.

Returns: true if a cycle is detected.

◆ is_condition_task()

bool vlink::GraphTask::is_condition_task ( ) const

nodiscard

Returns true if this task was created with create_condition().

Returns: true for condition tasks.

◆ precede()

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

Declares that this task must complete before task starts.

Equivalent to task->succeed(this_task).

Parameters

task	Successor task.

◆ process_and_traverse()

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

protected

Here is the call graph for this function:

Here is the caller graph for this function:

◆ register_status_callback()

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

Registers a callback invoked whenever this task's status changes.

Parameters

callback Called with (name, new_status) on every status transition.

◆ remove_precede_task()

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

Removes a previously added predecessor dependency.

Parameters

task	The predecessor to remove.

◆ remove_succeed_task()

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

Removes a previously added successor dependency.

Parameters

task	The successor to remove.

◆ set_condition_number()

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

Sets the number of condition branches this task can select.

Parameters

condition_number Branch count (used for condition tasks).

◆ set_group_name()

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

Sets a group name for visual grouping in DOT export.

Parameters

name	Group name string.

◆ set_max_recursion_depth()

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

Sets the maximum recursion depth to guard against infinitely deep graphs.

If a task graph exceeds this depth during execution, a kFatal log is emitted. The default value is 10000.

Parameters

depth Maximum depth.

◆ set_name()

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

Sets the task name used in DOT export and status callbacks.

Parameters

name	Task name string.

◆ set_policy()

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

Sets the execution policy.

Parameters

policy See Policy enum.

◆ set_priority()

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

Sets the task 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 task starts.

Equivalent to task->precede(this_task).

Parameters

task	Predecessor task.

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

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