Fledex.Scheduler.Job (Fledex_Scheduler v0.3.0)

View Source

A job that determines the behaviour of the scheduler. Instead of calling Fledex.Scheduler.run_at/3, Fledex.Scheduler.run_in/3, and Fledex.Scheduler.run_every/3 you can specify your job and use Fledex.Scheduler.run_job/2. the job gives you the most power, since the above mentioned functions all map to a job under the hood.

Summary

Types

schedule()
t()
task()
unit()

Functions

new()

Create an empty job

new(name, func, schedule, context, opts)

Create a new job with all aspects specified

set_context(job, context)

This sets the context.

set_name(job, name)

Set the name of the job.

set_nonexistent_time_strategy(job, strategy)

This sets on how to handle the case that a scheduling time does not exist.

set_overlap(job, overlap)

This sets whether two runs should overlap or not.

set_repeat(job, repeat)

This sets whether the job should repeat (or only run once), You can specify an amount, like 10 and it means that the job will run 10x.

set_run_once(job, run_once)

This sets whether the job should run once during startup, even if it's not time from a scheduling perspective.

set_schedule(job, schedule)

This sets the schedue, i.e. the specification of when the task shoudl be executed. You can specify the job in two different ways

set_task(job, func)

This sets the task that should be executed when it's time to run.

set_timezone(job, timezone)

This sets the timezone

to_job(func, spec, job_opts)

This converts the arguments to a list.

Types

schedule()

@type schedule() :: Crontab.CronExpression.t() | {pos_integer(), unit()}

t()

@type t() :: %Fledex.Scheduler.Job{
  context: map(),
  func: task() | nil,
  name: GenServer.name() | nil,
  opts: keyword(),
  schedule: schedule() | nil
}

task()

@type task() :: (-> any()) | (DateTime.t() -> any())

unit()

@type unit() ::
  :milliseconds
  | :ms
  | :seconds
  | :sec
  | :s
  | :minutes
  | :min
  | :m
  | :hours
  | :h
  | :weeks
  | :w

Functions

new()

@spec new() :: t()

Create an empty job

new(name, func, schedule, context, opts)

@spec new(GenServer.name(), task(), schedule(), map(), keyword()) :: t()

Create a new job with all aspects specified

set_context(job, context)

@spec set_context(t(), map()) :: t()

This sets the context.

The context nothing that the scheduler will use, but it's something that the user can set to the job. It's an arbirary map. During task execution you can access the context and thereby use it in your processing.

set_name(job, name)

@spec set_name(t(), GenServer.name()) :: t()

Set the name of the job.

If nothing is specified, then this will also be the name of the process that will execute the job

set_nonexistent_time_strategy(job, strategy)

@spec set_nonexistent_time_strategy(t(), :skip | :adjust) :: t()

This sets on how to handle the case that a scheduling time does not exist.

During DST changes, it can happen that a time does not exist and there are two ways on how to handle this:

  • :skp: just ignore the missed scheduling and use the next one (this is the default)
  • :adjust: adjust the schedule so that the schedule will happen at the same distance from midnight independently on what the time actually is.

set_overlap(job, overlap)

@spec set_overlap(t(), boolean()) :: t()

This sets whether two runs should overlap or not.

An overlap can happen if, e.g. you schedule a job to run every second, but the execution runs for more than 1sec (let's say 1.2 sec). If you overlap, the next run will happen immediately, whereas if we don't overlap, the next run will only happen at it's next interval, i.e. 0.8sec later.

In general you want to avoid to run any job for that much time

set_repeat(job, repeat)

@spec set_repeat(t(), boolean() | non_neg_integer()) :: t()

This sets whether the job should repeat (or only run once), You can specify an amount, like 10 and it means that the job will run 10x.

set_run_once(job, run_once)

@spec set_run_once(t(), boolean()) :: t()

This sets whether the job should run once during startup, even if it's not time from a scheduling perspective.

This option is very convenient if you want to run something every 15min, but you don't want to wait for that much time for the first initialization. By settin it the task will be run once during startup and will then follow it's schedule.

set_schedule(job, schedule)

@spec set_schedule(t(), schedule()) :: t()

This sets the schedue, i.e. the specification of when the task shoudl be executed. You can specify the job in two different ways

set_task(job, func)

@spec set_task(t(), task()) :: t()

This sets the task that should be executed when it's time to run.

set_timezone(job, timezone)

@spec set_timezone(t(), :utc | String.t()) :: t()

This sets the timezone

You can use any timezone as defined in tzdata. You will have to make sure that you specify the optional :tzdata library and configure it correctly

Note

You can also specify :utc as timezone, because Quantum allowed it. It is preferred that you use Etc/UTC instead. The use of :utc will be removed in a future version

to_job(func, spec, job_opts)

@spec to_job(task(), schedule() | pos_integer(), keyword()) :: t()

This converts the arguments to a list.

Note: the job_opts should contain at least a :name, but any of the other properties the Job can take are accepted too.