Kiq v0.2.0 Kiq.Job View Source

Used to construct a Sidekiq compatible job.

The job complies with the Sidekiq Job Format, and contains the following fields:

  • jid - A 12 byte random number as a 24 character hex encoded string
  • pid — Process id of the worker running the job, defaults to the calling process
  • class - The worker class which is responsible for executing the job
  • args - The arguments passed which should be passed to the worker
  • queue - The queue where a job should be enqueued, defaults to “default”
  • at — A time at or after which a scheduled job should be performed, in Unix format
  • created_at - When the job was created, in Unix format
  • enqueue_at - When the job was enqueued, in Unix format

Retry & Failure Fields:

  • retry - Tells the Kiq worker to retry the enqueue job
  • retry_count - The number of times we’ve retried so far
  • failed_at - The first time the job failed, in Unix format
  • retried_at — The last time the job was retried, in Unix format
  • error_message — The message from the last exception
  • error_class — The exception module (or class, in Sidekiq terms)
  • backtrace - The number of lines of error backtrace to store. Only present for compatibility with Sidekiq, this field is ignored.

Unique Fields:

  • unique_for - How long uniqueness will be enforced for a job, in milliseconds
  • unique_until - Allows controlling when a unique lock will be removed, valid options are “start” and “success”.
  • unlocks_at - When the job will be unlocked, in milliseconds
  • unique_token - The uniqueness token calculated from class, queue and args

Link to this section Summary

Functions

Decode an encoded job from JSON into a Job struct

Encode a job as JSON

Build a new Job struct with all dynamic arguments populated

Generate a compliant, entirely random, job id

Convert a job into a map suitable for encoding

Calculate the unique key from a job’s args, class and queue

Link to this section Types

Link to this type t() View Source
t() :: %Kiq.Job{
  args: [any()],
  at: Kiq.Timestamp.t(),
  class: binary(),
  created_at: Kiq.Timestamp.t(),
  enqueued_at: Kiq.Timestamp.t(),
  error_class: binary(),
  error_message: binary(),
  failed_at: Kiq.Timestamp.t(),
  jid: binary(),
  pid: pid(),
  queue: binary(),
  retried_at: Kiq.Timestamp.t(),
  retry: boolean() | non_neg_integer(),
  retry_count: non_neg_integer(),
  unique_for: non_neg_integer(),
  unique_token: binary(),
  unique_until: binary(),
  unlocks_at: Kiq.Timestamp.t()
}

Link to this section Functions

Link to this function decode(input) View Source
decode(input :: binary()) :: t()

Decode an encoded job from JSON into a Job struct.

All keys are atomized, including keys within arguments. This does not use String.to_existing_atom/1, so be wary of encoding large maps.

Example

iex> job = Kiq.Job.decode(~s({"class":"MyWorker","args":[1,2]}))
...> Map.take(job, [:class, :args])
%{class: "MyWorker", args: [1, 2]}

iex> job = Kiq.Job.decode(~s({"class":"MyWorker","args":{"a":1}}))
...> Map.get(job, :args)
%{a: 1}
Link to this function encode(job) View Source
encode(job :: t()) :: binary()

Encode a job as JSON.

During the encoding process any keys with nil values are removed.

Link to this function new(args) View Source
new(args :: map() | Keyword.t()) :: t()

Build a new Job struct with all dynamic arguments populated.

iex> Kiq.Job.new(%{class: "Worker"}) |> Map.take([:class, :args, :queue])
%{class: "Worker", args: [], queue: "default"}

To fit more naturally with Elixir the class argument can be passed as module:

iex> Kiq.Job.new(module: "Worker").class
"Worker"

Only “start” and “success” are allowed as values for unique_until. Any other value will be nullified:

iex> Kiq.Job.new(class: "A", unique_until: "start").unique_until
"start"

iex> Kiq.Job.new(class: "A", unique_until: :start).unique_until
"start"

iex> Kiq.Job.new(class: "A", unique_until: "whenever").unique_until
nil
Link to this function random_jid(size \\ 12) View Source
random_jid(size :: pos_integer()) :: binary()

Generate a compliant, entirely random, job id.

Example

iex> Kiq.Job.random_jid() =~ ~r/^[0-9a-z]{24}$/
true

iex> job_a = Kiq.Job.random_jid()
...> job_b = Kiq.Job.random_jid()
...> job_a == job_b
false
Link to this function to_map(job) View Source
to_map(job :: t()) :: map()

Convert a job into a map suitable for encoding.

For Sidekiq compatibility and encodeability some values are rejected. Specifically, the retry_count value is dropped when it is 0.

Link to this function unique_key(job) View Source
unique_key(job :: t()) :: binary()

Calculate the unique key from a job’s args, class and queue.