1pg(3) Erlang Module Definition pg(3)
2
6 pg - Distributed named process groups.
7
9 This module implements process groups. A message can be sent to one,
10 some, or all group members.
11 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 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 If a member terminates, it is automatically removed from the group.
26 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 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 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 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 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 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 Local membership is not preserved if scope process exits and restarts.
56 A scope can be kept local-only by using a scope name that is unique
58 cluster-wide, e.g. the node name:
59 : pg:start_link(node()).
61
64 group() = any()
65 The identifier of a process group.
67
69 start_link() -> {ok, pid()} | {error, any()}
70 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 start(Scope :: atom()) -> {ok, pid()} | {error, any()}
76 start_link(Scope :: atom()) -> {ok, pid()} | {error, any()}
78 Starts additional scope.
80 join(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok
82 join(Scope :: atom(),
84 Group :: group(),
85 PidOrPids :: pid() | [pid()]) ->
86 ok
87 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 PidOrPids may contain the same process multiple times.
93 leave(Group :: group(), PidOrPids :: pid() | [pid()]) -> ok
95 leave(Scope :: atom(),
97 Group :: group(),
98 PidOrPids :: pid() | [pid()]) ->
99 ok | not_joined
100 Makes the process PidOrPids leave the group Group. If the
102 process is not a member of the group, not_joined is returned.
103 When list of processes is passed as PidOrPids, function returns
105 not_joined only when all processes of the list are not joined.
106 monitor_scope() -> {reference(), #{group() => [pid()]}}
108 monitor_scope(Scope :: atom()) ->
110 {reference(), #{group() => [pid()]}}
111 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 Whenever any group membership changes, an update message is sent
117 to the subscriber:
118 {Ref, join, Group, [JoinPid1, JoinPid2]}
120 {Ref, leave, Group, [LeavePid1]}
122 monitor(Group :: group()) -> {reference(), [pid()]}
124 monitor(Scope :: atom(), Group :: group()) ->
126 {reference(), [pid()]}
127 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 See monitor_scope/0 for the update message structure.
133 demonitor(Ref :: reference()) -> ok | false
135 demonitor(Scope :: atom(), Ref :: reference()) -> ok | false
137 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 get_local_members(Group :: group()) -> [pid()]
143 get_local_members(Scope :: atom(), Group :: group()) -> [pid()]
145 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 get_members(Group :: group()) -> [pid()]
151 get_members(Scope :: atom(), Group :: group()) -> [pid()]
153 Returns all processes in the group Group. Processes are returned
155 in no specific order. This function is optimised for speed.
156 which_groups() -> [Group :: group()]
158 which_groups(Scope :: atom()) -> [Group :: group()]
160 Returns a list of all known groups.
162
164 kernel(6)
165Maxim Fedorov, WhatsApp Inc. kernel 8.5.4.2 pg(3)