Unix/Linux Go Back    


Linux 2.6 - man page for global_group (linux section 3erl)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


global_group(3erl)		     Erlang Module Definition		       global_group(3erl)

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 parti-
       tions, each partition having its own global name space, refer to global(3erl) . These par-
       titions 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 ker-
       nel(7) , config(5) :

       {global_groups, [GroupTuple]}

       Types:

	 * GroupTuple = {GroupName, [Node]} | {GroupName, PublishType, [Node]}

	 * GroupName = atom() (naming a global group)

	 * PublishType = normal | hidden

	 * Node = atom() (naming a node)

       A GroupTuple without PublishType is the same as a GroupTuple with PublishType == 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 normal (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.

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

	 * An  instance  of the global group server, global_group , must be running on each node.
	   The processes are automatically started and synchronized 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.

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

	      Types  GroupName = atom()
		     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() -> [{Item, Info}]

	      Types  Item, Info -- see below

	      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  connec-
		  tions.

		{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 subscribed  to  nodeup  and
		  nodedown messages.

       monitor_nodes(Flag) -> ok

	      Types  Flag = bool()

	      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  {node-
	      down, Node} when a group node connects or disconnects, respectively.

       own_nodes() -> Nodes

	      Types  Nodes = [Node]
		     Node = node()

	      Returns the names of all group nodes, regardless of their current status.

       registered_names(Where) -> Names

	      Types  Where = {node, Node} | {group, GroupName}
		     Node = node()
		     GroupName = atom()
		     Names = [Name]
		     Name = atom()

	      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 = {node, Node} | {group, GroupName}
		     Node = node()
		     GroupName = atom()
		     Name = atom()
		     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  unregis-
	      ters 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(3erl) ).

	      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 = {node, Node} | {group, GroupName}
		     Node = node()
		     GroupName = atom()
		     Name = atom()

	      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 obvi-
       ous  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(3erl)

Ericsson AB				  kernel 2.14.3 		       global_group(3erl)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:59 AM.