Roger.Job behaviour (roger v3.0.0) View Source

Base module for implementing Roger jobs.

To start, use Roger.Job in your module. The only required callback to implement is the perform/1 function.

defmodule TestJob do
  use Roger.Job
  def perform(_args) do
    # perform some work here...
  end
end

Other functions that can be implemented in a job module are the following:

queue_key/1 - Enforces job uniqueness. When returning a string from this function, Roger enforces that only one job per queue key can be put in the queue at the same time. Only when the job has left the queue (after it has been executed), it will be possible to enqueue a job with the same queue key again.

execution_key/1 - Enforces job execution serialization. When returning a string from this function, Roger enforces that not more than one job with the same job is executed concurrently. However, it is still possible to have multiple jobs with the same execution key enqueued, but jobs that have the same execution key will be put in a waiting queue and processed serially.

queue_type/1 - Specifies which partition queue the job will run on. By default, this function returns :default, the default queue type.

retryable?/0 - Specifies whether the job should be retried using an exponential backoff scheme. The default implementation returns false, meaning that jobs will not be retried.

Link to this section Summary

Functions

To implement a job module, use Roger.Job in your module, and implement its required perform/1 function.

Creates a new job based on a job module.

Decode a binary payload into a Job struct, and validates it.

Encodes a job into a binary payload.

Enqueues a job in the given partition.

Executes the given job.

Constructs the AMQP options for publishing the job

Given a job, return its queue type

Given a job, return whether it's retryable or not.

Callbacks

Ability to set max execution time of the job in seconds. The default is :infinity which will allow the job unlimited time to finish. Minimum value is 1 seconds.

Link to this section Types

Specs

t() :: %Roger.Job{
  args: term(),
  execution_key: term(),
  id: term(),
  max_execution_time: term(),
  module: term(),
  queue_key: term(),
  queued_at: term(),
  retry_count: term(),
  started_at: term()
}

Link to this section Functions

To implement a job module, use Roger.Job in your module, and implement its required perform/1 function.

Link to this function

create(module, args \\ [], id \\ generate_job_id())

View Source

Creates a new job based on a job module.

The given module must exist as an Elixir module and must be implementing the Job behaviour (use Roger.Job). Arguments can be passed by the args parameter as a list. Job id is a random hex assigned to the job.

The function returns the Job struct, which can be sent off to the queues using Job.enqueue/2.

Examples

iex> {:ok, job} = Roger.Job.create(Roger.JobTest.SquareJob, [4])
iex> job.__struct__
Roger.Job

Specs

decode(data :: binary()) :: {:ok, t()} | {:error, msg :: String.t()}

Decode a binary payload into a Job struct, and validates it.

Specs

encode(job :: t()) :: binary()

Encodes a job into a binary payload.

Link to this function

enqueue(job, partition_id, override_queue \\ nil)

View Source

Enqueues a job in the given partition.

Executes the given job.

This function is called from within a Job.Worker process, there's no need to call it yourself.

Link to this function

publish_opts(job, partition_id)

View Source

Constructs the AMQP options for publishing the job

Given a job, return its queue type

Given a job, return whether it's retryable or not.

Link to this section Callbacks

Link to this callback

execution_key(any)

View Source (optional)

Specs

execution_key(any()) :: String.t()
Link to this callback

max_execution_time()

View Source (optional)

Specs

max_execution_time() :: integer() | :infinity

Ability to set max execution time of the job in seconds. The default is :infinity which will allow the job unlimited time to finish. Minimum value is 1 seconds.

Specs

perform(any()) :: any()
Link to this callback

queue_key(any)

View Source (optional)

Specs

queue_key(any()) :: String.t()

Specs

queue_type(any()) :: atom()

Specs

retryable?() :: true | false