View Source Tarearbol.Scheduler (tarearbol v1.12.0)

Cron-like task scheduler. Accepts both static and dynamic configurations.

Usage

Add Tarearbol.Scheduler to the list of supervised workers. It would attempt to read the static configuration (see below) and start the DynamicSupervisor with all the scheduled jobs as supervised workers.

The runner is the function of arity zero, that should return {:ok, result} tuple upon completion. The job will be rescheduled according to its schedule.

The last result returned will be stored in the state and might be retrieved later with get/1 passing the job name.

Static Configuration

Upon starts it looks up :tarearbol section of Mix.Project for :jobs and :jobs_file keys. The latter has a default .tarearbol.exs. This won’t work with releases.

Also it looks up :tarearbol, :jobs section of config.exs. Everything found is unioned. Jobs with the same names are overriden, the file has precedence over project config, the application config has least precedence.

If found, jobs as a list of tuples of {name, runner, schedule} are scheduled. These are expected to be in the following form.

name might be whatever, used to refer to the job during it’s lifetime
runner might be either {module, function} tuple or a reference to the function of arity zero (&Foo.bar/0)
schedule in standard cron notation, see https://crontab.guru

Dynamic Configuration

Use Tarearbol.Scheduler.push/3, Tarearbol.Scheduler.pop/1 to add/remove jobs temporarily and/or Tarearbol.Scheduler.push!/3, Tarearbol.Scheduler.pop!/1 to reflect changes in the configuration file.

Tarearbol.Scheduler.push(TestJob, &Foo.bar/0, "3-5/1 9-18 * * 6-7")

Summary

Types

once_schedule()

Type of possible job schedules to be run once: Time to be executed once or amount of milliseconds to execute after

repeated_schedule()

Type of possible job schedules to be run repeatedly: binary cron format or DateTime for the daily execution

runner()

Type of the job runner, an {m, f} tuple or a function of arity zero, returning one of the outcomes below

schedule()

Combined type for the all schedules possible

Functions

active_jobs()

asynch_call(id, message)

Performs a GenServer.cast/2 to the worker specified by id.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

del(id)

Dynamically removes a supervised worker implementing Tarearbol.DynamicManager behaviour from the list of supervised children

get(id)

Retrieves the information (payload, timeout, lull etc.) assotiated with the supervised worker

multidel(id) deprecated

Dynamically removes a supervised worker implementing Tarearbol.DynamicManager behaviour from the list of supervised children on all the nodes managed by Cloister.

multiput(id, opts) deprecated

Dynamically adds a supervised worker implementing Tarearbol.DynamicManager behaviour to the list of supervised children on all the nodes managed by Cloister.

pop(name)

Removes the scheduled job from the schedule by id.

pop!(name)

Removes the scheduled job from the schedule by id and updated the configuration.

push(name, runner, schedule)

Creates and temporarily pushes the job to the list of currently scheduled jobs.

push!(name, runner, schedule)

Creates and pushes the job to the list of currently scheduled jobs, updates the permanent list of scheduled jobs.

put(id, opts)

Dynamically adds a supervised worker implementing Tarearbol.DynamicManager behaviour to the list of supervised children.

put_new(id, opts)

Dynamically adds a supervised worker implementing Tarearbol.DynamicManager behaviour to the list of supervised children if and only if it does not exist yet.

restart()

Restarts the DynamicManager to the clean state

start_link(opts \\ [])

Starts the DynamicSupervisor and its helpers to manage dynamic children

synch_call(id, message)

Performs a GenServer.call/3 to the worker specified by id.

Types

once_schedule()

@type once_schedule() :: non_neg_integer() | Time.t()

Type of possible job schedules to be run once: Time to be executed once or amount of milliseconds to execute after

repeated_schedule()

@type repeated_schedule() :: binary() | DateTime.t()

Type of possible job schedules to be run repeatedly: binary cron format or DateTime for the daily execution

runner()

