A cron-style scheduling library for Elixir.

Overview

Timelier is a cron style scheduling application for Elixir. It will match a list of time ‘patterns’ against the current time and start any tasks associated with each matching pattern.

By default, the set of scheduled tasks is sourced from the crontab environment variable within the :timelier application or [] if not present. For example, the following snippet from config.exs defines a task that runs every 15 minutes and dumps a message via :error_logger.info_msg/1.

config :timelier,
       crontab: [{{[0,15,30,45],:any,:any,:any,:any}, {:error_logger,:info_msg,['Hello world.~n']}}]

Starting Timelier

The crontab for Timelier will often contain tasks whose execution is dependent upon particular applications running. To ensure timelier can successfully start tasks defined in your application (or its dependencies), add it as an included application:

def application do
  [included_applications: [:timelier]]
end

and append it’s root supervisor to the list of children that your own top-level supervisor starts, e.g.

def start(_type, _args) do
  import Supervisor.Spec, warn: false

  # Define workers and child supervisors to be supervised
  children = [
    worker(YourApp.YourWorker, []),
    # Other children in your supervision tree...

    supervisor(Timelier.Supervisor, []) # Add timelier's top-level supervisor
  ]

  opts = [strategy: :one_for_one, name: YourApp.Supervisor]
  Supervisor.start_link(children, opts)
end

This should ensure that all appropriate supervision trees should be started before Timelier begins starting tasks.

Crontab format

The format of the crontab is a list of tuple pairs, where the first tuple describes the time pattern and the second specifies the task to be invoked when the pattern matches the current time.

The task is 3-tuple of {mod, func, args}, as would be passed to Kernel.apply/3 and is run by a temporary GenServer under a simple-one-for-one strategy. The return result of applying this triple is ignored, but any crashes will generate a crash report, if sasl is also running.

The time pattern is 5-tuple specifying the minute, hour, day, weekday, and month. Each element may be:

• A single specific value (see the types for the valid ranges).
• Wildcarded with :any, which will always match.
• Described as a list, in which case the elements describe the set of valid values.

In addition, the day and weekday elements support some special ranges:

• The day element may take negative values in the range -31 .. -1, where -1 indicates the last day of the month, -2 the penultimate day of the month and so on.
• The weekday element may take negative values in the range -7 .. -1 where -1 means ‘the last Monday of the month’ and -7 means ‘the last Sunday of the month’.

Example patterns

Time evaluation

Every minute, the application converts the current timestamp (from :erlang.timestamp/0) into an internal datetime representation that may either be in UTC or local time, before matching against the crontab entries.

This representation is controlled by the timezone environment variable, which may either be :utc or :local. The default, if unspecified, is :local.

Alternative Providers

To use an alternative source of scheduled tasks, specify the provider environment variable and ensure that the specified callback returns a tuple of the type {:ok, Timelier.crontab}, e.g.

config :timelier,
       provider: {mod, func, [arg1, arg2 ...]}