Struct ControllerSpec 

pub struct ControllerSpec { /* private fields */ }

Available on crate feature controller only.

A task, admission slot, and busy-slot policy submitted as one request.

The contained TaskSpec defines how the task runs after registry admission. The controller settings define when it may enter the registry:

• an AdmissionPolicy for a busy slot;
• an optional slot that groups work which must not overlap.

Pass the request to SupervisorHandle::submit_and_watch when application logic needs to know whether work was rejected or how an admitted task ended. Use SupervisorHandle::submit when command intake alone is enough. Allocate its task ID before intake with SupervisorHandle::prepare_submission.

Admission flow

application
     │ ControllerSpec
     ▼
SupervisorHandle::submit*
     ▼
controller command queue
     ▼
controller slot
     ├── idle ──► TaskSpec ──► runtime registry ──► managed task
     └── busy ──► apply AdmissionPolicy

Task name and slot

A task name is a unique registry key and diagnostic label. A slot groups work for controller admission. Different task names can share a slot. Without an explicit slot, the task name is used for both roles.

Slots do not create a second task namespace. A task name stays reserved while it belongs to the registry or to Taskvisor’s cleanup of a force-aborted task. The name can be admitted again after that ownership ends.

Examples

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

let task: TaskRef = TaskFn::arc(|_ctx| async {
    Ok(())
});

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

assert_eq!(request.admission(), AdmissionPolicy::Queue);
assert_eq!(request.task_spec().name(), "deploy-main-42");
assert_eq!(request.slot_name(), "deploy-main");

Implementations

impl ControllerSpec

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

Creates a request from an explicit policy and task specification.

The task name is the effective slot until with_slot sets a separate key. Prefer queue, replace, or drop_if_running when the policy is known at the call site.

pub fn admission(&self) -> AdmissionPolicy

Returns the admission policy.

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

Replaces the busy-slot policy without changing the task or slot.

pub fn task_spec(&self) -> &TaskSpec

Returns the contained task specification.

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

Replaces the contained task specification.

An explicit slot stays unchanged. Without one, slot_name uses the name of the new task.

pub fn into_task_spec(self) -> TaskSpec

Removes controller settings and returns the runtime task specification.

The returned value can be passed to a direct add* method when the caller decides to bypass slot admission.

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

Groups this task under an admission key separate from its task name.

Tasks with the same effective slot cannot own that slot together. The task name remains unchanged and is still checked by the runtime registry.

pub fn without_slot(self) -> Self

Clears the slot override and groups this request by task name again.

pub fn slot_name(&self) -> &str

Returns the effective slot: the explicit slot or the task name.

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

Returns the explicit slot override, or None when task name is the slot.

pub fn queue(task_spec: TaskSpec) -> Self

Creates a request that queues behind older work in a busy slot.

Use this when incoming work should join the FIFO order. Queue limits can still reject the submission after command intake. See AdmissionPolicy::Queue for the full contract.

pub fn replace(task_spec: TaskSpec) -> Self

Creates a request that becomes the newest queue head in a busy slot.

Use this when the next item should carry the newest value. This retires the current owner but does not clear older FIFO entries behind the head. See AdmissionPolicy::Replace for the full contract.

pub fn drop_if_running(task_spec: TaskSpec) -> Self

Creates a request that runs only when the slot is idle.

A busy slot rejects the request without starting its task body. Use a watched submit method when the caller must observe that decision. See AdmissionPolicy::DropIfRunning for the full contract.

Trait Implementations

impl Clone for ControllerSpec

fn clone(&self) -> ControllerSpec

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for ControllerSpec

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.