TaskBunny v0.2.2 TaskBunny.Job behaviour

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

Summary

Functions

Enqueues a job with payload

Similar to enqueue/3 but raises an exception on error

Callbacks

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

Callback to process a job

Callback for the retry interval in milliseconds

Callback for the timeout in milliseconds for a job execution

Functions

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.
enqueue!(job, payload, options \\ [])
enqueue!(atom, any, keyword) :: :ok

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

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.

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.