Struct Task 

pub struct Task { /* private fields */ }

A Task manages a set of workers and their results.

The Task is the primary orchestrator in consortium. It schedules workers for execution, runs them (respecting fanout limits), and collects their output, return codes, and timeout information.

Design Differences from Python

The Python Task is heavily thread-based with a thread-local singleton pattern (task_self()). The Rust version is single-threaded and owned, using explicit lifetimes rather than thread-local storage. Multi-threaded usage should wrap Task in Arc<Mutex<Task>> if needed.

Implementations

impl Task

pub fn new() -> Self

Create a new Task with default settings.

pub fn from_defaults(defaults: &Defaults) -> Self

Create a new Task from a Defaults configuration.

pub fn with_config(defaults: TaskDefaults, info: TaskInfo) -> Self

Create a new Task with explicit configuration.

pub fn defaults(&self) -> &TaskDefaults

Get task defaults.

pub fn defaults_mut(&mut self) -> &mut TaskDefaults

Get mutable task defaults.

pub fn info(&self) -> &TaskInfo

Get task info.

pub fn info_mut(&mut self) -> &mut TaskInfo

Get mutable task info.

pub fn set_fanout(&mut self, fanout: usize)

Set the fanout (maximum concurrent workers/processes).

pub fn fanout(&self) -> usize

Get the current fanout.

pub fn load_topology(&mut self, path: &str) -> Result<()>

Load a propagation topology from a topology configuration file.

On success, stores the parser (which caches the tree internally).

pub fn default_tree_is_enabled(&mut self) -> bool

Check if tree mode is enabled by default.

pub fn default_router(&mut self) -> Result<&PropagationTreeRouter>

Get or create the default PropagationTreeRouter.

pub fn has_topology(&self) -> bool

Check if a topology is loaded.

pub fn shell( &mut self, command: &str, nodes: Option<&str>, handler: Option<Box<dyn EventHandler>>, ) -> usize

Schedule a local shell command for execution.

If nodes is None, executes locally on a single node. If nodes is Some, executes the command on each node in the set.

Returns the worker ID assigned to this worker.

pub fn shell_with_opts( &mut self, command: &str, nodes: Option<&str>, handler: Option<Box<dyn EventHandler>>, timeout: Option<Duration>, autoclose: bool, ) -> usize

Schedule a shell command with full options.

Returns the worker ID.

pub fn schedule( &mut self, worker: Box<dyn Worker>, handler: Option<Box<dyn EventHandler>>, autoclose: bool, ) -> usize

Schedule a pre-built worker for execution.

The worker will be started when resume() or run() is called. Returns the worker ID.

pub fn run(&mut self, timeout: Option<Duration>) -> Result<()>

Run the task: start all scheduled workers and block until they complete.

Optionally schedule a shell command first (like Python’s task.run(cmd, ...)).

Returns Ok(()) on success, or the first error encountered.

pub fn run_command( &mut self, command: &str, nodes: Option<&str>, handler: Option<Box<dyn EventHandler>>, timeout: Option<Duration>, ) -> Result<usize>

Run with a command: convenience for shell(cmd) + run().

pub fn resume(&mut self) -> Result<()>

Resume task execution — start all pending workers and run until done.

pub fn abort(&mut self, kill: bool)

Abort the task, stopping all running workers.

If kill is true, running worker processes are killed and the task is fully terminated: any further abort()/terminate() call is a no-op (upstream ClusterShell #110 — “only terminate Task once”).

Aborting clears the task’s result stores, mirroring Python Task._terminate() which calls Task._reset().

pub fn abort_handle(&self) -> TaskAbortHandle

Return a thread-safe handle that can abort this task from another thread while resume()/run() is blocked in the run loop.

This is the Rust equivalent of calling task.abort() (or task_cleanup()) from a different thread in Python ClusterShell.

pub fn running(&self) -> bool

Check if the task is currently running.

pub fn state(&self) -> TaskState

Get the current task state.

pub fn max_retcode(&self) -> Option<i32>

Get the maximum return code from the last run, or None if:

• All commands timed out.
• No command-based worker was executed.

pub fn node_retcode(&self, node: &str) -> Option<i32>

Get the return code for a specific node.

When the node is associated with multiple workers, returns the max return code from those workers. Returns None if not found.

pub fn iter_retcodes( &self, match_keys: Option<&HashSet<String>>, ) -> Vec<(i32, Vec<String>)>

Iterate over return codes and their associated node lists.

Returns an iterator of (rc, Vec<node_name>) tuples. If match_keys is Some, only includes matching nodes.

pub fn iter_retcodes_by_worker( &self, worker_id: usize, match_keys: Option<&HashSet<String>>, ) -> Vec<(i32, Vec<String>)>

Iterate over return codes for a specific worker.

pub fn num_timeout(&self) -> usize

Get the number of timed-out nodes.

pub fn iter_keys_timeout(&self) -> impl Iterator<Item = &str>

Iterate over timed-out nodes.

pub fn num_timeout_by_worker(&self, worker_id: usize) -> usize

Get the number of timed-out nodes for a specific worker.

pub fn iter_keys_timeout_by_worker( &self, worker_id: usize, ) -> impl Iterator<Item = &str>

Iterate over timed-out nodes for a specific worker.

pub fn node_buffer(&self, node: &str) -> Result<Vec<u8>>

Get the stdout buffer for a specific node across all workers.

Returns a concatenation of all stdout messages for that node.

pub fn node_error(&self, node: &str) -> Result<Vec<u8>>

Get the stderr buffer for a specific node.

pub fn flush_buffers(&mut self)

Flush all stdout buffers.

pub fn flush_errors(&mut self)

Flush all stderr buffers.

pub fn num_workers(&self) -> usize

Get the number of scheduled workers.

pub fn worker(&self, worker_id: usize) -> Option<&dyn Worker>

Get a reference to a worker by ID.

pub fn worker_retcodes(&self, worker_id: usize) -> Option<&HashMap<String, i32>>

Get the return codes for a specific worker.

Trait Implementations

impl Default for Task

fn default() -> Self

Returns the “default value” for a type.