Docs / Configure

Slot reference

A slot is defined as slot_NNN with a kind and that kind's options. This page describes what reads and writes do for each kind.

slot_002:            # slot number 002
  kind: token_bucket # one of the kinds below
  bucket_size: 100   # options of that kind
  period: second
KindReadWrites / d
simple_memoryValueStores value010
timeout_memoryValueStores value if owner or no owner, else 007010
token_bucketTakes tokens, returns how many006010
leaky_bucket1 accepted / 0 rejected006010
tickerCurrent countdownRestarts the countdown010
atomicIncrements, returns new valueSets the counter010
broadcastLast value writtenSends event to every client010
multicastLast value writtenSends event to subscribersJoin / leave

Every kind also accepts a users map with per-user permissions. See Authentication.

Invalid definitions are ignored silently

An unknown kind, a missing required option or an out-of-range value makes the server skip that slot without any warning. The slot then answers e<slot>005 (MISSING_SLOT). Read each slot once after a configuration change to make sure it exists.

Simple memory#

kind: simple_memory. The most basic slot: a value of up to 36 bytes that anyone with permission can read and write. It has no options.

slot_000:
  kind: simple_memory

Timeout memory#

kind: timeout_memory. A memory slot with an owner. Only the connection that last wrote the slot can write it again, until it goes timeout seconds without writing. Use it as a lease to pick a single active worker or leader.

OptionRequiredDescription
timeoutYesOwnership timeout in seconds. Must be at least 1.
slot_001:
  kind: timeout_memory
  timeout: 10

Captured with two nc sessions, A and B, against timeout: 10:

# A takes the lease
> w001node-a
< v001node-a
# B tries and is refused, but can read the owner
> w001node-b
< e001007
> r001
< v001node-a
# A closes its connection; B is still refused
> w001node-b
< e001007
# 10 seconds later
> w001node-b
< v001node-b

Ownership caveats#

Token bucket#

kind: token_bucket. A classic token bucket for rate limiting. A fleet of API servers can share one bucket to enforce a single limit on calls to an upstream.

OptionRequiredDescription
bucket_sizeYesMaximum number of tokens the bucket holds. At least 1.
periodYesRefill period: second, minute or hour.
refresh_rateNo, default 1Tokens added every period. Between 1 and bucket_size.
tokens_per_reqNo, default 1Most tokens handed out by one read. Between 1 and bucket_size. A client can take several tokens per call and use them locally, which cuts the number of requests.
slot_002:
  kind: token_bucket
  bucket_size: 200   # allow bursts of up to 2x
  period: second
  refresh_rate: 100  # 100 tokens per second

Leaky bucket#

kind: leaky_bucket. A bucket that leaks one token every refresh_rate milliseconds. Each read tries to add a token: if there is room, the request is accepted. Once the bucket is full, requests are rejected until a token leaks out. The bucket size allows bursts, after which requests are accepted at the constant leak rate. Set bucket_size: 1 to allow no burst.

OptionRequiredDescription
bucket_sizeYesCapacity of the bucket. At least 1.
refresh_rateNo, default 1000Milliseconds between leaked tokens. At least 1.
slot_003:
  kind: leaky_bucket
  bucket_size: 100
  refresh_rate: 1000

Ticker#

kind: ticker. A watchdog countdown, as in embedded circuits and microcontrollers. The slot holds a non-negative integer that goes down by one every refresh_rate milliseconds until it reaches zero. Writing a value restarts the countdown from that value.

OptionRequiredDescription
initial_valueYesStarting value. Must not be negative.
refresh_rateYesMilliseconds per tick. At least 1.

Both options are required. A ticker without either one is ignored and answers 005, like any invalid slot.

slot_004:
  kind: ticker
  initial_value: 600
  refresh_rate: 1000

Atomic counter#

kind: atomic. An integer counter that only goes up. Use it to hand out distinct numbers to concurrent workers. It has no options.

slot_005:
  kind: atomic
> r005
< v0051
> r005
< v0052
> w00541
< v00541
> r005
< v00542
> w005-1
< e005007

Broadcast#

kind: broadcast. A write is sent as an async event to every connected client, including the one that wrote it. No subscription is needed. Use it to push a signal, such as an ID or a "reload configuration" notice, to every instance. It has no options apart from users.

slot_006:
  kind: broadcast

The event is a, the slot number and the value. The writer gets its own event too, before the confirmation:

> w006deploy-42
< a006deploy-42
< v0062/2/0

The confirmation is received/sent/errors:

Ghoti only answers the write once every delivery is confirmed or the 200 ms wait is over, so many clients, or slow ones, delay the confirmation.

Multicast#

kind: multicast. Like broadcast, but the event only goes to the clients that joined the slot's group with s. A client leaves the group with d.

OptionRequiredDescription
timeoutNo, default 200Milliseconds to wait for subscribers to confirm an event. At least 1. Note that this is milliseconds, unlike timeout_memory's seconds.
dereg_triesNo, default 3Consecutive failed deliveries after which a subscriber is removed from the group. At least 1.
slot_007:
  kind: multicast
  timeout: 200
  dereg_tries: 3

Captured with a subscriber X and a writer B:

# X joins
> s007
< v0071
# B writes; only X receives the event
> w007cache-flush
< v0071/1/0
# B joins too, then writes again
> s007
< v0071
> w007hi
< a007hi
< v0072/2/0

Planned: random signal propagation#

Planned A slot kind that delivers each write to one subscriber chosen at random, instead of to all of them. It is not implemented, and a slot configured with an unknown kind is ignored.

Found something out of date? Open an issue or edit this page.