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.

   Note:
       Scope  name  is  used  to  register process locally, and to name an ETS table. 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.

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) configuration 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 Group. 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 Group. 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 Group. 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 Group. 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)