A generally useful event scheduler module.

The ExtensibleScheduler package provides advanced and extensible Julia events schedulers inspired by Python schedulers APScheduler, schedule and sched.

It's also inspired by Sched.jl, a Julia event scheduler inspired by Python sched.

Schedulers can use real time clock (system time) or simulated time (for simulation purpose).

Action(func, args...; kwargs...)

An Action is a structure (a functor in fact) which stores function, arguments and keyword arguments.

An Action can be run (in fact it's run internally by a scheduler when a Job is triggered.)

BlockingScheduler(; clock=real_time_clock, delayfunc=_sleep, jobconfig=JobConfig())

BlockingScheduler is the simplest scheduler. It implements AbstractScheduler.

This is a monothread implementation of scheduling job.

Optional arguments

• clock::AbstractClock: clock that will be used by scheduler (it's by default real_time_clock, which is system UTC time but a SimClock struct can also be passed for simulation purpose).
• delayfunc::DelayFunc: functor which is responsible (when called) of waiting until next task should be fired (_sleep is used by default but a NoSleep struct can also be passed for simulation purpose).
• jobconfig::JobConfig: job configuration default settings (misfire_grace_period...)

SimClock(initial_value)

A simulated clock (for simulation or testing purpose)

iterate(trigger, dt[, n=number_of_times])

Iterate from instant dt using trigger with a given iteration number n if n < 0 (-1 by default), it iterates indefinitely.

Usage

julia> trigger = Trigger(Dates.Time(20, 30))

julia> for dt in iterate(trigger, DateTime(2020, 1, 1), n=3)
         @show dt
       end
dt = 2020-01-01T20:30:00
dt = 2020-01-02T20:30:00
dt = 2020-01-03T20:30:00

julia> collect(iterate(trigger, DateTime(2020, 1, 1), n=3))
3-element Array{Any,1}:
 2020-01-01T20:30:00
 2020-01-02T20:30:00
 2020-01-03T20:30:00

Trigger(dt::DateTime)

Return an InstantTrigger which should trigger job at a given DateTimedt

Trigger(d::Date)

Return an InstantTrigger which should trigger job at a given Dated(at midnight)

Trigger(td::Dates.Period[, n=number_of_times])

Return an PeriodTrigger which should trigger a job after a given period (DatePeriod or TimePeriod).

Trigger(t::Dates.Time[, n=number_of_times])

Return an TimeTrigger which should trigger a job daily at a given time (once, a finite number of times or indefinitely).

Trigger(f::Function[, n=number_of_times])

Return an CustomTrigger which should trigger a job according a function f.

Trigger(tf::TimeFrame[, n=number_of_times])

Return an TimeFrameTrigger which should trigger a job at a given instant according timeframe periodicity. (from TimeFrames.jl)

add(sched, action, trigger; name=DEFAULT_JOB_NAME, priority=DEFAULT_PRIORITY)

Schedule when an Action named action should be triggered (according trigger).

run_pending(sched)

Run pending tasks of a scheduler sched.

This function should be called instead of run when using scheduler in simulation mode.

set(clock::RealTimeClock, value)

Setting clock to a system clock is not an allowed operation

set(clock::SimClock, new_value)

Set time (with new_value of a simulated clock

Default sleep function

Default time function

AbstractClock is an abstract type for clocks

Clocks return instant (DateTime) when asked using now(clock)

Clock can be real (ie using system time) but can also be fake (for simulation purpose).

Time can be set on a simulutated clock using set(clock, new_datetime)

AbstractExecutor is an abstract type for executors

Executors are structs which are responsible of running Action attached to a given Job

AbstractJobStore is an abstract type for jobstores

A jobstore is a data structure which is responsible of storing jobs that should be executed later.

AbstractScheduler is an abstract type for schedulers.

Schedulers are structs which are responsible of running Action at given instants (according a Trigger).

Several kind of schedulers can implement AbstractScheduler.

The most simple scheduler is BlockingScheduler which is monothread.

AbstractTrigger is an abstract type for Triggers

A Trigger define when a job should be run.

AbstractTrigger should implement get_next_dt_fire function which returns instant at which a job should be run (given current instant dt_now and instant when job was previously run (dt_previous_fire)

An exception that a clock can throw.

Generally a clock run an exception when user is trying to set time on a system clock (which is not allowed).

DebugExecutor()

DebugExecutor is a very basic executor that can be used with a BlockingScheduler (with either real clock or simulated clock)

Abstract type for struct (functor) that can block the current task for a specified delay.

FloatTimeFuncStruct()

Functor that return real-time as Float when called

InstantTrigger(dt::DateTime)

A trigger which should trigger job at a given instant (a given DateTime for example)

Job(id, action, trigger, name, priority, dt_created, dt_updated, dt_next_fire, n_triggered, config)

A job is an internal structure which store what action should be executed when triggered.

It also store several properties such as priority level, number of time a job is triggered, when will next trigger should occur...

JobConfig([misfire_grace_period])

Job default configuration

Optional arguments

• misfiregraceperiod (defaults to Dates.Second(1)): grace period for which a task can still be fired.

MemoryJobStore()

MemoryJobStore implements AbstractJobStore.

This is a data structure which is responsible of storing into memory jobs that should be executed later.

NoSleepStruct()

NoSleepStruct implements DelayFunc abstract type.

NoSleep is an instance of NoSleepStruct

When called NoSleep, doesn't do anything.

This is simply a workaround for simulating a scheduler waiting for next job to be processed.

NoTrigger define a trigger that never trigger.

It's a useful struct for triggers operations such as applying offset or jitter to a trigger.

Priority(time_, priority)

Priority of events.

Comparison is first done by time, and after (if same time) using priority value.

As in UNIX, lower priority numbers mean higher priority.

RealTimeClock(functor::TimeFunc)

A real time clock (system time) which use a TimeFunc functor

real_time_clock is default system clock. It's using UTC DateTime

SleepFuncStruct()

A struct that can block (when called) the current task for a specified number of seconds.

SleepFuncStruct implements DelayFunc abstract type.

The minimum sleep time is 1 millisecond or input of 0.001.

SleepFunc is an instance of SleepFuncStruct

SleepFunc(duration)

is same as sleep(duration)

Abstract type for struct that returns real-time or simulated time when called (functor)

TriggerJitter(trigger, offset)

or

TriggerOffset(offset)

A trigger operation that apply jitter to instant when a job should be triggered.

Addition + and substraction - are implemented so it's possible to define a new trigger using

Trigger("H") + TriggerJitter(Date.Minute(3))

to be able to run a job every hour with a random jitter of 3 minutes. This is same as:

TriggerJitter(Trigger("H"), Date.Minute(3))

Randomize next_dt_fire by adding or subtracting a random value (the jitter). If the resulting DateTime is in the past, returns the initial next_dt_fire without jitter.

nextdtfire - jitter <= result <= nextdtfire + jitter

TriggerOffset(trigger, offset)

or

TriggerOffset(offset)

A trigger operation to shift instant when a job should be triggered (adding an offset)

Addition + and substraction - are implemented so it's possible to define a new trigger using

Trigger("H") + TriggerOffset(Date.Minute(3))

to be able to run a job every hour at 3 minutes after round after.

This is same as:

TriggerOffset(Trigger("H"), Date.Minute(3))

UTCDateTimeFuncStruct()

Functor that return real-time as DateTime (UTC) when called

isempty(jobstore)

Returns true when there isn't any job in jobstore.

length(jobstore)

Return the number of jobs stored into jobstore.

A given job can be executed several times (periodical jobs for example).

run(action::Action)

Run action.

This function shouldn't be called directly. It's called by scheduler when a job is triggered.

run(sched)

Run (in a blocking loop) a scheduler named sched.

run(executor::DebugExecutor, job::Job)

Run an Action attached to a given Job

sleep(sched, args...; kwargs...)

Block the scheduler for a specified delay.

job = dequeue!(jobstore)

Remove and return the next job from a jobstore.

job = peek(jobstore)

Return the next job from a jobstore without removing it from this jobstore.

now(clock::RealTimeClock)

Return current instant from a (system) clock

now(clock::RealTimeClock)

Return current instant from a simulated clock (for simulation or testing purpose)

CustomTrigger(f::Function[, n=number_of_times])

A trigger which should trigger a job according a function f.

It's generally a better idea (cleaner implementation) to write your own trigger from AbstractTrigger, AbstractFiniteTrigger or AbstractInfiniteTrigger but passing a function to a CustomTrigger can be quite handy

Job can be triggered:

• once (n=1)
• a finite number of times (n=number_of_times)
• indefinitely (without setting n)

Example

f = (dt_previous_fire, dt_now) -> dt_now + Dates.Minute(5)
trigger = CustomTrigger(f)

should run a job every 5 minutes

Executor(sched)

Return executor of a scheduler named sched.

JobStore(sched)

Return jobstore of a scheduler named sched.

PeriodTrigger(t::Dates.Time[, n=number_of_times])

A trigger which should trigger a job after a given period (DatePeriod or TimePeriod)

Optional parameter

• n=1: trigger once
• n=-1 (default): trigger every day indefinitely
• n=value: trigger just a number of times

TimeFrameTrigger(tf::TimeFrame)

A trigger which should trigger a job at a given instant according timeframe periodicity (from TimeFrames.jl)

Example

TimeFrameTrigger("H")

should run a job every hour

TimeTrigger(t::Dates.Time[, n=number_of_times])

A trigger which should trigger a job daily at a given time.

Optional parameter

• n=1: trigger once
• n=-1 (default): trigger every day indefinitely
• n=value: trigger just a number of times

get_job_id(jobstore)

Returns a job identifier (a job_id).

Parameter jobstore is passed to ensure that no other job stored in jobstore have same job_id.

get_job_id()

Returns a job identifier (a job_id).

It's preferable to use get_job_id(jobstore) to ensure that a job_id is unique for a given JobStore.

get_next_dt_fire(trigger, dt_previous_fire, dt_now)

Return instant at which a job should be run (given current instant dt_now and instant when job was previously run (dt_previous_fire)

get_scheduler_id()

Return a random identifier for a scheduler.

hasjob(jobstore, job_id)

Return true if a job with identifier job_id is stored into jobstore.

hasnextfire(job)

Returns true if a task should be fired in the future.

isrunning(sched)

Return true when a scheduler named sched is running.

isstopped(sched)

Return true when a scheduler named sched is stopped.

schedule(jobstore, job, first_time)

Schedule a job according its Priority.

shutdown(sched)

Shutdown scheduler sched.

update(jobstore, job, now_)

Update jobstore for a given job. Schedule when a job should be fire or delete it from jobstore if it shouldn't be fired again.