partisan_broadcast (partisan v6.0.0)

Public API for Partisan's epidemic-broadcast groups.

A broadcast group is a supervised process that owns a complete, private epidemic-broadcast context — its own mailbox, spanning-tree state and outstanding-lazy table — reading membership from the shared, lock-free partisan_membership snapshot. Group identity is the handler module: each broadcast handler runs in its own group, so independent gossip streams never share a tree or a mailbox.

Groups are declared by the broadcast_mods and broadcast_groups configuration keys and started at boot, and can also be created or retired at runtime.

Entry points

broadcast/2 — disseminate a message to the group that hosts a handler module.
start_group/1, stop_group/1 — create or retire a group at runtime.
groups/0 — list the running groups.

Summary

Functions

broadcast(Broadcast, Mod)

Disseminates Broadcast through the broadcast group that hosts handler Mod.

child_specs()

Returns the child specs for the broadcast groups declared by configuration.

group_name(Mod)

Returns the registered name of the broadcast group that hosts handler Mod.

groups()

Returns the registered names of the currently running broadcast groups.

start_group/1

Starts a broadcast group at runtime.

stop_group/1

Stops and removes the broadcast group for Arg.

Functions

broadcast(Broadcast, Mod)

-spec broadcast(any(), module()) -> ok.

Disseminates Broadcast through the broadcast group that hosts handler Mod.

Mod names the handler module — which is also the group's identity — and the payload sent to peers is derived from Broadcast by that handler's broadcast_data/1 callback. Returns ok once the broadcast has been handed to the group; dissemination itself is asynchronous.

child_specs()

-spec child_specs() -> [supervisor:child_spec()].

Returns the child specs for the broadcast groups declared by configuration.

partisan_broadcast_group_sup uses these to start the configured groups at boot.

group_name(Mod)

-spec group_name(module()) -> atom().

Returns the registered name of the broadcast group that hosts handler Mod.

The name is a deterministic function of Mod and is identical on every node, so a group can be addressed cluster-wide without a registry lookup.

groups()

-spec groups() -> [atom()].

Returns the registered names of the currently running broadcast groups.

start_group/1

-spec start_group(module() | map()) -> {ok, pid()} | {error, term()}.

Starts a broadcast group at runtime.

Arg is either a handler module or a spec map:

#{mods := [module()],
  name => atom(),
  engine => module(),
  lazy_tick_period => integer(),
  exchange_tick_period => integer()}

engine selects the tree engine (defaults to partisan_plumtree_engine; see partisan_broadcast_engine). The call is idempotent: if the group is already running it returns the existing process rather than starting a second one.

stop_group/1

-spec stop_group(module() | map()) -> ok | {error, term()}.

Stops and removes the broadcast group for Arg.

Arg is a handler module or a spec map (only the group name is read). Returns ok whether or not a group was running under that name.