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. 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 connected to node3, node3 will have the full view.

Groups are automatically created when any process joins, and are removed when all processes leave the group. Non-existing group is considered empty (containing no processes).

Process groups can be organised into multiple scopes. Scopes are completely 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 required to propagate group membership information. Default scope pg is started automatically when kernel(7) is configured to do so.

Local membership is not preserved if scope process exits and restarts.

A scope can be kept local-only by using a scope name that is unique cluster-wide, e.g. the node name:

DATA TYPES

group() = any()

EXPORTS

start_link() -> {ok, pid()} | {error, any()}

start(Scope :: atom()) -> {ok, pid()} | {error, any()}

start_link(Scope :: atom()) -> {ok, pid()} | {error, any()}

join(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok

join(Scope :: atom(),



     Group :: group(),



     PidOrPids :: pid() | [pid()]) ->



        ok

leave(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok

leave(Scope :: atom(),



      Group :: group(),



      PidOrPids :: pid() | [pid()]) ->



         ok | not_joined

monitor_scope() -> {reference(), #{group() => [pid()]}}

monitor_scope(Scope :: atom()) ->



                 {reference(), #{group() => [pid()]}}

{Ref, join, Group, [JoinPid1, JoinPid2]}

{Ref, leave, Group, [LeavePid1]}

monitor(Group :: group()) -> {reference(), [pid()]}

monitor(Scope :: atom(), Group :: group()) ->



           {reference(), [pid()]}

demonitor(Ref :: reference()) -> ok | false

demonitor(Scope :: atom(), Ref :: reference()) -> ok | false

get_local_members(Group :: group()) -> [pid()]

get_local_members(Scope :: atom(), Group :: group()) -> [pid()]

get_members(Group :: group()) -> [pid()]

get_members(Scope :: atom(), Group :: group()) -> [pid()]

which_groups() -> [Group :: group()]

which_groups(Scope :: atom()) -> [Group :: group()]

SEE ALSO

kernel(7)