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       A scope can be kept local-only by using a scope  name  that  is  unique
58       cluster-wide, e.g. the node name:
59
60         : pg:start_link(node()).
61
62

DATA TYPES

64       group() = any()
65
66              The identifier of a process group.
67

EXPORTS

69       start_link() -> {ok, pid()} | {error, any()}
70
71              Starts  the default pg scope within supervision tree. Kernel may
72              be configured to do it automatically, see  kernel(6)  configura‐
73              tion manual.
74
75       start(Scope :: atom()) -> {ok, pid()} | {error, any()}
76
77       start_link(Scope :: atom()) -> {ok, pid()} | {error, any()}
78
79              Starts additional scope.
80
81       join(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok
82
83       join(Scope :: atom(),
84            Group :: group(),
85            PidOrPids :: pid() | [pid()]) ->
86               ok
87
88              Joins single process or multiple processes to the group Group. A
89              process can join a group many times  and  must  then  leave  the
90              group the same number of times.
91
92              PidOrPids may contain the same process multiple times.
93
94       leave(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok
95
96       leave(Scope :: atom(),
97             Group :: group(),
98             PidOrPids :: pid() | [pid()]) ->
99                ok | not_joined
100
101              Makes  the  process  PidOrPids  leave  the  group  Group. If the
102              process is not a member of the group, not_joined is returned.
103
104              When list of processes is passed as PidOrPids, function  returns
105              not_joined only when all processes of the list are not joined.
106
107       monitor_scope() -> {reference(), #{group() => [pid()]}}
108
109       monitor_scope(Scope :: atom()) ->
110                        {reference(), #{group() => [pid()]}}
111
112              Subscribes  the  caller to updates from the specified scope. Re‐
113              turns content of the entire scope and a reference to  match  the
114              upcoming notifications.
115
116              Whenever any group membership changes, an update message is sent
117              to the subscriber:
118
119              {Ref, join, Group, [JoinPid1, JoinPid2]}
120
121              {Ref, leave, Group, [LeavePid1]}
122
123       monitor(Group :: group()) -> {reference(), [pid()]}
124
125       monitor(Scope :: atom(), Group :: group()) ->
126                  {reference(), [pid()]}
127
128              Subscribes the caller to updates for the  specified  group.  Re‐
129              turns  list of processes currently in the group, and a reference
130              to match the upcoming notifications.
131
132              See monitor_scope/0 for the update message structure.
133
134       demonitor(Ref :: reference()) -> ok | false
135
136       demonitor(Scope :: atom(), Ref :: reference()) -> ok | false
137
138              Unsubscribes the caller from updates (scope or  group).  Flushes
139              all  outstanding  updates that were already in the message queue
140              of the calling process.
141
142       get_local_members(Group :: group()) -> [pid()]
143
144       get_local_members(Scope :: atom(), Group :: group()) -> [pid()]
145
146              Returns all processes running on the local  node  in  the  group
147              Group.  Processes  are returned in no specific order. This func‐
148              tion is optimised for speed.
149
150       get_members(Group :: group()) -> [pid()]
151
152       get_members(Scope :: atom(), Group :: group()) -> [pid()]
153
154              Returns all processes in the group Group. Processes are returned
155              in no specific order. This function is optimised for speed.
156
157       which_groups() -> [Group :: group()]
158
159       which_groups(Scope :: atom()) -> [Group :: group()]
160
161              Returns a list of all known groups.
162

SEE ALSO

164       kernel(6)
165
166
167
168Maxim Fedorov, WhatsApp Inc.    kernel 8.5.4.2                           pg(3)
Impressum