The hashtag & the slot

Why one slot matters

the scripts

rely on it for cluster legality. A cluster runs a multi-key script only when its keys hash to one slot; declared keys that span slots are refused with CROSSSLOT. A script's declared keys share {q}, and the row @claim2 derives from the declared base KEYS[3] carries the same {q}, so it lands on the same slot. The connector reads {emq}:version once per connect, as a plain GET outside any script, so no script touches the reserve's slot.

the native module

serves standalone servers only. On a standalone server every key is local, so no slot can split a command. The canon records the limit: every native write verb also reads {emq}:version, whose hashtag is emq, not the queue's, so in general it sits on another slot. The module keeps the hashtag discipline anyway: its layout check refuses any call whose keys do not share one non-empty {q}, so its keys are the scripts' keys, byte for byte. A cluster-enabled server refuses every EMQ.* write with EMQWIRE expected a standalone server but cluster mode is enabled.

Without the brace, three keys of one queue could scatter across three slots, and on a cluster no single atomic script could span them.

hashtag/1 — the substring inside the first braces

# echo_mq — EchoMQ.Keyspace
# The hashtag is the substring inside the first {...}. When the braces are
# absent, or empty, the whole key is hashed — the cluster rule. For an
# EchoMQ key the tag is always the queue name (emq:{orders}:* -> "orders").
def hashtag(key) do
  with [_, rest] <- :binary.split(key, "{"),
       [tag, _] when tag != "" <- :binary.split(rest, "}") do
    tag
  else
    _ -> key
  end
end

slot/1 — CRC16-XMODEM, modulo 16384

# echo_mq — EchoMQ.Keyspace
# The cluster slot of a key, computed client-side: the slot a cluster
# server assigns. CRC16-XMODEM over the hashtag (not the whole key),
# modulo 16384 — the cluster specification's algorithm. Known vector:
# slot("123456789") == 12739 (CRC16 0x31C3).
def slot(key) when is_binary(key), do: rem(crc16(hashtag(key), 0), 16384)

# echo_mq — EchoMQ.Keyspace
# CRC16-XMODEM: poly 0x1021, init 0, no reflection. XOR the byte into the
# high half, then eight shift-and-conditional-XOR rounds, masked to 16 bits.
defp crc16(<<>>, crc), do: crc

defp crc16(<<b, rest::binary>>, crc) do
  crc = Bitwise.band(Bitwise.bxor(crc, Bitwise.bsl(b, 8)), 0xFFFF)

  crc =
    Enum.reduce(1..8, crc, fn _, c ->
      shifted = Bitwise.band(Bitwise.bsl(c, 1), 0xFFFF)
      if Bitwise.band(c, 0x8000) != 0, do: Bitwise.bxor(shifted, 0x1021), else: shifted
    end)

  crc16(rest, crc)
end

// trafikey — the native keyspace mirror
// The same rule as hashtag/1: the bytes between the first "{" and the
// next "}", when non-empty; otherwise the whole key.
pub fn hashtag(key: &[u8]) -> &[u8] {
    let mut opened = key.splitn(2, |&b| b == b'{');
    let (Some(_), Some(rest)) = (opened.next(), opened.next()) else {
        return key;
    };
    let mut closed = rest.splitn(2, |&b| b == b'}');
    match (closed.next(), closed.next()) {
        (Some(tag), Some(_)) if !tag.is_empty() => tag,
        _ => key,
    }
}

// CRC16-XMODEM, poly 0x1021, init 0: the same loop on a u16, whose shift
// drops the high bit the Elixir masks away.
pub fn crc16(bytes: &[u8]) -> u16 {
    let mut crc: u16 = 0;
    for &b in bytes {
        crc ^= u16::from(b) << 8;
        for _ in 0..8 {
            crc = if crc & 0x8000 != 0 {
                (crc << 1) ^ 0x1021
            } else {
                crc << 1
            };
        }
    }
    crc
}

// slot/1, ported. The module's test pins the vector:
// assert_eq!(slot(b"123456789"), 12739);
pub fn slot(key: &[u8]) -> u16 {
    crc16(hashtag(key)) % 16384
}

The empty hashtag — the one trap

emq:{}:pending

slot 7387 — the whole key is hashed.

emq:{}:active

slot 5857 — another slot for the same queue.

emq:{orders}:pending

slot 105 — and every other key of orders with it.

Compute a slot — and see both stances

The slot is one CRC16 of the hashtag, knowable before the wire is touched. One queue, one hashtag, one slot: the precondition the scripts carry onto a cluster. The native module serves standalone servers, where every key is local, and still refuses keys that do not share one hashtag.

Pattern → implementation

The pattern says "co-locate by hashtag"; slot/1 is the exact, pinned arithmetic that makes the co-location real and the same for every speaker, in either executor.

Recap — the brace, the CRC16, the slot

Next in this module: The reserve — {emq}:, the core's first-byte-disjoint cross-queue space, where the wire identity lives.

References