Algorithm

Inherits from: Task

Overview
Features
Class Interface
Signals
Usage Example
The Dirty State
Asynchronous Execution
Cancellation Mechanism
Lifecycle
Best Practices

The Algorithm class is a core component of the task library that provides a framework for implementing executable algorithms with standardized signaling, progress reporting, and execution control. It extends the base Task class to add algorithm-specific functionality including execution state tracking, cancellation support, and dirty state management.

Features

Standardized Execution: Common interface for algorithm implementation and execution
Progress Reporting: Built-in mechanism for reporting execution progress
Cancellation Support: Ability to request and detect stop requests during execution
State Management: Tracking of "dirty" state to determine if re-execution is needed
Asynchronous Execution: Support for running algorithms in background threads
Signal-Based Communication: Events for algorithm lifecycle (started, finished, errors)
Execution Arguments: Flexible argument passing mechanism via ArgumentPack

Class Interface

Signals

Algorithm emits the following signals:

Signal	Type	Description	Arguments
progress data	Data	Reports execution progress	float (0.0 to 1.0)
started simple	Simple	Indicates algorithm has started execution	None
finished simple	Simple	Indicates algorithm has completed execution	None
error data	Data	Reports execution errors	std::string (error message)

Usage Example

Algorithm Implementation Example

Using the Algorithm

The Dirty State

The Algorithm class maintains a "dirty" state that indicates whether the algorithm needs to be re-executed:

isDirty(): Returns true if the algorithm's input has changed since last execution
setDirty(bool): Explicitly sets the dirty state

This mechanism is useful for:

Avoiding unnecessary re-execution
Forcing re-execution when needed
Tracking when inputs have changed

Note: Setting dirty to true while an algorithm is running causes a stop request to be issued.

Asynchronous Execution

The run() method provides asynchronous execution using C++ futures:

This allows algorithms to run in the background without blocking the main thread.

Cancellation Mechanism

Algorithms can be cancelled during execution:

Requesting Cancellation: Call stop() to set the stop flag
Checking for Cancellation: Algorithm should periodically call stopRequested()
Handling Cancellation: If stop is requested, algorithm can clean up and exit

Handling Cancellation

Lifecycle

An Algorithm goes through the following lifecycle:

Construction: Internal state initialized (dirty=true, running=false, stopRequested=false)
Configuration: Algorithm-specific parameters set by calling its methods
Execution Start: run() or runImpl() called, emits "started" signal
Execution: exec() implementation runs, may report progress
Execution End: Algorithm completes, emits "finished" signal
Error Handling: If an exception occurs, emits "error" signal with details

This lifecycle can be repeated multiple times for the same algorithm instance.

The implementation of runImpl() automatically handles the proper emission of "started" and "finished" signals, as well as the management of the m_isRunning state flag.

Implementation Details

Here's a simplified view of the key implementation methods:

Constructor Implementation

Progress Reporting Implementation

Asynchronous Execution Implementation

Run Implementation

Best Practices

Check Stop Requests: Call stopRequested() regularly during long-running operations
Report Progress: Use reportProgress() to provide feedback on execution status
Handle Exceptions: Catch and report exceptions specific to your algorithm
Manage Dirty State: Set dirty=true when inputs change to indicate re-execution is needed
Use Run for Background Execution: Use run() for asynchronous execution rather than calling exec() directly
Define Clear Signals: Create algorithm-specific signals for returning results
Clean Up Resources: Ensure resources are released properly, especially if cancellation occurs

Extensions

Algorithm is extended by several specialized classes in the framework:

FlowAlgorithm: Extends Algorithm to process sequences of jobs
ParallelAlgorithm: Provides parallel processing of jobs
ThreadPool: Specializes Algorithm to manage collections of Runnable tasks

Note: When implementing a new algorithm, consider whether one of the existing specialized algorithm classes might provide functionality that matches your requirements.