@type runner() ::
  {atom(), atom()}
  | {atom(), atom(), list()}
  | (-> :halt | {:ok | {:reschedule, binary()}, any()})

Type of the job runner, an {m, f} tuple or a function of arity zero, returning one of the outcomes below

schedule()

@type schedule() :: once_schedule() | repeated_schedule()

Combined type for the all schedules possible

Functions

active_jobs()

@spec active_jobs() :: %{
  required(Tarearbol.DynamicManager.id()) => Tarearbol.DynamicManager.Child.t()
}

asynch_call(id, message)

(since 1.2.1)

@spec asynch_call(id :: nil | Tarearbol.DynamicManager.id(), message :: any()) ::
  :ok | :error

Performs a GenServer.cast/2 to the worker specified by id.

Tarearbol.DynamicManager.cast/2 callback should be implemented for this to work.

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

del(id)

Dynamically removes a supervised worker implementing Tarearbol.DynamicManager behaviour from the list of supervised children

If distributed: true parameter was given to use Tarearbol.DynamicManager, deletes the worker from all the nodes managed by Cloister. :cloister dependency must be added to a project to use this feature.

get(id)

Retrieves the information (payload, timeout, lull etc.) assotiated with the supervised worker

multidel(id)

This function is deprecated. Use `distributed: true` parameter in call to `use Tarearbol.DynamicManager` and regular `del/1` instead. .

Dynamically removes a supervised worker implementing Tarearbol.DynamicManager behaviour from the list of supervised children on all the nodes managed by Cloister.

Use distributed: true parameter in call to use Tarearbol.DynamicManager and regular del/1 instead.

multiput(id, opts)

This function is deprecated. Use `distributed: true` parameter in call to `use Tarearbol.DynamicManager` and regular `put/2` instead. .

Dynamically adds a supervised worker implementing Tarearbol.DynamicManager behaviour to the list of supervised children on all the nodes managed by Cloister.

Use distributed: true parameter in call to use Tarearbol.DynamicManager and regular put/2 instead.

pop(name)

@spec pop(name :: any()) :: :ok

Removes the scheduled job from the schedule by id.

For the implementation that survives restarts use pop!/1.

pop!(name)

@spec pop!(name :: any()) :: :ok

Removes the scheduled job from the schedule by id and updated the configuration.

For the implementation that removes jobs temporarily, use pop!/1.

push(name, runner, schedule)

@spec push(
  name :: binary(),
  runner :: runner(),
  schedule :: repeated_schedule() | once_schedule()
) :: :ok

Creates and temporarily pushes the job to the list of currently scheduled jobs.

For the implementation that survives restarts use push!/3.

push!(name, runner, schedule)

@spec push!(
  name :: binary(),
  runner :: runner(),
  schedule :: repeated_schedule() | once_schedule()
) :: :ok

Creates and pushes the job to the list of currently scheduled jobs, updates the permanent list of scheduled jobs.

For the implementation that temporarily pushes a job, use push/3.

put(id, opts)

Dynamically adds a supervised worker implementing Tarearbol.DynamicManager behaviour to the list of supervised children.

Unlike put_new/3, this function would have the child replaced (shut down by id and started again with options given.)

If distributed: true parameter was given to use Tarearbol.DynamicManager, puts the worker into all the nodes managed by Cloister. :cloister dependency must be added to a project to use this feature.

put_new(id, opts)

Dynamically adds a supervised worker implementing Tarearbol.DynamicManager behaviour to the list of supervised children if and only if it does not exist yet.

restart()

Restarts the DynamicManager to the clean state

start_link(opts \\ [])

Starts the DynamicSupervisor and its helpers to manage dynamic children

synch_call(id, message)

(since 1.2.0)

@spec synch_call(id :: nil | Tarearbol.DynamicManager.id(), message :: any()) ::
  {:ok, any()} | :error

Performs a GenServer.call/3 to the worker specified by id.

Tarearbol.DynamicManager.call/3 callback should be implemented for this to work.