Struct ControllerSpec

Source

pub struct ControllerSpec { /* private fields */ }

Available on crate feature controller only.

Expand description

Describes one task submission through the controller.

A ControllerSpec does not run a task by itself. It stores the task, the busy-slot policy, and the target slot.

The slot is admission metadata. It is not part of the task execution model. The task still runs according to its TaskSpec.

§Example

use taskvisor::{ControllerSpec, TaskFn, TaskRef, TaskSpec};

let task: TaskRef = TaskFn::arc("deploy-main-42", |_ctx| async {
    Ok(())
});

let spec = ControllerSpec::queue(TaskSpec::once(task)).with_slot("deploy-main");

assert_eq!(spec.slot_name(), "deploy-main");

§See also

AdmissionPolicy - how concurrent submissions to the same slot are handled
TaskSpec - task restart, backoff, timeout, and retry settings
SupervisorHandle::prepare_submission - reserve the submission identity before events can start
SupervisorHandle::submit - submit without waiting for the final outcome
SupervisorHandle::submit_and_watch - submit and get a TaskWaiter for the final TaskOutcome

Implementations§

Source §

impl ControllerSpec

Source

pub fn new(admission: AdmissionPolicy, task_spec: TaskSpec) -> Self

Creates a submission spec from an admission policy and a task spec.

The slot defaults to the task name. Use with_slot to group several task names under one slot.

Source

pub fn admission(&self) -> AdmissionPolicy

Returns the admission policy used when the target slot is busy.

Source

pub fn with_admission(self, admission: AdmissionPolicy) -> Self

Sets the admission policy used when the target slot is busy.

Source

pub fn task_spec(&self) -> &TaskSpec

Returns the task execution specification.

Source

pub fn with_task_spec(self, task_spec: TaskSpec) -> Self

Replaces the task execution specification.

When no explicit slot is configured, the effective slot changes to the name of the replacement task. An explicit slot is preserved.

Source

pub fn into_task_spec(self) -> TaskSpec

Consumes this submission spec and returns its task execution specification.

Controller-only metadata such as the admission policy and slot override is discarded.

Source

pub fn with_slot(self, slot: impl Into<Arc<str>>) -> Self

Sets the admission slot key.

The slot is the controller’s admission unit: only one registered task can own a slot at a time.

Use the same slot for work that must not run in parallel. Use different slots for work that may run independently.

Source

pub fn without_slot(self) -> Self

Removes an explicit slot override.

After this call, slot_name falls back to the current task name.

Source

pub fn slot_name(&self) -> &str

Returns the effective slot key.

If with_slot was not used, this returns the task name from TaskSpec::name.

Source

pub fn slot_override(&self) -> Option<&str>

Returns the explicit slot override, if one was configured.

Unlike slot_name, this does not fall back to the task name.

Source

pub fn queue(task_spec: TaskSpec) -> Self

Creates a submission with FIFO queue admission.

If the slot is idle, the controller tries to start registry admission. If the slot is busy, the submission is appended behind older pending work when ControllerConfig::max_slot_queue allows it; otherwise it is rejected.

Source

pub fn replace(task_spec: TaskSpec) -> Self

Creates a replacement submission.

If the slot is idle, the controller tries to start registry admission. If the slot is busy, this submission becomes the queue head. The controller retires a registered owner, or waits for a pending registration decision before deciding whether removal is needed.

An existing head is rejected and replaced, even when it came from Queue. Existing FIFO items behind the head remain queued. Repeated replacements therefore keep only the latest head without growing the queue.

Source