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. Add watch() before the terminal operation to observe rejection or the final task outcome. Use the default unwatched operation 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. 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 the registry owns it. Cleanup of a force-aborted task can also retain the name. 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

Controller 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

Busy-slot admission policy.

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

Busy-slot policy replacement that preserves the task and slot.

pub fn task_spec(&self) -> &TaskSpec

Borrowed runtime task specification.

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

Runtime task-spec replacement that preserves any explicit slot.

Without one, slot_name uses the name of the new task.

pub fn into_task_spec(self) -> TaskSpec

Runtime task specification without controller settings.

Pass this value to SupervisorHandle::add to bypass slot admission.

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

Explicit admission key separate from the 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

Task-name admission with no explicit slot override.

pub fn slot_name(&self) -> &str

Effective admission key from the explicit slot or task name.

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

Explicit slot override when configured.

pub fn queue(task_spec: TaskSpec) -> Self

FIFO admission 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

Newest-head admission 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

Idle-only admission for incoming work.

A busy slot rejects the request without starting its task body. Add watch() to the submission operation when the caller must observe that decision. See AdmissionPolicy::DropIfRunning for the full contract.

Trait Implementations

impl Clone for ControllerSpec

fn clone(&self) -> Self

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.