pg(3erl) - f34

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. Unlike pg2,  that
31       provides strong ordering guarantees, Process Groups membership view may
32       temporarily diverge. For example, when processes  on  node1  and  node2
33       join  concurrently,  node3 and node4 may receive updates in a different
34       order.
35
36       Membership view is not transitive. If node1 is not  directly  connected
37       to  node2,  they  will  not see each other groups. But if both are con‐
38       nected to node3, node3 will have the full view.
39
40       Groups are automatically created when any process joins,  and  are  re‐
41       moved when all processes leave the group. Non-existing group is consid‐
42       ered empty (containing no processes).
43
44       Process groups can be organised into multiple scopes. Scopes  are  com‐
45       pletely  independent  of  each  other. A process may join any number of
46       groups in any number of scopes. Scopes are designed to decouple  single
47       mesh  into  a  set  of overlay networks, reducing amount of traffic re‐
48       quired to propagate group membership information. Default scope  pg  is
49       started automatically when kernel(6) is configured to do so.
50
51   Note:
52       Scope  name is used to register process locally, and to name an ETS ta‐
53       ble. If there is another process registered under this name, or another
54       ETS table exists, scope fails to start.
55
56       Local  membership is not preserved if scope process exits and restarts.
57       This behaviour is different from pg2, that  recovers  local  membership
58       from remote nodes.
59
60

DATA TYPES

62       group() = any()
63
64              The identifier of a process group.
65

EXPORTS

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

NAME

DESCRIPTION

DATA TYPES

EXPORTS

SEE ALSO