1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
26
<title>global_group</title>
27
<prepared>Esko Vierumäki</prepared>
29
<date>1998-12-18</date>
32
<module>global_group</module>
33
<modulesummary>Grouping Nodes to Global Name Registration Groups</modulesummary>
35
<p>The global group function makes it possible to group the nodes
36
in a system into partitions, each partition having its own global
37
name space, refer to <c>global(3)</c>. These partitions are
38
called global groups.</p>
39
<p>The main advantage of dividing systems to global groups is that
40
the background load decreases while the number of nodes to be
41
updated is reduced when manipulating globally registered names.</p>
42
<p>The Kernel configuration parameter <c>global_groups</c> defines
43
the global groups (see also
44
<seealso marker="kernel_app">kernel(6)</seealso>,
45
<seealso marker="config">config(4)</seealso>:</p>
47
{global_groups, [GroupTuple]}</code>
49
<list type="bulleted">
50
<item><c>GroupTuple = {GroupName, [Node]} | {GroupName, PublishType, [Node]}</c></item>
51
<item><c>GroupName = atom()</c> (naming a global group)</item>
52
<item><c>PublishType = normal | hidden</c></item>
53
<item><c>Node = atom()</c> (naming a node)</item>
55
<p>A <c>GroupTuple</c> without <c>PublishType</c> is the same as a
56
<c>GroupTuple</c> with <c>PublishType == normal</c>.</p>
57
<p>A node started with the command line flag <c>-hidden</c>, see
58
<seealso marker="erts:erl">erl(1)</seealso>, is said to be a
59
<em>hidden</em> node. A hidden node will establish hidden
60
connections to nodes not part of the same global group, but
61
normal (visible) connections to nodes part of the same global
63
<p>A global group defined with <c>PublishType == hidden</c>, is
64
said to be a hidden global group. All nodes in a hidden global
65
group are hidden nodes, regardless if they are started with
66
the <c>-hidden</c> command line flag or not.</p>
67
<p>For the processes and nodes to run smoothly using the global
68
group functiontionality, the following criteria must be met:</p>
69
<list type="bulleted">
71
<p>An instance of the global group server, <c>global_group</c>,
72
must be running on each node. The processes are automatically
73
started and synchronized when a node is started.</p>
76
<p>All involved nodes must agree on the global group definition,
77
or the behavior of the system is undefined.</p>
80
<p><em>All</em> nodes in the system should belong to exactly
84
<p>In the following description, a <em>group node</em> is a node
85
belonging to the same global group as the local node.</p>
89
<name>global_groups() -> {GroupName, GroupNames} | undefined</name>
90
<fsummary>Return the global group names</fsummary>
92
<v>GroupName = atom()</v>
93
<v>GroupNames = [GroupName]</v>
96
<p>Returns a tuple containing the name of the global group
97
the local node belongs to, and the list of all other known
98
group names. Returns <c>undefined</c> if no global groups are
103
<name>info() -> [{Item, Info}]</name>
104
<fsummary>Information about global groups</fsummary>
106
<v>Item, Info -- see below</v>
109
<p>Returns a list containing information about the global
110
groups. Each element of the list is a tuple. The order of
111
the tuples is not defined.</p>
113
<tag><c>{state, State}</c></tag>
115
<p>If the local node is part of a global group,
116
<c>State == synced</c>. If no global groups are defined,
117
<c>State == no_conf</c>.</p>
119
<tag><c>{own_group_name, GroupName}</c></tag>
121
<p>The name (atom) of the group that the local node belongs
124
<tag><c>{own_group_nodes, Nodes}</c></tag>
126
<p>A list of node names (atoms), the group nodes.</p>
128
<tag><c>{synced_nodes, Nodes}</c></tag>
130
<p>A list of node names, the group nodes currently
131
synchronized with the local node.</p>
133
<tag><c>{sync_error, Nodes}</c></tag>
135
<p>A list of node names, the group nodes with which
136
the local node has failed to synchronize.</p>
138
<tag><c>{no_contact, Nodes}</c></tag>
140
<p>A list of node names, the group nodes to which there are
141
currently no connections.</p>
143
<tag><c>{other_groups, Groups}</c></tag>
145
<p><c>Groups</c> is a list of tuples
146
<c>{GroupName, Nodes}</c>, specifying the name and nodes
147
of the other global groups.</p>
149
<tag><c>{monitoring, Pids}</c></tag>
151
<p>A list of pids, specifying the processes which have
152
subscribed to <c>nodeup</c> and <c>nodedown</c> messages.</p>
158
<name>monitor_nodes(Flag) -> ok </name>
159
<fsummary>Subscribe to node status changes</fsummary>
164
<p>Depending on <c>Flag</c>, the calling process starts
165
subscribing (<c>Flag == true</c>) or stops subscribing
166
(<c>Flag == false</c>) to node status change messages.</p>
167
<p>A process which has subscribed will receive the messages
168
<c>{nodeup, Node}</c> and <c>{nodedown, Node}</c> when a
169
group node connects or disconnects, respectively.</p>
173
<name>own_nodes() -> Nodes</name>
174
<fsummary>Return the group nodes</fsummary>
176
<v>Nodes = [Node]</v>
177
<v> Node = node()</v>
180
<p>Returns the names of all group nodes, regardless of their
185
<name>registered_names(Where) -> Names</name>
186
<fsummary>Return globally registered names</fsummary>
188
<v>Where = {node, Node} | {group, GroupName}</v>
189
<v> Node = node()</v>
190
<v> GroupName = atom()</v>
191
<v>Names = [Name]</v>
192
<v> Name = atom()</v>
195
<p>Returns a list of all names which are globally registered
196
on the specified node or in the specified global group.</p>
200
<name>send(Name, Msg) -> pid() | {badarg, {Name, Msg}}</name>
201
<name>send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}}</name>
202
<fsummary>Send a message to a globally registered pid</fsummary>
204
<v>Where = {node, Node} | {group, GroupName}</v>
205
<v> Node = node()</v>
206
<v> GroupName = atom()</v>
211
<p>Searches for <c>Name</c>, globally registered on
212
the specified node or in the specified global group, or --
213
if the <c>Where</c> argument is not provided -- in any global
214
group. The global groups are searched in the order in which
215
they appear in the value of the <c>global_groups</c>
216
configuration parameter.</p>
217
<p>If <c>Name</c> is found, the message <c>Msg</c> is sent to
218
the corresponding pid. The pid is also the return value of
219
the function. If the name is not found, the function returns
220
<c>{badarg, {Name, Msg}}</c>.</p>
224
<name>sync() -> ok</name>
225
<fsummary>Synchronize the group nodes</fsummary>
227
<p>Synchronizes the group nodes, that is, the global name
228
servers on the group nodes. Also check the names globally
229
registered in the current global group and unregisters them
230
on any known node not part of the group.</p>
231
<p>If synchronization is not possible, an error report is sent
232
to the error logger (see also <c>error_logger(3)</c>).</p>
234
<c>{error, {'invalid global_groups definition', Bad}}</c> if
235
the <c>global_groups</c> configuration parameter has an
236
invalid value <c>Bad</c>.</p>
240
<name>whereis_name(Name) -> pid() | undefined</name>
241
<name>whereis_name(Where, Name) -> pid() | undefined</name>
242
<fsummary>Get the pid with a given globally registered name</fsummary>
244
<v>Where = {node, Node} | {group, GroupName}</v>
245
<v> Node = node()</v>
246
<v> GroupName = atom()</v>
250
<p>Searches for <c>Name</c>, globally registered on
251
the specified node or in the specified global group, or -- if
252
the <c>Where</c> argument is not provided -- in any global
253
group. The global groups are searched in the order in which
254
they appear in the value of the <c>global_groups</c>
255
configuration parameter.</p>
256
<p>If <c>Name</c> is found, the corresponding pid is returned.
257
If the name is not found, the function returns
258
<c>undefined</c>.</p>
265
<p>In the situation where a node has lost its connections to other
266
nodes in its global group, but has connections to nodes in other
267
global groups, a request from another global group may produce an
268
incorrect or misleading result. For example, the isolated node may
269
not have accurate information about registered names in its
271
<p>Note also that the <c>send/2,3</c> function is not secure.</p>
272
<p>Distribution of applications is highly dependent of the global
273
group definitions. It is not recommended that an application is
274
distributed over several global groups of the obvious reason that
275
the registered names may be moved to another global group at
276
failover/takeover. There is nothing preventing doing this, but
277
the application code must in such case handle the situation.</p>
281
<title>SEE ALSO</title>
282
<p><seealso marker="erts:erl">erl(1)</seealso>,
283
<seealso marker="global">global(3)</seealso></p>
added
removed
lib/kernel/doc/src/global_group.xml
