Module sorceress::scheduler

An ahead-of-time scheduler for executing recurring jobs.

This module provides a scheduler for running jobs that send events to the SuperCollider server at, or ahead of, specific times. A Scheduler creates a Job from a JobDef and invokes Job::run on that job continuously. The interval at which the job is run is determined by the Duration returned by Job::run.

Examples

use sorceress::scheduler::Scheduler;
use std::time::Duration;

let mut beats = (0..4).into_iter();
Scheduler::new().run(|_| {
    move |_| {
        let beat = beats.next()?;
        println!("beat {}", beat);
        Some(Duration::from_millis(500))
    }
})?;

Ephemeral Jobs

If a job does not need to be snapshotted and restored during live-reloading it can () as its Snapshot type. As a convenience, these jobs can be implemented as closure that takes the initial time and returns a Job, as seen in the example above.

Logical Time

The functions JobDef::init and Job::run both take a logical_time argument. The logical time is kept by the scheduler and provides a time that jobs can use as a basis for timestamps on OSC bundles sent to SuperCollider. The logical time is distinctly different from the actual time that jobs can observe using SystemTime::now() in a few ways:

• Logical time only advances when Job::run returns a duration, and the logical time always advances by exactly that duration. The logical time is never affected by fluctuations in system performance.

• The logical_time is usually, and is by default, ahead of the actual time that the job is run. This delay allows time for OSC bundles to be sent to and processed by the SuperCollider server in advance of when the OSC bundles need to be scheduled. This delay can be configured using Scheduler::ahead_by.

• The logical time and actual time will vary slightly on top of the ahead_by delay due to the imprecise nature of the std::thread::sleep function used by the scheduler. This amount is on the order of 10ths of milliseconds on a modern desktop computer. If OSC messages are timestamped and sent to the SuperCollider server before they need to be scheduled this slight variation in time will be of no consequence.

Structs

Error	The error type returned by Scheduler operations.
Handle	A handle to a scheduler.
Scheduler	An ahead-of-time scheduler for executing recurring tasks.

Traits

Job	A recurring job.
JobDef	A Job factory.

Type Definitions

Result

A specialized Result type for scheduler errors.