TaskBunny v0.3.4 TaskBunny.Job behaviour View Source

Behaviour module for implementing a TaskBunny job.

TaskBunny job is an asynchronous background job whose execution request is enqueued to RabbitMQ and performed in a worker process.

defmodule HelloJob do
  use TaskBunny.Job

  def perform(%{"name" => name}) do
    IO.puts "Hello " <> name

    :ok
  end
end

HelloJob.enqueue(%{"name" => "Cloud"})

Failing

TaskBunny treats the job as failed when…

the return value of perform is not :ok or {:ok, something}
the perform timed out
the perform raises an exception while being executed
the perform throws :exit signal while being executed.

TaskBunny will retry the failed job later.

Timeout

By default TaskBunny terminates the job when it takes more than 2 minutes. This prevents messages blocking a worker.

If your job is expected to take longer than 2 minutes or you want to terminate the job earlier, override timeout/0.

defmodule SlowJob do
  use TaskBunny.Job

  def timeout, do: 300_000

  def perform(_) do
    slow_work()
    :ok
  end
end

Retry

By default TaskBunny retries 10 times every five minutes for a failed job. You can change this by overriding max_retry/0 and retry_interval/1.

For example, if you want the job to be retried five times and gradually increase the interval based on failed times, you can write logic like the following:

defmodule HttpSyncJob do
  def max_retry, do: 5

  def retry_interval(failed_count) do
    [1, 5, 10, 30, 60]
    |> Enum.map(&(&1 * 60_000))
    |> Enum.at(failed_count - 1, 1000)
  end

  ...
end

Link to this section Summary

Functions

enqueue!(job, payload, options \\ [])

Similar to enqueue/3 but raises an exception on error

enqueue(job, payload, options \\ [])

Enqueues a job with payload

Callbacks

max_retry()

Callback for the max number of retries TaskBunny can make for a failed job

on_reject(any)

Callback executed when a process gets rejected

perform(any)

Callback to process a job

retry_interval(integer)

Callback for the retry interval in milliseconds

timeout()

Callback for the timeout in milliseconds for a job execution

Link to this section Functions

enqueue!(job, payload, options \\ [])

enqueue!(atom(), any(), keyword()) :: :ok

Similar to enqueue/3 but raises an exception on error.

enqueue(job, payload, options \\ [])

enqueue(atom(), any(), keyword()) :: :ok | {:error, any()}

Enqueues a job with payload.

You might want to use the shorter version if you can access to the job.

# Following two calls are exactly same.
RegistrationJob.enqueue(payload)
TaskBunny.enqueue(RegistrationJob, payload)

Options

delay: Set time in milliseconds to schedule the job enqueue time.
host: RabbitMQ host. By default it is automatically selected from configuration.
queue: RabbitMQ queue. By default it is automatically selected from configuration.

Link to this section Callbacks

max_retry()

max_retry() :: integer()

Callback for the max number of retries TaskBunny can make for a failed job.

Default value is 10. Override the function if you want to change the value.

on_reject(any)

on_reject(any()) :: :ok

Callback executed when a process gets rejected.

It receives in input the whole error trace structure plus the orginal payload for inspection and recovery actions.

perform(any)

perform(any()) :: :ok | {:ok, any()} | {:error, term()}

Callback to process a job.

It can take any type of argument as long as it can be serialized with Poison, but we recommend you to use map with string keys for a consistency.

def perform(name) do
  IO.puts name <> ", it's not a preferred way"
end

def perform(%{"name" => name}) do
  IO.puts name <> ", it's a preferred way :)"
end

retry_interval(integer)

retry_interval(integer()) :: integer()

Callback for the retry interval in milliseconds.

Default value is 300_000 = 5 minutes. Override the function if you want to change the value.

TaskBunny will set failed count to the argument. The value will be more than or equal to 1 and less than or equal to max_retry.

timeout()

timeout() :: integer()

Callback for the timeout in milliseconds for a job execution.

Default value is 120_000 = 2 minutes. Override the function if you want to change the value.