Fledex Scheduler

[!IMPORTANT]
This repository is based on SchedEx, but got heavily modified to fit the needs of Fledex. I tried to keep the interface still the same, so you should be able to use it as a drop-in replacement as well.
If you don't see a need for the additional features (like defining jobs) you probably want to use SchedEx instead. This README.md only describes the parts that differ from SchedEx. For the other parts, look at the SchedEx library documentation.
Not everything has been adjusted to the new home and therefore you will still find a lot of references to SchedEx (that might, or might not be accurate).

Fledex_Scheduler is a "simple yet deceptively powerful scheduling library for Elixir. Though it is almost trivially simple by design, it enables a number of very powerful use cases to be accomplished with very little effort".

Fledex_Scheduler is a fork of SchedEx that is written by Mat Trudel, and development is generously supported by the fine folks at FunnelCloud. It has been adapted to easily integrate into Fledex

For usage details, please refer to the documentation and look at the original SchedEx library documentation.

Installation

The library is available in Hex, the package can be installed by adding :fledex_scheduler to your list of dependencies in mix.exs:

def deps do
  [
    {:fledex_scheduler, "~>0.3"}
  ]
end

Basic Usage

Fledex.Scheduler.run_job/2 is the function most commonly used. You first define a Fledex.Scheduler.Job before you schedule the job. Thus, your code will look something like the following:

alias Fledex.Scheduler
alias Fledex.Scheduler.Job

job =
  Job.new()
  |> Job.set_name(:test_job)
  |> Job.set_schedule(crontab)
  |> Job.set_task(fn -> 
    # do something useful
    :ok
  end)
  |> Job.set_repeat(true)
  |> Job.set_run_once(false)
  |> Job.set_timezone("Etc/UTC")
  |> Job.set_overlap(false)
  |> Job.set_nonexistent_time_strategy(:adjust)
  |> Job.set_context(%{strip_name: :test_strip, job: :test_job})

{:ok, pid} = Scheduler.run_job(job)

If more control over the scheduling process is required (for example by integrating it into a supervision tree) it's also possible to use the Runner (Fledex.Scheduler.Runner) directly. The Fledex.Scheduler.run_job/2 maps directly to the Fledex.Scheduler.Runner.run/3 or Fledex.Scheduler.Runner.start_link/3 with additional server options.

Differences vs SchedEx

SchedEx was the base for this library and the core implementation hasn't changed. Here the biggest changes:

A Job definition has been added. This Job is not only used in the run_job but also under the hood in all the other interface functions, i.e. run_every, run_at, and run_in. An attempt was made to keep the same semantics in the interface so it can act as a drop-in replacement for SchedEx. Still, no guarantee can be given that this is true in all cases.
The scheduling has been extended and can now happen in the following forms:
- delay based (in milliseconds)
- delay based with a unit (as a tuple {unit, amount}) (NEW)
- crontab based, either as a Crontab.CronExpression or as a string (that will be parsed)
The dependency on TimeX has been removed and we rely purely on the functions provided by core Elixir.
The Stats have been replaced with :telemetry. Thus, if you want to extract some stats, you should attach to the span events [Fledex.Scheduler.Runner, :run_func]. The corresponding stats functions have been removed.
In addition a clearer definition was introduced between the different type of options (job_opts, test_opts, and server_opts).
100% test, @spec, and @doc coverage has been added.
A lot of automatisms have been added in the CI pipeline.

Copyright and License

This work is free. You can redistribute it and/or modify it under the terms of the MIT License. See the LICENSE.md file for more details.