Struct RunInstance 

pub struct RunInstance { /* private fields */ }

A run instance represents a specific scheduled occurrence of a task.

Each run is uniquely identified by a RunId and is associated with a TaskId. The lifecycle of a run progresses through canonical states according to the run policy.

Implementations

impl RunInstance

pub fn new_scheduled( task_id: TaskId, scheduled_at: u64, created_at: u64, ) -> Result<Self, RunInstanceConstructionError>

Creates a new run instance in Scheduled state.

pub fn new_scheduled_with_id( id: RunId, task_id: TaskId, scheduled_at: u64, created_at: u64, ) -> Result<Self, RunInstanceConstructionError>

Creates a new run instance in Scheduled state with an explicit identifier.

This constructor is primarily intended for deterministic replay/bootstrap flows that must preserve a durable RunId.

pub fn new_ready( task_id: TaskId, scheduled_at: u64, created_at: u64, effective_priority: i32, ) -> Result<Self, RunInstanceConstructionError>

Creates a new ready run with the specified effective priority.

pub fn new_ready_with_id( id: RunId, task_id: TaskId, scheduled_at: u64, created_at: u64, effective_priority: i32, ) -> Result<Self, RunInstanceConstructionError>

Creates a new ready run with an explicit identifier and effective priority.

pub fn is_terminal(&self) -> bool

Returns true if this run is in a terminal state.

pub fn id(&self) -> RunId

Returns this run’s identifier.

pub fn task_id(&self) -> TaskId

Returns the owning task identifier for this run.

pub fn state(&self) -> RunState

Returns the current lifecycle state for this run.

pub fn current_attempt_id(&self) -> Option<AttemptId>

Returns the currently active attempt identifier, if one exists.

pub fn attempt_count(&self) -> u32

Returns the number of started attempts for this run.

pub fn created_at(&self) -> u64

Returns the run creation timestamp.

pub fn scheduled_at(&self) -> u64

Returns the timestamp at which this run becomes eligible for readiness.

pub fn effective_priority(&self) -> i32

Returns the effective priority snapshot currently associated with this run.

pub fn last_state_change_at(&self) -> u64

Returns the timestamp of the most recent state change.

pub fn record_state_change_at(&mut self, timestamp: u64)

Records the timestamp of a state change (called by the reducer after transitions).

Invariants

In production, the supplied timestamp must be monotonically non-decreasing relative to the current last_state_change_at. The reducer is the sole caller and is expected to feed wall-clock timestamps from durably ordered WAL events. Violation of this invariant will not cause incorrect behavior (the field is simply overwritten), but it indicates a clock or sequencing anomaly that should be investigated.

pub fn transition_to( &mut self, new_state: RunState, ) -> Result<(), RunInstanceError>

Applies a validated lifecycle transition.

Transition legality is enforced via the canonical transition table. Leaving Running while an active attempt is still open is rejected.

pub fn promote_to_ready(&mut self) -> Result<(), RunInstanceError>

Promotes this run into the Ready state with transition validation.

pub fn promote_to_ready_with_priority( &mut self, effective_priority: i32, ) -> Result<(), RunInstanceError>

Promotes this run into the Ready state and snapshots its effective priority.

pub fn set_effective_priority( &mut self, effective_priority: i32, ) -> Result<(), RunInstanceError>

Updates the ready-state effective priority snapshot.

pub fn start_attempt( &mut self, attempt_id: AttemptId, ) -> Result<(), RunInstanceError>

Records the start of a new attempt for a run currently in Running.

pub fn finish_attempt( &mut self, attempt_id: AttemptId, ) -> Result<(), RunInstanceError>

Records completion of the current active attempt.

impl RunInstance

pub fn restore_attempt_state_for_bootstrap( &mut self, count: u32, active_attempt: Option<AttemptId>, )

Restores attempt state during snapshot bootstrap.

During snapshot bootstrap, runs are created via new_scheduled_with_id (which initializes attempt_count=0 and current_attempt_id=None) then replayed through state transitions. However, start_attempt()/finish_attempt() are never called during bootstrap replay. This method directly sets the attempt count and active attempt ID from the snapshot’s attempt history.

This is a bootstrap-only method — normal operation uses start_attempt() and finish_attempt() which enforce state-machine invariants.

Trait Implementations

impl Clone for RunInstance

fn clone(&self) -> RunInstance

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for RunInstance

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

Formats the value using the given formatter.

impl PartialEq for RunInstance

fn eq(&self, other: &RunInstance) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for RunInstance

impl StructuralPartialEq for RunInstance