Rihanna v2.3.1 Rihanna View Source

The primary client interface for Rihanna.

There are two ways to dispatch jobs with Rihanna:

  1. Using mod-fun-args which is a bit like RPC
  2. Using a module that implements Rihanna.Job and passing in one argument

See the documentation for enqueue/1 and enqueue/2 for more details.

Supervisor

You must have started Rihanna.Supervisor otherwise you will see an error trying to enqueue or retry jobs.

Database Connections

Rihanna requires 1 + N database connections per node, where 1 connection is used for the external API of enqueuing/retrying jobs and N is the number of dispatchers. The default configuration is to run one dispatcher per node, so this will use 2 database connections.

Notes on queueing

Rihanna uses a FIFO job queue, so jobs will be processed roughly in the order that they are enqueued. However, because Rihanna is a concurrent job queue, it may have multiple workers processing jobs at the same time so there is no guarantee of any ordering in practice.

Scheduling

You can schedule jobs for deferred execution using schedule/2 and schedule/3. Jobs scheduled for later execution will run shortly after the due at date, but there is no guarantee on exactly when they will run.

Link to this section Summary

Functions

Deletes a job by ID. ID can be passed as either integer or string.

Deletes all jobs that match either/or module or function.

Enqueues a job specified as a module and one argument.

Retries a job by ID. ID can be passed as either integer or string.

Schedule a job specified as a simple mod-fun-args tuple to run later.

Schedule a job specified as a module and one argument to run later.

Link to this section Types

Link to this type

connection()

View Source
connection() :: {Ecto, repo :: module()}
Link to this type

schedule_option()

View Source
schedule_option() ::
  {:at, DateTime.t()}
  | {:in, pos_integer()}
  | {:due_at, DateTime.t()}
  | {:priority, pos_integer()}
  | {:producer_postgres_connection, {module(), any()}}
Link to this type

schedule_options()

View Source
schedule_options() :: [schedule_option()]

Link to this section Functions

Link to this function

delete(job_id, opts \\ [])

View Source
delete(String.t() | integer(), keyword()) ::
  {:ok, Rihanna.Job.t()} | {:error, :job_not_found}

Deletes a job by ID. ID can be passed as either integer or string.

Link to this function

delete_by(args, opts \\ [])

View Source
delete_by(list(), keyword()) :: {:ok, :deleted} | {:error, :job_not_found}

Deletes all jobs that match either/or module or function.

Example

Deletes all jobs for Module.function

  Rihanna.delete_by(mod: Module, fun: :function)

Deletes all jobs for the module Module

  Rihanna.delete_by(mod: Module)

Deletes all jobs for the function function

  Rihanna.delete_by(fun: :function)
Link to this function

enqueue(term, opts \\ [])

View Source
enqueue({module(), atom(), list()}, keyword()) :: {:ok, Rihanna.Job.t()}
enqueue({module(), any()}, keyword()) :: {:ok, Rihanna.Job.t()}
enqueue(module(), any()) :: {:ok, Rihanna.Job.t()}

Enqueues a job specified as a module and one argument.

It is expected that the module implements the Rihanna.Job behaviour and defines a function Rihanna.Job.perform/1.

The argument may be anything.

See Rihanna.Job for more on how to implement your own jobs.

You can enqueue a job like so:

# Enqueue job for later execution and return immediately
Rihanna.enqueue(MyApp.MyJob, [arg1, arg2])
Link to this function

retry(job_id, opts \\ [])

View Source
retry(String.t(), keyword()) :: {:ok, :retried} | {:error, :job_not_found}
retry(integer(), keyword()) :: {:ok, :retried} | {:error, :job_not_found}

Retries a job by ID. ID can be passed as either integer or string.

Note that this only works if the job has failed - if it has not yet run or is currently in progress, this function will do nothing.

Link to this function

schedule(term, schedule_options)

View Source
schedule({module(), atom(), list()}, schedule_options()) ::
  {:ok, Rihanna.Job.t()}

Schedule a job specified as a simple mod-fun-args tuple to run later.

Example

Schedule at a DateTime:

due_at = ~N[2018-07-01 12:00:00] |> DateTime.from_naive!("Etc/UTC")
Rihanna.schedule({IO, :puts, ["Umbrella-ella-ella"]}, at: due_at)

Schedule in 5 minutes:

Rihanna.schedule({IO, :puts, ["Umbrella-ella-ella"]}, in: :timer.minutes(5))
Link to this function

schedule(mod, arg, schedule_options)

View Source
schedule(module(), any(), schedule_options()) :: {:ok, Rihanna.Job.t()}

Schedule a job specified as a module and one argument to run later.

It is expected that the module implements the Rihanna.Job behaviour and defines a function Rihanna.Job.perform/1.

The argument may be anything.

See Rihanna.Job for more on how to implement your own jobs.

Example

Schedule at a DateTime:

due_at = DateTime.from_naive!(~N[2018-07-01 12:00:00], "Etc/UTC")
Rihanna.schedule(MyApp.MyJob, [arg1, arg2], at: due_at)

Schedule in 5 minutes:

Rihanna.schedule(MyApp.MyJob, [arg1, arg2], in: :timer.minutes(5))