1global_group(3) Erlang Module Definition global_group(3)
2
6 global_group - Grouping nodes to global name registration groups.
7
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 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 The Kernel configuration parameter global_groups defines the global
18 groups (see also kernel(6) and config(4)):
19 {global_groups, [GroupTuple :: group_tuple()]}
21 For the processes and nodes to run smoothly using the global group
23 functionality, the following criteria must be met:
24 * 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 * All involved nodes must agree on the global group definition, oth‐
30 erwise the behavior of the system is undefined.
31 * All nodes in the system must belong to exactly one global group.
33 In the following descriptions, a group node is a node belonging to the
35 same global group as the local node.
36
38 group_tuple() =
39 {GroupName :: group_name(), [node()]} |
40 {GroupName :: group_name(),
41 PublishType :: publish_type(),
42 [node()]}
43 A GroupTuple without PublishType is the same as a GroupTuple
45 with PublishType equal to normal.
46 group_name() = atom()
48 publish_type() = hidden | normal
50 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 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 name() = atom()
62 A registered name.
64 where() = {node, node()} | {group, group_name()}
66
68 global_groups() -> {GroupName, GroupNames} | undefined
69 Types:
71 GroupName = group_name()
73 GroupNames = [GroupName]
74 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 info() -> [info_item()]
80 Types:
82 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 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 {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 {own_group_name, GroupName}:
104 The name (atom) of the group that the local node belongs to.
105 {own_group_nodes, Nodes}:
107 A list of node names (atoms), the group nodes.
108 {synced_nodes, Nodes}:
110 A list of node names, the group nodes currently synchronized
111 with the local node.
112 {sync_error, Nodes}:
114 A list of node names, the group nodes with which the local
115 node has failed to synchronize.
116 {no_contact, Nodes}:
118 A list of node names, the group nodes to which there are
119 currently no connections.
120 {other_groups, Groups}:
122 Groups is a list of tuples {GroupName, Nodes}, specifying
123 the name and nodes of the other global groups.
124 {monitoring, Pids}:
126 A list of pids, specifying the processes that have sub‐
127 scribed to nodeup and nodedown messages.
128 monitor_nodes(Flag) -> ok
130 Types:
132 Flag = boolean()
134 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 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 own_nodes() -> Nodes
144 Types:
146 Nodes = [Node :: node()]
148 Returns the names of all group nodes, regardless of their cur‐
150 rent status.
151 registered_names(Where) -> Names
153 Types:
155 Where = where()
157 Names = [Name :: name()]
158 Returns a list of all names that are globally registered on the
160 specified node or in the specified global group.
161 send(Name, Msg) -> pid() | {badarg, {Name, Msg}}
163 send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}}
165 Types:
167 Where = where()
169 Name = name()
170 Msg = term()
171 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 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 sync() -> ok
183 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 If synchronization is not possible, an error report is sent to
190 the error logger (see also error_logger(3).
191 Returns {error, {'invalid global_groups definition', Bad}} if
193 configuration parameter global_groups has an invalid value Bad.
194 whereis_name(Name) -> pid() | undefined
196 whereis_name(Where, Name) -> pid() | undefined
198 Types:
200 Where = where()
202 Name = name()
203 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 If Name is found, the corresponding pid is returned. If the name
211 is not found, the function returns undefined.
212
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 * Function send/2,3 is not secure.
222 * 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
231 global(3), erl(1)
232Ericsson AB kernel 6.5 global_group(3)