API Reference

MachineClock

A clock that uses the system time. The time is represented in seconds. Supports pausing and resuming to decouple logical time from system time. The start_time, pause_start_time, and total_paused_time are all represented in seconds and are wall clock (unstretched) time. Whenever now is called, the time is stretched by the stretch_factor. This means that when the stretch_factor is greater than 1, the time will progress faster than the wall clock time.

Fields

• start_time::T: The system time when the clock was created or last reset
• paused::Bool: Whether the clock is currently paused
• total_paused_time::T: Cumulative time spent paused
• pause_start_time::Union{T, Nothing}: System time when current pause started (if any)
• stretch_factor::F: The factor by which to stretch the time

TickedScheduler{C <: Clock, T} <: Scheduler

A scheduler that processes jobs at regular tick intervals.

Fields

• clock::C: The clock providing time information
• jobs::Vector{Job}: The jobs to be scheduled
• ticker::Ticker{T}: The ticker that manages timing

TickedScheduler(clock::Clock, tick_period::T) where {T}

Create a new TickedScheduler with the specified clock and tick period.

Ticker{T}

A mutable struct that handles time accumulation and tick processing.

Fields

• period::T: The fixed tick period
• last_tick_time::T: The time when the last tick was processed
• accumulated_lag::T: Unprocessed time since the last tick

Ticker(period::Quantity{T, 𝐓}) where {T}

Create a new Ticker with the specified tick period.

TimedJob{F, T}

A job that executes at regular time intervals.

Fields

• f::F: The function to execute
• ticker::Ticker{T}: The ticker that manages timing

TimedJob(f, period::Quantity{T, 𝐓}) where {T}

Create a new TimedJob with the specified function and tick period.

VirtualClock

A clock that uses virtual time for simulations. The time is represented in seconds.

Fields

• current_time::T: The current time of the clock

This clock can be advanced with the advance_time! function.

advance_time!(clock::VirtualClock{T}, dt::Quantity{<:Number, 𝐓})

Advance the time of the clock by a given duration. Uses Unitful.jl for time units.

advance_to!(ticker::Ticker, absolute_time::Quantity{<:Number, 𝐓})

Advance the ticker to an absolute time, updating internal state accordingly.

can_tick(ticker::Ticker)

Check if the ticker has accumulated enough time to process a tick.

consume_tick!(ticker::Ticker)

Consume one tick, reducing the accumulated lag by the tick period.

global_clock()

Returns the global clock instance.

Note: This function is type-unstable but the type instability is isolated by function barriers in the calling code.

global_scheduler()

Returns the global scheduler instance.

Note: This function is type-unstable but the type instability is isolated by function barriers in the calling code.

now(clock::Clock)

Returns the current time in the clock using Unitful to represent the unit of time.

pause!(clock::MachineClock)

Pause the clock. While paused, logical time stops progressing.

progress!(job::Job, t::Quantity{<:Number, 𝐓})

Execute the job with the current time. The job decides internally whether to perform work.

progress!(ticker::Ticker, delta_time::Quantity{<:Number, 𝐓})

Progress the ticker by a delta time, updating internal state accordingly.

progress!(job::TimedJob, dt::Quantity{<:Number, 𝐓})

Progress the job by the specified time delta, executing the function for each available tick.

reset!(ticker::Ticker, time::Quantity{<:Number, 𝐓})

Reset the ticker to start at the specified time with no accumulated lag.

reset_global_clock!()

Resets the global clock to the default MachineClock instance.

reset_global_scheduler!()

Resets the global scheduler to the default TickedScheduler instance.

resume!(clock::MachineClock)

Resume the clock. Logical time continues from where it was paused.

schedule!(scheduler::Scheduler, job::Job)

Register a job with the scheduler to run. Can be implemented for concrete types to define scheduling behavior for different schedulers and job types.

schedule!(scheduler::TickedScheduler, job::Job)

Schedule a job to be executed by the scheduler.

set_global_clock!(clock::Clock)

Sets the global clock to the specified instance.

Arguments

• clock::Clock: The clock instance to use globally

set_global_scheduler!(scheduler::Scheduler)

Sets the global scheduler to the specified instance.

Arguments

• scheduler::Scheduler: The scheduler instance to use globally

set_time!(clock::VirtualClock{T}, time::Quantity{<:Number, 𝐓})

Set the time of the clock. Uses Unitful.jl for time units.

update!(scheduler::Scheduler)

Update the scheduler to the current time as provided with the associated clock. This distributes time to the scheduled jobs until virtual time has caught up with the current time provided by the clock (optionally also virtual).

update!(scheduler::TickedScheduler)

Update the scheduler by advancing to the current time and processing available ticks.