Struct Scheduler 

pub struct Scheduler { /* private fields */ }

Host-side scheduler skeleton.

One per Uni instance. M11 cutover wires tokio::spawn driving and persistence into uni_system.background_jobs. Currently the scheduler is paused — registered jobs are stored but not executed.

Implementations

impl Scheduler

pub fn new() -> Self

Construct a paused scheduler.

pub fn add_job(&self, id: QName)

Register a new job with the legacy Manual schedule.

Equivalent to add_scheduled_job(id, Schedule::Manual). The job becomes eligible immediately and fires on the next tick (no-op while paused).

pub fn add_scheduled_job(&self, id: QName, schedule: Schedule)

Register a new job with an explicit schedule.

The job’s next_fire_at is computed from the schedule plus the current SystemTime. The scheduler picks it up on the first Self::tick / Self::tick_at whose now is at or past next_fire_at (no-op while paused).

pub fn cancel(&self, id: &QName) -> bool

Cancel a scheduled job by id.

Returns true if the job was found and cancelled.

pub fn list(&self) -> Vec<SchedulerJobRecord>

List all known jobs and their statuses (snapshot).

pub fn cancel_token_for(&self, id: &QName) -> Option<CancellationToken>

Look up the cancellation token associated with a registered job.

Returns None if no job matches id. The returned clone shares state with the record’s token, so callers can both await cancelled().await and observe the same cancel signal trip via Self::cancel.

Used by the host driver to wrap each dispatched spawn_blocking in a tokio::select! against cancelled().await, so shutdown / explicit cancel propagates without waiting for the job body to poll CancellationToken::is_cancelled.

pub fn resume(&self)

Resume the scheduler (M11 cutover wires actual driving here).

pub fn tick(&self) -> Vec<QName>

Drive the scheduler with the current wall-clock time.

Equivalent to tick_at(SystemTime::now()). See Self::tick_at for the full semantics.

pub fn tick_at(&self, now: SystemTime) -> Vec<QName>

Pop every pending job whose schedule has fired at or before now, transition each to Running, and return their ids for the caller to dispatch.

M11 substantive driver primitive. This is the synchronous, runtime-free heart of the scheduler — the eventual Tokio driver wraps a poll loop that calls tick_at(SystemTime::now()), dispatches the returned jobs (e.g., via tokio::spawn invoking each job’s BackgroundJobProvider::execute), and calls Scheduler::mark_finished when each completes.

Schedule semantics (delegated to crate::traits::background::Schedule::next_after):

• A job is “due” iff status == Pending, next_fire_at.is_none() or next_fire_at <= now, and the cancel token is not already triggered.
• Manual jobs have next_fire_at = now at registration and so are immediately due (matching legacy tick() behavior).
• Once(at) jobs become due only when now >= at.
• Periodic(every) jobs become due every after each fire.
• Cron(expr) jobs become due at the next cron instant computed via the cron crate.

Honors pause: returns empty when Self::is_paused. Honors cancellation: skips jobs whose cancel token is already triggered (filtering them out of the return).

pub fn running_count(&self) -> usize

Number of jobs currently in Running state. Useful for observability (e.g., a metrics gauge).

pub fn pending_count(&self) -> usize

Number of pending jobs ready for the next tick.

pub fn requeue_orphaned_runs(&self) -> usize

Reset every Running job back to Pending — used by the driver to recover from a crash where jobs were started but not finished. The host restores the scheduler state from uni_system.background_jobs and calls this to make all previously-Running jobs eligible for re-dispatch.

pub fn pause(&self)

Pause the scheduler.

pub fn is_paused(&self) -> bool

Returns true if currently paused.

pub fn mark_started(&self, id: &QName)

Mark a job as starting a new run.

Used by tests + the M11 cutover driver. Updates the record’s status to Running and stamps last_started_at.

pub fn mark_finished(&self, id: &QName, success: bool)

Mark a job’s run as finished (success or failure).

Recomputes next_fire_at from the job’s Schedule using SystemTime::now() as the reference point. If the schedule has another fire upcoming (Periodic, Cron, or a Once whose instant is still in the future — which shouldn’t normally happen after it has just fired), the job transitions back to Pending so the next Self::tick_at can pick it up. Otherwise the job stays in its terminal state (Idle on success, FailedRetrying on failure).

Trait Implementations

impl Debug for Scheduler

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

Formats the value using the given formatter.

impl Default for Scheduler

fn default() -> Self

Returns the “default value” for a type.

impl SchedulerControl for Scheduler

fn add_scheduled_job(&self, id: QName, schedule: Schedule)

Register a job to fire on schedule.

fn cancel(&self, id: &QName) -> bool

Cancel a job by id. Returns true if it existed.

fn list(&self) -> Vec<SchedulerJobRecord>

Snapshot of every known job.

fn submit_cypher(&self, _cypher: &str) -> Result<(), FnError>

Submit an inline write-mode Cypher body for synchronous execution. The default impl returns an error so simple scheduler primitives (without a host) can still satisfy the trait shape; the uni-db::scheduler::SchedulerHost override dispatches through its crate::traits::background::JobHost.

fn flush_checkpoint(&self) -> Result<(), FnError>

Drive the persistence backend to flush its checkpoint buffer.