pg(3erl) - f36

1pg(3)                      Erlang Module Definition                      pg(3)
2
3
4

NAME

6       pg - Distributed named process groups.
7

DESCRIPTION

9       This  module  implements  process groups. A message can be sent to one,
10       some, or all group members.
11
12       Up until OTP 17 there used  to  exist  an  experimental  pg  module  in
13       stdlib.  This  pg module is not the same module as that experimental pg
14       module, and only share the same module name.
15
16       A group of processes can be accessed by a common name. For example,  if
17       there  is  a group named foobar, there can be a set of processes (which
18       can be located on different nodes) that are all members  of  the  group
19       foobar.  There  are  no  special functions for sending a message to the
20       group. Instead, client functions are to be written with  the  functions
21       get_members/1  and get_local_members/1 to determine which processes are
22       members of the group. Then the message can be sent to one or more group
23       members.
24
25       If a member terminates, it is automatically removed from the group.
26
27       A process may join multiple groups. It may join the same group multiple
28       times. It is only allowed to join processes running on local node.
29
30       Process Groups implement strong eventual  consistency.  Process  Groups
31       membership view may temporarily diverge. For example, when processes on
32       node1 and node2 join concurrently, node3 and node4 may receive  updates
33       in a different order.
34
35       Membership  view  is not transitive. If node1 is not directly connected
36       to node2, they will not see each other groups. But  if  both  are  con‐
37       nected to node3, node3 will have the full view.
38
39       Groups  are  automatically  created when any process joins, and are re‐
40       moved when all processes leave the group. Non-existing group is consid‐
41       ered empty (containing no processes).
42
43       Process  groups  can be organised into multiple scopes. Scopes are com‐
44       pletely independent of each other. A process may  join  any  number  of
45       groups  in any number of scopes. Scopes are designed to decouple single
46       mesh into a set of overlay networks, reducing  amount  of  traffic  re‐
47       quired  to  propagate group membership information. Default scope pg is
48       started automatically when kernel(6) is configured to do so.
49
50   Note:
51       Scope name is used to register process locally, and to name an ETS  ta‐
52       ble. If there is another process registered under this name, or another
53       ETS table exists, scope fails to start.
54
55       Local membership is not preserved if scope process exits and restarts.
56
57

DATA TYPES

59       group() = any()
60
61              The identifier of a process group.
62

EXPORTS

64       start_link() -> {ok, pid()} | {error, any()}
65
66              Starts the default pg scope within supervision tree. Kernel  may
67              be  configured  to do it automatically, see kernel(6) configura‐
68              tion manual.
69
70       start(Scope :: atom()) -> {ok, pid()} | {error, any()}
71
72       start_link(Scope :: atom()) -> {ok, pid()} | {error, any()}
73
74              Starts additional scope.
75
76       join(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok
77
78       join(Scope :: atom(),
79            Group :: group(),
80            PidOrPids :: pid() | [pid()]) ->
81               ok
82
83              Joins single process or multiple processes to the group Group. A
84              process  can  join  a  group  many times and must then leave the
85              group the same number of times.
86
87              PidOrPids may contain the same process multiple times.
88
89       leave(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok
90
91       leave(Scope :: atom(),
92             Group :: group(),
93             PidOrPids :: pid() | [pid()]) ->
94                ok | not_joined
95
96              Makes the process  PidOrPids  leave  the  group  Group.  If  the
97              process is not a member of the group, not_joined is returned.
98
99              When  list of processes is passed as PidOrPids, function returns
100              not_joined only when all processes of the list are not joined.
101
102       get_local_members(Group :: group()) -> [pid()]
103
104       get_local_members(Scope :: atom(), Group :: group()) -> [pid()]
105
106              Returns all processes running on the local  node  in  the  group
107              Group.  Processes  are returned in no specific order. This func‐
108              tion is optimised for speed.
109
110       get_members(Group :: group()) -> [pid()]
111
112       get_members(Scope :: atom(), Group :: group()) -> [pid()]
113
114              Returns all processes in the group Group. Processes are returned
115              in no specific order. This function is optimised for speed.
116
117       which_groups() -> [Group :: group()]
118
119       which_groups(Scope :: atom()) -> [Group :: group()]
120
121              Returns a list of all known groups.
122

NAME

DESCRIPTION

DATA TYPES

EXPORTS

SEE ALSO