Citrine v0.1.4 Citrine.Scheduler behaviour View Source

The interface for the core Citrine scheduler. To use the scheduler, define a module that uses Citrine.Scheduler.

Citrine uses Erlang's :mnesia module for state management. Tables are stored in-memory as RAM copies, thus they are not persisted to disk.

Usage

Define a scheduler based on Citrine.Scheduler:

defmodule Blogmail.Scheduler do
  use Citrine.Scheduler, otp_app: :blogmail
  def initialize_jobs() do
    # Initialize your jobs here
    put_job(%Citrine.Job{
      id: "hourly",
      schedule: "0 * * * *",
      task: fn -> nil end
    })
  end
end

Citrine should be added to your application's supervisor tree:

defmodule MyApp.Application do
  use Application
  def start(_type, _args) do
    children = [
      # Start the Citrine scheduler
      MyApp.Scheduler
    ]
    opts = [strategy: :one_for_one, name: MyApp.Supervisor]
    Supervisor.start_link(children, opts)
  end
end

Additionally, it's recommended that you provide an init_task to perform initialization at startup. You should also specify a sufficient init_task_delay to allow everything to settle before running the init task.

For example, you could specify the following in config.exs:

config :myapp, MyApp.Scheduler,
  init_task_delay: 30_000,
  init_task: {MyApp.Scheduler, :initialize_jobs, []}

Example

iex(1)> defmodule MyApp.Scheduler do
...(1)>   use Citrine.Scheduler, otp_app: :myapp
...(1)> end
iex(2)> MyApp.Scheduler.start_link()
iex(3)> MyApp.Scheduler.put_job(
...(3)>   %Citrine.Job{
...(3)>    id: "job",
...(3)>    schedule: "* * * * *",
...(3)>    task: fn -> nil end
...(3)>  })

Link to this section Summary

Types

After the scheduler has started, the init task will be executed after :init_task_delay milliseconds have passed.

Delay in milliseconds before executing the :init_task.

t()

Functions

Returns a specification to start this module under a supervisor.

Callback implementation for Supervisor.init/1.

Callbacks

Returns a count of the number of jobs running on this node in the cluster.

Delete and terminate an existing job matching the specified id.

Retrieve a job by its id.

List all known jobs in the cluster.

Start or update a job. If a job with the same ID already exists, the job will be updated with the new Citrine.Job.

Link to this section Types

Specs

init_task() :: Citrine.Job.task()

After the scheduler has started, the init task will be executed after :init_task_delay milliseconds have passed.

Specs

init_task_delay() :: non_neg_integer()

Delay in milliseconds before executing the :init_task.

Specs

option() ::
  {:init_task, Citrine.Job.task()} | {:init_task_delay, init_task_delay()}

Specs

options() :: [option()]

Specs

t()

Link to this section Functions

Returns a specification to start this module under a supervisor.

See Supervisor.

Callback implementation for Supervisor.init/1.

Link to this section Callbacks

Specs

count_local_jobs() :: non_neg_integer()

Returns a count of the number of jobs running on this node in the cluster.

Specs

delete_job(job_id :: Citrine.Job.jobid()) :: :ok
delete_job(
  job :: %Citrine.Job{
    extended_syntax: term(),
    id: term(),
    schedule: term(),
    task: term()
  }
) :: :ok

Delete and terminate an existing job matching the specified id.

Specs

get_job(job_id :: Citrine.Job.jobid()) ::
  {pid(),
   %Citrine.Job{
     extended_syntax: term(),
     id: term(),
     schedule: term(),
     task: term()
   }}
  | nil
get_job(
  job :: %Citrine.Job{
    extended_syntax: term(),
    id: term(),
    schedule: term(),
    task: term()
  }
) ::
  {pid(),
   %Citrine.Job{
     extended_syntax: term(),
     id: term(),
     schedule: term(),
     task: term()
   }}
  | nil

Retrieve a job by its id.

Specs

list_jobs() :: [
  {pid(),
   %Citrine.Job{
     extended_syntax: term(),
     id: term(),
     schedule: term(),
     task: term()
   }}
]

List all known jobs in the cluster.

Specs

put_job(
  job :: %Citrine.Job{
    extended_syntax: term(),
    id: term(),
    schedule: term(),
    task: term()
  }
) :: DynamicSupervisor.on_start_child()

Start or update a job. If a job with the same ID already exists, the job will be updated with the new Citrine.Job.

Specs

start_link(opts :: options()) :: {:ok, pid()} | {:error, term()}