##########
Task model
##########

Overview
--------

CSP.LMC Long Running Commands are represented as a *task tree* composed
of Task and LeafTask nodes.

* A **Task** is a composite node that groups one or more subtasks.
* A **LeafTask** is a terminal node that performs a single operation
  (either a TANGO device command or an internal Component Manager method).

Each node owns a TaskTracker instance used to update progress and final
status.


BaseTask
--------

``BaseTask`` provides the common attributes and behaviour shared by both
Task and LeafTask:

* ``name``: logical task name.
* ``task_type``: execution type (see :doc:`task_execution_type`).
* ``skip_subtasks``: sequential control flag (used to reject subsequent
  subtasks after a failure).
* ``completed_callback``: callback invoked when the task completes.
* ``tracker``: TaskTracker instance associated with this task.

The BaseTask provides two utilities used throughout the framework:

* ``parent_callback()``
  Returns the callback that subtasks should invoke to update the parent
  task state (internally mapped to ``tracker.update_task``).

* ``set_completed_callback()``
  Sets the completion callback used by the TaskTracker.



Task
----

A ``Task`` is a composite node. It contains:

* ``subtasks``: ordered list of nested Tasks and/or LeafTasks.
* ``task_type``: defines whether subtasks are executed sequentially or
  in parallel (execution is performed by the MainTaskExecutor).

Tracker instantiation differs from LeafTask:

* For a Task, the tracker is created with ``total_subtasks=len(subtasks)``,
  enabling progress aggregation across all children.

During composition, tasks with an empty ``subtasks`` list may be removed
by the TaskComposer clean-up stage.



LeafTask
--------

A ``LeafTask`` is a terminal node executing a single action. It contains:

* ``target``: execution target (typically a subsystem component proxy or
  the Component Manager for internal operations).
* ``command_name``: TANGO command name (DEVICE) or CM method name
  (INTERNAL).
* ``argin``: optional input argument for the command/method.

LeafTasks are never root tasks.


Callbacks and propagation model
-------------------------------

Execution updates are propagated via callbacks:

* LeafTasks invoke their parent callback (obtained from the parent task)
  to update parent state.
* The parent TaskTracker aggregates child updates and determines overall
  progress and completion.

The TaskExecutor is responsible for executing tasks and invoking the
appropriate callbacks, while the TaskTracker is responsible for state
aggregation and reporting.