classy_membership ¶Cluster Membership CRDT.
This module provides a low-level API for maintaining and updating cluster membership information. Business code should not use it directly.
-type liveness() :: non_neg_integer().
Not exported
-type pv_last() :: #pv_last{op :: op(), toi :: clock()}.
-type pk_last() :: #pk_last{c :: classy:cluster_id(),
l :: classy:site(), k :: key()}.
-type sync_data() :: #cast_sync{}.
-type ord() :: {clock(), magic(), classy:site()}.
Projection of ‘op()‘ fields used to establish total order of logs.
-type op() :: #op_set{origin :: classy:site(),
k :: key(), c :: clock(), m :: magic(), val :: term(),
owt :: integer(), reserved :: term()}.
-type magic() :: term().
Not exported
Arbitrary term used to break ties between commands with the same logical timestamp.
-type update() :: #{mem := false,
origin := classy:site() | undefined} |
#{mem := true, host => node(), meta => map(),
liveness =>
{_NRestarts :: non_neg_integer(),
_SetBySelf :: boolean(),
_IsLive :: boolean()}}.
-type key() :: #mem{} | #host{} | #info{} | #live{}.
Not exported
-type clock() :: non_neg_integer().
-type start_args() :: #{cluster := classy:cluster_id(),
site := classy:site()}.
-spec wipe(classy:cluster_id(), classy:site(),
boolean()) -> ok.
Remove all existing data related to the given cluster.
The process should be running, it is used as a guard against race conditions.
If the third parameter (Stop) is set to true,
then the process immediately terminates after executing the command.
All data related to the cluster is gone.
Otherwise the process keeps running, but it continues from a fresh state.
Logically, it is equivalent to wipe(..., true) followed by ensure_started(...)
(re-initialization is done in-place).
-spec get_data(classy:cluster_id(), classy:site(),
clock(), clock()) -> {ok, sync_data()} | {error, _}.
Get membership data
-spec call_sync(classy:cluster_id(), classy:site(),
sync_data()) -> ok.
-spec cast_sync(classy:cluster_id(), classy:site(),
sync_data()) -> ok.
-spec from_liveness(liveness()) -> {NRestarts,
Self,
IsUp} when NRestarts :: non_neg_integer(),
Self :: boolean(),
IsUp :: boolean().
Convert liveness bitfield to a tuple.
-spec to_liveness(non_neg_integer(), boolean(),
boolean()) -> liveness().
Convert information about liveness to a sortable non-negative integer replicated via CRDT.
Arguments:
true of the update is made by the site itself,
false if the target site is updated by the 3rd party.
true if the site is up.
Bits in the integer are organized such that:
-spec dump() -> #{{classy:cluster_id(), classy:site()}
=> map()}.
Format full state of the membership CRDT in human-readable form for tests and debugging.
-spec flush(classy:cluster_id(), classy:site()) -> ok.
Force sending of events and execution of hooks.
-spec cleanup(classy:cluster_id(), classy:site(),
pos_integer()) -> ok.
Delete sites that have been kicked for longer than
ForgetAfter seconds ago from the local state.
-spec node_of_site(classy:cluster_id(),
classy:site()) -> #{classy:site() => node()}.
Return mapping of sites to nodes.
WARNING: it includes kicked members.
-spec site_of_node(classy:cluster_id(),
classy:site()) -> #{node() => classy:site()}.
Return mapping of nodes to sites.
WARNING: it includes kicked members.
-spec list_local_sites(running |
all) -> [{classy:cluster_id(), classy:site()}].
List local sites and clusters.
-spec members(classy:cluster_id(),
classy:site()) -> [classy:site()].
Return active members of the Cluster,
as perceived by Local site.
WARNING: if Local is not a member of the returned list,
then the local system may be permanently out of sync with the Cluster or {Cluster,Local} server may be inactive.
In both cases the result value can’t be trusted.
-spec set_liveness(classy:cluster_id(), classy:site(),
classy:site(), non_neg_integer(), boolean(),
boolean()) -> ok | {error, _}.
Set site liveness info.
Normally, liveness is only updated by the local site.
The remotes can only update IsUp boolean on behalf of other nodes,
but they must always keep NRestarts as is.
-spec set_info(classy:cluster_id(), classy:site(),
_Info) -> ok | {error, _}.
Set site information.
This function is called by the site itself.
-spec set_member(classy:cluster_id(), classy:site(),
classy:site(), boolean()) -> ok | {error, _}.
Low-level call that sets Target’s membership state to true.
WARNING: this function does not check if target site exists and/or is part of cluster.
When called with invalid Target,
it will create a new entry that will eventually make its way to the entire cluster.
This fictitious site will become a member until kicked,
and even then some records about it may be kept around.
-spec
known_clusters(classy:site()) -> #{classy:cluster_id()
=> [classy:site()]}.
Return collection of clusters where site is or was peer.