Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
global_group(3)		   Erlang Module Definition	       global_group(3)

NAME
       global_group - Grouping Nodes to	Global Name Registration Groups

DESCRIPTION
       The  global  group  function  makes it possible to group	the nodes in a
       system into partitions, each  partition	having	its  own  global  name
       space, refer to global(3). These	partitions are called global groups.

       The  main  advantage  of	 dividing systems to global groups is that the
       background load decreases while the number of nodes to  be  updated  is
       reduced when manipulating globally registered names.

       The  Kernel  configuration  parameter  global_groups defines the	global
       groups (see also	kernel(6), config(4):

       {global_groups, [GroupTuple :: group_tuple()]}

       For the processes and nodes to run  smoothly  using  the	 global	 group
       functionality, the following criteria must be met:

	 * An  instance	of the global group server, global_group, must be run-
	   ning	on each	node. The processes are	automatically started and syn-
	   chronized when a node is started.

	 * All	involved  nodes	 must agree on the global group	definition, or
	   the behavior	of the system is undefined.

	 * All nodes in	the system should belong to exactly one	global group.

       In the following	description, a group node is a node belonging  to  the
       same global group as the	local node.

DATA TYPES
       group_tuple() = {GroupName :: group_name(), [node()]}
		     | {GroupName :: group_name(),
			PublishType :: publish_type(),
			[node()]}

	      A	 GroupTuple  without  PublishType  is the same as a GroupTuple
	      with PublishType == normal.

       group_name() = atom()

       publish_type() =	hidden | normal

	      A	node started with the command line flag	-hidden,  see  erl(1),
	      is said to be a hidden node. A hidden node will establish	hidden
	      connections to nodes not part of the same	global group, but nor-
	      mal  (visible)  connections  to  nodes  part  of the same	global
	      group.

	      A	global group defined with PublishType == hidden, is said to be
	      a	 hidden	 global	 group.	All nodes in a hidden global group are
	      hidden nodes, regardless if they are started  with  the  -hidden
	      command line flag	or not.

       name() =	atom()

	      A	registered name.

       where() = {node,	node()}	| {group, group_name()}

EXPORTS
       global_groups() -> {GroupName, GroupNames} | undefined

	      Types:

		 GroupName = group_name()
		 GroupNames = [GroupName]

	      Returns  a  tuple	 containing  the  name of the global group the
	      local node belongs to, and the list of  all  other  known	 group
	      names. Returns undefined if no global groups are defined.

       info() -> [info_item()]

	      Types:

		 info_item() = {state, State ::	sync_state()}
			     | {own_group_name,	GroupName :: group_name()}
			     | {own_group_nodes, Nodes :: [node()]}
			     | {synched_nodes, Nodes ::	[node()]}
			     | {sync_error, Nodes :: [node()]}
			     | {no_contact, Nodes :: [node()]}
			     | {other_groups, Groups ::	[group_tuple()]}
			     | {monitoring, Pids :: [pid()]}
		 sync_state() =	no_conf	| synced

	      Returns  a  list containing information about the	global groups.
	      Each element of the list is a tuple. The order of	the tuples  is
	      not defined.

		{state,	State}:
		  If  the  local  node	is  part  of  a	global group, State ==
		  synced. If no	global groups are defined, State == no_conf.

		{own_group_name, GroupName}:
		  The name (atom) of the group that the	local node belongs to.

		{own_group_nodes, Nodes}:
		  A list of node names (atoms),	the group nodes.

		{synced_nodes, Nodes}:
		  A list of node names,	the group nodes	currently synchronized
		  with the local node.

		{sync_error, Nodes}:
		  A  list  of node names, the group nodes with which the local
		  node has failed to synchronize.

		{no_contact, Nodes}:
		  A list of node names,	the group nodes	 to  which  there  are
		  currently no connections.

		{other_groups, Groups}:
		  Groups  is  a	 list of tuples	{GroupName, Nodes}, specifying
		  the name and nodes of	the other global groups.

		{monitoring, Pids}:
		  A list of pids, specifying the  processes  which  have  sub-
		  scribed to nodeup and	nodedown messages.

       monitor_nodes(Flag) -> ok

	      Types:

		 Flag =	boolean()

	      Depending	 on Flag, the calling process starts subscribing (Flag
	      == true) or stops	subscribing (Flag ==  false)  to  node	status
	      change messages.

	      A	 process  which	 has  subscribed  will	receive	 the  messages
	      {nodeup, Node} and {nodedown, Node} when a group	node  connects
	      or disconnects, respectively.

       own_nodes() -> Nodes

	      Types:

		 Nodes = [Node :: node()]

	      Returns  the  names of all group nodes, regardless of their cur-
	      rent status.

       registered_names(Where) -> Names

	      Types:

		 Where = where()
		 Names = [Name :: name()]

	      Returns a	list of	all names which	are globally registered	on the
	      specified	node or	in the specified global	group.

       send(Name, Msg) -> pid()	| {badarg, {Name, Msg}}

       send(Where, Name, Msg) -> pid() | {badarg, {Name, Msg}}

	      Types:

		 Where = where()
		 Name =	name()
		 Msg = term()

	      Searches	for Name, globally registered on the specified node or
	      in the specified global group, or	-- if the  Where  argument  is
	      not  provided  --	 in  any  global  group. The global groups are
	      searched in the order in which they appear in the	value  of  the
	      global_groups configuration parameter.

	      If  Name	is found, the message Msg is sent to the corresponding
	      pid. The pid is also the return value of the  function.  If  the
	      name is not found, the function returns {badarg, {Name, Msg}}.

       sync() -> ok

	      Synchronizes  the	 group nodes, that is, the global name servers
	      on the group nodes. Also check the names globally	registered  in
	      the  current global group	and unregisters	them on	any known node
	      not part of the group.

	      If synchronization is not	possible, an error report is  sent  to
	      the error	logger (see also error_logger(3)).

	      Failure:	{error,	 {'invalid global_groups definition', Bad}} if
	      the global_groups	configuration parameter	has an	invalid	 value
	      Bad.

       whereis_name(Name) -> pid() | undefined

       whereis_name(Where, Name) -> pid() | undefined

	      Types:

		 Where = where()
		 Name =	name()

	      Searches	for Name, globally registered on the specified node or
	      in the specified global group, or	-- if the  Where  argument  is
	      not  provided  --	 in  any  global  group. The global groups are
	      searched in the order in which they appear in the	value  of  the
	      global_groups configuration parameter.

	      If Name is found,	the corresponding pid is returned. If the name
	      is not found, the	function returns undefined.

NOTE
       In the situation	where a	node has lost its connections to  other	 nodes
       in  its	global	group,	but  has  connections to nodes in other	global
       groups, a request from another global group may produce an incorrect or
       misleading result. For example, the isolated node may not have accurate
       information about registered names in its global	group.

       Note also that the send/2,3 function is not secure.

       Distribution of applications is highly dependent	of  the	 global	 group
       definitions.  It	 is not	recommended that an application	is distributed
       over several global groups of the obvious reason	 that  the  registered
       names  may be moved to another global group at failover/takeover. There
       is nothing preventing doing this, but the application code must in such
       case handle the situation.

SEE ALSO
       erl(1), global(3)

Ericsson AB			  kernel 3.2		       global_group(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | NOTE | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=global_group&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help