pg(3erl) Erlang Module Definition pg(3erl)
NAME
pg - Distributed named process groups.
DESCRIPTION
This module implements process groups. A message can be sent to one,
some, or all group members.
Up until OTP 17 there used to exist an experimental pg module in
stdlib. This pg module is not the same module as that experimental pg
module, and only share the same module name.
A group of processes can be accessed by a common name. For example, if
there is a group named foobar, there can be a set of processes (which
can be located on different nodes) that are all members of the group
foobar. There are no special functions for sending a message to the
group. Instead, client functions are to be written with the functions
get_members/1 and get_local_members/1 to determine which processes are
members of the group. Then the message can be sent to one or more group
members.
If a member terminates, it is automatically removed from the group.
A process may join multiple groups. It may join the same group multiple
times. It is only allowed to join processes running on local node.
Process Groups implement strong eventual consistency. Unlike pg2, that
provides strong ordering guarantees, Process Groups membership view may
temporarily diverge. For example, when processes on node1 and node2
join concurrently, node3 and node4 may receive updates in a different
order.
Membership view is not transitive. If node1 is not directly connected
to node2, they will not see each other groups. But if both are con-
nected to node3, node3 will have the full view.
Groups are automatically created when any process joins, and are re-
moved when all processes leave the group. Non-existing group is consid-
ered empty (containing no processes).
Process groups can be organised into multiple scopes. Scopes are com-
pletely independent of each other. A process may join any number of
groups in any number of scopes. Scopes are designed to decouple single
mesh into a set of overlay networks, reducing amount of traffic re-
quired to propagate group membership information. Default scope pg is
started automatically when kernel(7) is configured to do so.
Note:
Scope name is used to register process locally, and to name an ETS ta-
ble. If there is another process registered under this name, or another
ETS table exists, scope fails to start.
Local membership is not preserved if scope process exits and restarts.
This behaviour is different from pg2, that recovers local membership
from remote nodes.
DATA TYPES
group() = any()
The identifier of a process group.
EXPORTS
start_link() -> {ok, pid()} | {error, any()}
Starts the default pg scope within supervision tree. Kernel may
be configured to do it automatically, see kernel(7) configura-
tion manual.
start(Scope :: atom()) -> {ok, pid()} | {error, any()}
start_link(Scope :: atom()) -> {ok, pid()} | {error, any()}
Starts additional scope.
join(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok
join(Scope :: atom(),
Group :: group(),
PidOrPids :: pid() | [pid()]) ->
ok
Joins single process or multiple processes to the group Name. A
process can join a group many times and must then leave the
group the same number of times.
PidOrPids may contain the same process multiple times.
leave(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok
leave(Scope :: atom(),
Group :: group(),
PidOrPids :: pid() | [pid()]) ->
ok | not_joined
Makes the process PidOrPids leave the group Name. If the process
is not a member of the group, not_joined is returned.
When list of processes is passed as PidOrPids, function returns
not_joined only when all processes of the list are not joined.
get_local_members(Group :: group()) -> [pid()]
get_local_members(Scope :: atom(), Group :: group()) -> [pid()]
Returns all processes running on the local node in the group
Name. Processes are returned in no specific order. This function
is optimised for speed.
get_members(Group :: group()) -> [pid()]
get_members(Scope :: atom(), Group :: group()) -> [pid()]
Returns all processes in the group Name. Processes are returned
in no specific order. This function is optimised for speed.
which_groups() -> [Group :: group()]
which_groups(Scope :: atom()) -> [Group :: group()]
Returns a list of all known groups.
SEE ALSO
kernel(7)
Maxim Fedorov, WhatsApp Inc. kernel 7.0 pg(3erl)