The record hash

One hash, named fields

Three birth fields, one hash: where the job is, the token that fences its holder, and what it carries. The native module adds two more. The names are the contract.

The write — one atomic HSET

# echo_mq — EchoMQ.Jobs: the named handle for admission.
# A job is an entity: its row is a hash at the job key; the pending set is a
# same-score sorted set keyed by the id itself. The host builds both keys and
# hands them in declared; the values (id, payload) ride ARGV.
def enqueue(conn, queue, job_id, payload, opts \\ [])
    when is_binary(job_id) and is_binary(payload) do
  # A queue name may not carry a brace or a NUL: one queue, one {q} hashtag.
  Keyspace.valid_queue!(queue)
  # The dispatch is carried, never inspected: EchoMQ.Connector by default.
  via = Keyword.get(opts, :via, Connector)
  keys = [Keyspace.job_key(queue, job_id), Keyspace.queue_key(queue, "pending")]

  case via.eval(conn, @enqueue, keys, [job_id, payload]) do
    {:ok, 1} -> {:ok, :enqueued}
    {:ok, 0} -> {:ok, :duplicate}
    {:error, {:server, "EMQKIND" <> _}} -> {:error, :kind}
    other -> other
  end
end

-- the @enqueue script: the record write, every key declared in KEYS[]
-- The kind gate: the first three bytes of the id must be JOB (EMQKIND).
-- The full branded-id check already ran host-side, in job_key/2.
if string.sub(ARGV[1], 1, 3) ~= 'JOB' then
  return redis.error_reply('EMQKIND job id must be JOB-namespaced')
end
-- Idempotent: a row that already exists is a no-op (a duplicate enqueue).
if redis.call('EXISTS', KEYS[1]) == 1 then
  return 0
end
-- THE RECORD: one HSET writes the three named fields with their birth values.
--   state    'pending'  the lifecycle position
--   attempts '0'        the fencing token, minted by the first claim
--   payload  ARGV[2]    the caller's opaque cargo, stored verbatim
-- The native command EMQ.ENQUEUE writes this same HSET.
redis.call('HSET', KEYS[1], 'state', 'pending', 'attempts', '0', 'payload', ARGV[2])
-- The pending set: the id is the member, so byte order is mint order.
redis.call('ZADD', KEYS[2], 0, ARGV[1])
return 1

The record is one HSET: three named fields, born with their values, on either executor. The names are protocol; the shape is the contract every speaker reads.

The dives

Next in The Protocol: the chapter map — the native module that runs the core job transitions as EMQ.* commands, and the immutability discipline that holds the field set fixed.

References