global_group(3erl)

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

NAME

6       global_group - Grouping nodes to global name registration groups.
7

DESCRIPTION

9       This  module  makes it possible to partition the nodes of a system into
10       global groups. Each global group has  its  own  global  namespace,  see
11       global(3).
12
13       The  main  advantage of dividing systems into global groups is that the
14       background load decreases while the number of nodes to  be  updated  is
15       reduced when manipulating globally registered names.
16
17       The  Kernel  configuration  parameter  global_groups defines the global
18       groups (see also kernel(6) and config(4)):
19
20       {global_groups, [GroupTuple :: group_tuple()]}
21
22       For the processes and nodes to run  smoothly  using  the  global  group
23       functionality, the following criteria must be met:
24
25         * An  instance of the global group server, global_group, must be run‐
26           ning on each node. The processes are automatically started and syn‐
27           chronized when a node is started.
28
29         * All  involved nodes must agree on the global group definition, oth‐
30           erwise the behavior of the system is undefined.
31
32         * All nodes in the system must belong to exactly one global group.
33
34       In the following descriptions, a group node is a node belonging to  the
35       same global group as the local node.
36

DATA TYPES

38       group_tuple() =
39           {GroupName :: group_name(), [node()]} |
40           {GroupName :: group_name(),
41            PublishType :: publish_type(),
42            [node()]}
43
44              A  GroupTuple  without  PublishType  is the same as a GroupTuple
45              with PublishType equal to normal.
46
47       group_name() = atom()
48
49       publish_type() = hidden | normal
50
51              A node started with command-line flag -hidden  (see  erl(1))  is
52              said  to be a hidden node. A hidden node establishes hidden con‐
53              nections to nodes not part of the same global group, but  normal
54              (visible) connections to nodes part of the same global group.
55
56              A  global group defined with PublishType equal to hidden is said
57              to be a hidden global group. All nodes in a hidden global  group
58              are  hidden  nodes,  whether  they are started with command-line
59              flag -hidden or not.
60
61       name() = atom()
62
63              A registered name.
64
65       where() = {node, node()} | {group, group_name()}
66

EXPORTS

68       global_groups() -> {GroupName, GroupNames} | undefined
69
70              Types:
71
72                 GroupName = group_name()
73                 GroupNames = [GroupName]
74
75              Returns a tuple containing the name of the global group that the
76              local  node  belongs  to,  and the list of all other known group
77              names. Returns undefined if no global groups are defined.
78
79       info() -> [info_item()]
80
81              Types:
82
83                 info_item() =
84                     {state, State :: sync_state()} |
85                     {own_group_name, GroupName :: group_name()} |
86                     {own_group_nodes, Nodes :: [node()]} |
87                     {synched_nodes, Nodes :: [node()]} |
88                     {sync_error, Nodes :: [node()]} |
89                     {no_contact, Nodes :: [node()]} |
90                     {other_groups, Groups :: [group_tuple()]} |
91                     {monitoring, Pids :: [pid()]}
92                 sync_state() = no_conf | synced
93
94              Returns a list containing information about the  global  groups.
95              Each  list  element is a tuple. The order of the tuples is unde‐
96              fined.
97
98                {state, State}:
99                  If the local node is part of a global group, State is  equal
100                  to  synced.  If no global groups are defined, State is equal
101                  to no_conf.
102
103                {own_group_name, GroupName}:
104                  The name (atom) of the group that the local node belongs to.
105
106                {own_group_nodes, Nodes}:
107                  A list of node names (atoms), the group nodes.
108
109                {synced_nodes, Nodes}:
110                  A list of node names, the group nodes currently synchronized
111                  with the local node.
112
113                {sync_error, Nodes}:
114                  A  list  of node names, the group nodes with which the local
115                  node has failed to synchronize.
116
117                {no_contact, Nodes}:
118                  A list of node names, the group nodes  to  which  there  are
119                  currently no connections.
120
121                {other_groups, Groups}:
122                  Groups  is  a  list of tuples {GroupName, Nodes}, specifying
123                  the name and nodes of the other global groups.
124
125                {monitoring, Pids}:
126                  A list of pids, specifying  the  processes  that  have  sub‐
127                  scribed to nodeup and nodedown messages.
128
129       monitor_nodes(Flag) -> ok
130
131              Types:
132
133                 Flag = boolean()
134
135              Depending  on Flag, the calling process starts subscribing (Flag
136              equal to true) or stops subscribing (Flag  equal  to  false)  to
137              node status change messages.
138
139              A  process  that  has  subscribed receives the messages {nodeup,
140              Node} and {nodedown, Node} when a group node connects or discon‐
141              nects, respectively.
142
143       own_nodes() -> Nodes
144
145              Types:
146
147                 Nodes = [Node :: node()]
148
149              Returns  the  names of all group nodes, regardless of their cur‐
150              rent status.
151
152       registered_names(Where) -> Names
153
154              Types:
155
156                 Where = where()
157                 Names = [Name :: name()]
158
159              Returns a list of all names that are globally registered on  the
160              specified node or in the specified global group.
161
162       send(Name, Msg) -> pid() | {badarg, {Name, Msg}}
163
164       send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}}
165
166              Types:
167
168                 Where = where()
169                 Name = name()
170                 Msg = term()
171
172              Searches  for Name, globally registered on the specified node or
173              in the specified global group, or (if argument Where is not pro‐
174              vided)  in  any  global group. The global groups are searched in
175              the order that they appear in the value of configuration parame‐
176              ter global_groups.
177
178              If  Name is found, message Msg is sent to the corresponding pid.
179              The pid is also the return value of the function. If the name is
180              not found, the function returns {badarg, {Name, Msg}}.
181
182       sync() -> ok
183
184              Synchronizes  the  group nodes, that is, the global name servers
185              on the group nodes. Also checks the names globally registered in
186              the  current global group and unregisters them on any known node
187              not part of the group.
188
189              If synchronization is not possible, an error report is  sent  to
190              the error logger (see also error_logger(3).
191
192              Returns  {error,  {'invalid  global_groups definition', Bad}} if
193              configuration parameter global_groups has an invalid value Bad.
194
195       whereis_name(Name) -> pid() | undefined
196
197       whereis_name(Where, Name) -> pid() | undefined
198
199              Types:
200
201                 Where = where()
202                 Name = name()
203
204              Searches for Name, globally registered on the specified node  or
205              in the specified global group, or (if argument Where is not pro‐
206              vided) in any global group. The global groups  are  searched  in
207              the order that they appear in the value of configuration parame‐
208              ter global_groups.
209
210              If Name is found, the corresponding pid is returned. If the name
211              is not found, the function returns undefined.
212

NOTES

214         * In  the  situation  where  a node has lost its connections to other
215           nodes in its global group, but has connections to  nodes  in  other
216           global  groups,  a request from another global group can produce an
217           incorrect or misleading result. For example, the isolated node  can
218           have  inaccurate  information  about registered names in its global
219           group.
220
221         * Function send/2,3 is not secure.
222
223         * Distribution of applications is  highly  dependent  of  the  global
224           group  definitions.  It  is  not recommended that an application is
225           distributed over many global groups, as the registered names can be
226           moved  to  another  global group at failover/takeover. Nothing pre‐
227           vents this to be done, but the application code  must  then  handle
228           the situation.
229

NAME

DESCRIPTION

DATA TYPES

EXPORTS

NOTES

SEE ALSO