global_group(3)

MODULE
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 has its own global name registration facility, refer to global(3). These partitions are called global groups. Each global group has its own global name space.
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 global names.

The node_groups-key in the .config file defines the node groups:

{node_groups, [{GroupName, [Node]}] }

GroupName is an atom() naming a global group.
Node is an atom() naming a node.

The command erl -config File starts a node with a configuration file named File.config. If the node_groups-key is not defined the system will start as a whole, without any partitions. When the key is not defined, the services of this function will not give any extra value to global(3).

For the processes and nodes to run smoothly using this function the following criteria must be met:
1. The global group function must have a server process, global_group, running on each node. NOTE: The processes are automatically started and synchronized when a node is started.
2. All processes must agree with the node definition in the immediate global group.
3. Nodes can only belong to one global group.

EXPORTS

global_groups() -> {OwnGroupName, [OtherGroupName]} | undefined

    Types
        OwnGroupName = atom()
        OtherGroupName = atom()
        ErrorMsg = term()

    Returns the names of all the global groups known to the immediate global group.

monitor_nodes(Flag) -> ok

    Types
        Flag = bool()

    The requesting process receives {nodeup, Node} and {nodedown, Node} messages about the nodes from the immediate global group. If the flag Flag is set to true the service is turned on; false turns it off.

own_nodes() -> [Node]

    Types
        Node = atom()

    Returns the names of nodes from the immediate global group.

registered_names({node, Node}) -> [Name]
registered_names({group, GlobalGroupName}) -> [Name]

    Types
        Name = term()
        Node = atom()
        GlobalGroupName = atom()

    Returns a lists of all globally registered names on the specified node or from the specified global group.

send(Name, Msg) -> Pid
send({node, Node}, Name, Msg) -> Pid
send({group, GlobalGroupName}, Name, Msg) -> Pid

    Types
        GlobalGroupName = atom()
        Msg = term()
        Name = term()
        Node = atom()
        Pid = pid()

    send/2 searches for the registered Name in all global groups defined, in the order of appearance in the .config-file, until the registered name is found or all groups are searched. If Name is found, the message Msg is sent to it. If it is not found, the function exits with reason {badarg, {Name, Msg}}.

    send/3 searches for the registered Name in either the specified node or the specified global group. If the registered name is found, the message Msg is sent to that process. If Name is not found, the function exits with reason {badarg, {Name, Msg}}.

whereis_name(Name) -> Pid | undefined
whereis_name({node, Node}, Name) -> Pid | undefined
whereis_name({group, GlobalGroupName}, Name) -> Pid | undefined

    Types
        GlobalGroupName = atom()
        Name = term()
        Node = atom()
        Pid = pid()

    whereis_name/1 searches for the registered Name in all global groups defined, in the order of appearance in the .config-file, until the registered name is found or all groups are searched.

    whereis_name/2 searches for the registered Name in either the specified node or the specified global group.

    Returns either the atom undefined, or the Pid which is associated with Name.

start()
start_link() -> {ok, Pid} | {error, Reason}

    This function starts the global group server. Normally, the server is started automatically.

stop() -> void()

    Stops the global group server.

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 the other global group may produce an incorrect or misleading result. When this occurs the isolated node may not have accurate information, for example, about registered names in its global group.

Note also that the send function is not secure.

SEE ALSO

erl(1), global(3)

AUTHOR
Esko Vierumaki - esko@erix.ericsson.se