Que v0.4.1 Que.Worker behaviour

Defines a Worker for processing Jobs.

The defined worker is responsible for processing passed jobs, and handling the job’s success and failure callbacks. The defined worker must export a perform/1 callback otherwise compilation will fail.

Basic Worker

defmodule MyApp.Workers.SignupMailer do
  use Que.Worker

  def perform(email) do
    Mailer.send_email(to: email, message: "Thank you for signing up!")
  end
end

You can also pattern match and use guard clauses like normal methods:

defmodule MyApp.Workers.NotificationSender do
  use Que.Worker

  def perform(type: :like, to: user, count: count) do
    User.notify(user, "You have #{count} new likes on your posts")
  end

  def perform(type: :message, to: user, from: sender) do
    User.notify(user, "You received a new message from #{sender.name}")
  end

  def perform(to: user) do
    User.notify(user, "New activity on your profile")
  end
end

Concurrency

By default, workers process one Job at a time. You can specify a custom value by passing the concurrency option.

defmodule MyApp.Workers.PageScraper do
  use Que.Worker, concurrency: 4

  def perform(url), do: Scraper.scrape(url)
end

If you want all Jobs to be processed concurrently without any limit, you can set the concurrency option to :infinity. The concurrency option must either be a positive integer or :infinity, otherwise it will raise an error during compilation.

Handle Job Success & Failure

The worker can also export optional on_success/1 and on_failure/2 callbacks that handle appropriate cases.

defmodule MyApp.Workers.CampaignMailer do
  use Que.Worker

  def perform({campaign, user}) do
    Mailer.send_campaign_email(campaign, user: user)
  end

  def on_success({campaign, user}) do
    CampaignReport.compile(campaign, status: :success, user: user)
  end

  def on_failure({campaign, user}, error) do
    CampaignReport.compile(campaign, status: :failed, user: user)
    Logger.debug("Campaign email to #{user.id} failed: #{inspect(error)}")
  end
end

Failed Job Retries

Failed Jobs are NOT automatically retried. If you want a job to be retried when it fails, you can simply enqueue it again.

To get a list of all failed jobs, you can call Que.Persistence.failed/0.

Summary

Types

t()

A valid worker module

Functions

Checks if the specified module is a valid Que Worker

Raises an error if the passed module is not a valid Que.Worker

Callbacks

Optional callback that is executed if an error is raised during job is processed (in perform callback)

Optional callback that is executed when the job is processed successfully

Main callback that processes the Job

Types

t()
t() :: module

A valid worker module

Functions

valid?(module)
valid?(module :: module) :: boolean

Checks if the specified module is a valid Que Worker

Example

defmodule MyWorker do
  use Que.Worker

  def perform(_args), do: nil
end


Que.Worker.valid?(MyWorker)
# => true

Que.Worker.valid?(SomeOtherModule)
# => false
validate!(module)
validate!(module :: module) :: :ok | no_return

Raises an error if the passed module is not a valid Que.Worker

Callbacks

on_failure(arguments, error)
on_failure(arguments :: term, error :: tuple) :: term

Optional callback that is executed if an error is raised during job is processed (in perform callback)

on_success(arguments)
on_success(arguments :: term) :: term

Optional callback that is executed when the job is processed successfully.

perform(arguments)
perform(arguments :: term) :: term

Main callback that processes the Job.

This is a required callback that must be implemented by the worker. If the worker doesn’t export perform/1 method, compilation will fail. It takes one argument which is whatever that’s passed to Que.add.

You can define it like any other method, use guard clauses and also use pattern matching with multiple method definitions.