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
       This  module  makes it possible to partition the	nodes of a system into
       global groups. Each global group	has  its  own  global  namespace,  see
       global(3).

       The  main  advantage of dividing	systems	into 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) and 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, oth-
	   erwise the behavior of the system is	undefined.

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

       In the following	descriptions, 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 equal to	normal.

       group_name() = atom()

       publish_type() =	hidden | normal

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

	      A	 global	group defined with PublishType equal to	hidden is said
	      to be a hidden global group. All nodes in	a hidden global	 group
	      are  hidden  nodes,  whether  they are started with command-line
	      flag -hidden 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 that 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  list  element is a tuple. The order	of the tuples is unde-
	      fined.

		{state,	State}:
		  If the local node is part of a global	group, State is	 equal
		  to  synced.  If no global groups are defined,	State is equal
		  to 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  that  have  sub-
		  scribed to nodeup and	nodedown messages.

       monitor_nodes(Flag) -> ok

	      Types:

		 Flag =	boolean()

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

	      A	 process  that	has  subscribed	receives the messages {nodeup,
	      Node} and	{nodedown, Node} when a	group node connects or discon-
	      nects, 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 that 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 argument Where is not pro-
	      vided)  in  any  global group. The global	groups are searched in
	      the order	that they appear in the	value of configuration parame-
	      ter global_groups.

	      If  Name is found, 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 checks 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).

	      Returns  {error,	{'invalid  global_groups definition', Bad}} if
	      configuration parameter global_groups 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 argument Where is not pro-
	      vided) in	any global group. The global groups  are  searched  in
	      the order	that they appear in the	value of configuration parame-
	      ter global_groups.

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

NOTES
	 * 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	can produce an
	   incorrect or	misleading result. For example,	the isolated node  can
	   have	 inaccurate  information  about	registered names in its	global
	   group.

	 * Function send/2,3 is	not secure.

	 * Distribution	of applications	is  highly  dependent  of  the	global
	   group  definitions.	It  is	not recommended	that an	application is
	   distributed over many global	groups,	as the registered names	can be
	   moved  to  another  global group at failover/takeover. Nothing pre-
	   vents this to be done, but the application code  must  then	handle
	   the situation.

SEE ALSO
       global(3), erl(1)

Ericsson AB			  kernel 6.3		       global_group(3)

NAME | DESCRIPTION | DATA TYPES | EXPORTS | NOTES | 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+13.0-RELEASE+and+Ports>

home | help