(acquire! this election-id opts)Try to acquire leadership for an election.
Returns a map with :status in #{:acquired :busy}. On :acquired it also carries:
:token — opaque holder identity required by renew!/resign!/validate!. Random and NOT orderable; never use it as a fence. :fencing — positive integer, monotonically non-decreasing per election-id across successive acquisitions. This is the value a resource write must be guarded by, so a holder that lost the election cannot apply a stale write after a new holder took over.
:fencing is required on every backend, not incidental. A backend that omits it degrades the whole scheme to no fencing at all, silently.
Try to acquire leadership for an election.
Returns a map with :status in #{:acquired :busy}. On :acquired it also
carries:
:token — opaque holder identity required by renew!/resign!/validate!.
Random and NOT orderable; never use it as a fence.
:fencing — positive integer, monotonically non-decreasing per election-id
across successive acquisitions. This is the value a resource
write must be guarded by, so a holder that lost the election
cannot apply a stale write after a new holder took over.
:fencing is required on every backend, not incidental. A backend that omits
it degrades the whole scheme to no fencing at all, silently.(renew! this election-id token opts)Renew leadership using the opaque token returned by acquire!/renew!.
Returns a map with :status in #{:renewed :lost}. On :renewed it echoes the holder's :fencing so a caller can detect an epoch change it did not cause.
Renew leadership using the opaque token returned by acquire!/renew!.
Returns a map with :status in #{:renewed :lost}. On :renewed it echoes the
holder's :fencing so a caller can detect an epoch change it did not cause.(resign! this election-id token opts)Release leadership using the opaque token returned by acquire!/renew!.
Returns a map with :status in #{:released :not-owner}.
:hold-off-ms keeps the election unclaimable for that long after release --
acquire! answers {:status :busy :reason :hold-off} with the remaining
time in :remaining-ttl-ms. Use it when a released election should move to
a different holder rather than bounce straight back to the releaser.
BACKEND SUPPORT: valkey and redis only. It must be atomic with the release
(delete the lease and arm the marker together), which those backends do in
one script. postgres, zookeeper and kubernetes-lease cannot express it and
THROW :d-core.core.leader-election.common/unsupported-option rather than
silently ignoring the option -- a backend that appeared to accept a
hold-off while not enforcing it would restore exactly the thrash it exists
to prevent.
Release leadership using the opaque token returned by acquire!/renew!.
Returns a map with :status in #{:released :not-owner}.
`:hold-off-ms` keeps the election unclaimable for that long after release --
`acquire!` answers `{:status :busy :reason :hold-off}` with the remaining
time in `:remaining-ttl-ms`. Use it when a released election should move to
a *different* holder rather than bounce straight back to the releaser.
BACKEND SUPPORT: valkey and redis only. It must be atomic with the release
(delete the lease and arm the marker together), which those backends do in
one script. postgres, zookeeper and kubernetes-lease cannot express it and
THROW `:d-core.core.leader-election.common/unsupported-option` rather than
silently ignoring the option -- a backend that appeared to accept a
hold-off while not enforcing it would restore exactly the thrash it exists
to prevent.(status this election-id opts)Return the current leadership state for an election.
Returns a map with :status in #{:vacant :held}, plus holder metadata (:owner-id, :fencing, :remaining-ttl-ms). This is the diagnostic read.
It deliberately does NOT reveal the holder's token, so it cannot answer
'is this specific token still the holder?' — that is validate!.
Return the current leadership state for an election.
Returns a map with :status in #{:vacant :held}, plus holder metadata
(:owner-id, :fencing, :remaining-ttl-ms). This is the diagnostic read.
It deliberately does NOT reveal the holder's token, so it cannot answer
'is this specific token still the holder?' — that is `validate!`.(validate! this election-id token opts)Answer whether token is the live holder of election-id.
Returns a map with :status in #{:current :stale :vacant}:
:current — this token is the live holder :stale — a different holder owns the election (the epoch advanced) :vacant — nobody holds it
Read-only and idempotent, and safe to call from a third party that does not own the election — e.g. a proxy deciding whether to accept a consumer, or refusing a second one binding a partition another instance already owns.
Kept separate from status on purpose: status is a diagnostic that returns
holder metadata, validate answers exactly one authorization question and can
be called on a hot path without pulling the whole holder record.
Answer whether `token` is the live holder of `election-id`.
Returns a map with :status in #{:current :stale :vacant}:
:current — this token is the live holder
:stale — a different holder owns the election (the epoch advanced)
:vacant — nobody holds it
Read-only and idempotent, and safe to call from a third party that does not
own the election — e.g. a proxy deciding whether to accept a consumer, or
refusing a second one binding a partition another instance already owns.
Kept separate from `status` on purpose: status is a diagnostic that returns
holder metadata, validate answers exactly one authorization question and can
be called on a hot path without pulling the whole holder record.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |