diff options
Diffstat (limited to 'lib/kernel/doc/src/global.xml')
| -rw-r--r-- | lib/kernel/doc/src/global.xml | 399 |
1 files changed, 399 insertions, 0 deletions
diff --git a/lib/kernel/doc/src/global.xml b/lib/kernel/doc/src/global.xml new file mode 100644 index 0000000000..077109d6c9 --- /dev/null +++ b/lib/kernel/doc/src/global.xml @@ -0,0 +1,399 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1996</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>global</title> + <prepared>Martin Björklund</prepared> + <docno></docno> + <date>1997-11-17</date> + <rev></rev> + </header> + <module>global</module> + <modulesummary>A Global Name Registration Facility</modulesummary> + <description> + <p>This documentation describes the Global module which consists + of the following functionalities:</p> + + <list type="bulleted"> + <item>registration of global names;</item> + <item>global locks;</item> + <item>maintenance of the fully connected network.</item> + </list> + + <p>These services are controlled via the process + <c>global_name_server</c> which exists on every node. The global + name server is started automatically when a node is started. + With the term <em>global</em> is meant over a system consisting + of several Erlang nodes.</p> + + <p>The ability to globally register names is a central concept in + the programming of distributed Erlang systems. In this module, + the equivalent of the <c>register/2</c> and <c>whereis/1</c> + BIFs (for local name registration) are implemented, but for a + network of Erlang nodes. A registered name is an alias for a + process identifier (pid). The global name server monitors + globally registered pids. If a process terminates, the name will + also be globally unregistered.</p> + + <p>The registered names are stored in replica global name tables on + every node. There is no central storage point. Thus, + the translation of a name to a pid is fast, as it is always done + locally. When any action in taken which results in a change to + the global name table, all tables on other nodes are automatically + updated.</p> + + <p>Global locks have lock identities and are set on a specific + resource. For instance, the specified resource could be a pid. + When a global lock is set, access to the locked resource is + denied for all other resources other than the lock requester.</p> + + <p>Both the registration and lock functionalities are atomic. All + nodes involved in these actions will have the same view of + the information.</p> + + <p>The global name server also performs the critical task of + continuously monitoring changes in node configuration: if a node + which runs a globally registered process goes down, the name + will be globally unregistered. To this end the global name + server subscribes to <c>nodeup</c> and <c>nodedown</c> messages + sent from the <c>net_kernel</c> module. Relevant Kernel + application variables in this context are <c>net_setuptime</c>, + <c>net_ticktime</c>, and <c>dist_auto_connect</c>. See also + <seealso marker="kernel_app#net_setuptime">kernel(6)</seealso>.</p> + + <p>The name server will also maintain a fully connected network. For + example, if node <c>N1</c> connects to node <c>N2</c> (which is + already connected to <c>N3</c>), the global name servers on the + nodes <c>N1</c> and <c>N3</c> will make sure that also <c>N1</c> + and <c>N3</c> are connected. If this is not desired, the command + line flag <c>-connect_all false</c> can be used (see also + <seealso marker="erts:erl#connect_all">erl(1)</seealso>). In + this case the name registration facility cannot be used, but the + lock mechanism will still work.</p> + + <p>If the global name server fails to connect nodes (<c>N1</c> and + <c>N3</c> in the example above) a warning event is sent to the + error logger. The presence of such an event does not exclude the + possibility that the nodes will later connect--one can for + example try the command <c>rpc:call(N1, net_adm, ping, [N2])</c> in + the Erlang shell--but it indicates some kind of problem with + the network.</p> + + <note> + <p>If the fully connected network is not set up properly, the + first thing to try is to increase the value of + <c>net_setuptime</c>.</p> + </note> + + </description> + + <funcs> + <func> + <name>del_lock(Id)</name> + <name>del_lock(Id, Nodes) -> void()</name> + <fsummary>Delete a lock</fsummary> + <type> + <v>Id = {ResourceId, LockRequesterId}</v> + <v> ResourceId = term()</v> + <v> LockRequesterId = term()</v> + <v>Nodes = [node()]</v> + </type> + <desc> + <p>Deletes the lock <c>Id</c> synchronously.</p> + </desc> + </func> + + <func> + <name>notify_all_name(Name, Pid1, Pid2) -> none</name> + <fsummary>Name resolving function that notifies both pids</fsummary> + <type> + <v>Name = term()</v> + <v>Pid1 = Pid2 = pid()</v> + </type> + <desc> + <p>This function can be used as a name resolving function for + <c>register_name/3</c> and <c>re_register_name/3</c>. It + unregisters both pids, and sends the message + <c>{global_name_conflict, Name, OtherPid}</c> to both + processes.</p> + </desc> + </func> + + <func> + <name>random_exit_name(Name, Pid1, Pid2) -> Pid1 | Pid2</name> + <fsummary>Name resolving function that kills one pid</fsummary> + <type> + <v>Name = term()</v> + <v>Pid1 = Pid2 = pid()</v> + </type> + <desc> + <p>This function can be used as a name resolving function for + <c>register_name/3</c> and <c>re_register_name/3</c>. It + randomly chooses one of the pids for registration and kills + the other one.</p> + </desc> + </func> + + <func> + <name>random_notify_name(Name, Pid1, Pid2) -> Pid1 | Pid2</name> + <fsummary>Name resolving function that notifies one pid</fsummary> + <type> + <v>Name = term()</v> + <v>Pid1 = Pid2 = pid()</v> + </type> + <desc> + <p>This function can be used as a name resolving function for + <c>register_name/3</c> and <c>re_register_name/3</c>. It + randomly chooses one of the pids for registration, and sends + the message <c>{global_name_conflict, Name}</c> to the other + pid.</p> + </desc> + </func> + + <func> + <name>register_name(Name, Pid)</name> + <name>register_name(Name, Pid, Resolve) -> yes | no</name> + <fsummary>Globally register a name for a pid</fsummary> + <type> + <v>Name = term()</v> + <v>Pid = pid()</v> + <v>Resolve = fun() or {Module, Function} where</v> + <v> Resolve(Name, Pid, Pid2) -> Pid | Pid2 | none</v> + </type> + <desc> + <p>Globally associates the name <c>Name</c> with a pid, that is, + Globally notifies all nodes of a new global name in a network + of Erlang nodes.</p> + + <p>When new nodes are added to the network, they are informed + of the globally registered names that already exist. + The network is also informed of any global names in newly + connected nodes. If any name clashes are discovered, + the <c>Resolve</c> function is called. Its purpose is to + decide which pid is correct. If the function crashes, or + returns anything other than one of the pids, the name is + unregistered. This function is called once for each name + clash.</p> + + <p>There are three pre-defined resolve functions: + <c>random_exit_name/3</c>, <c>random_notify_name/3</c>, and + <c>notify_all_name/3</c>. If no <c>Resolve</c> function is + defined, <c>random_exit_name</c> is used. This means that one + of the two registered processes will be selected as correct + while the other is killed.</p> + + <p>This function is completely synchronous. This means that + when this function returns, the name is either registered on + all nodes or none.</p> + + <p>The function returns <c>yes</c> if successful, <c>no</c> if + it fails. For example, <c>no</c> is returned if an attempt + is made to register an already registered process or to + register a process with a name that is already in use.</p> + + <note> + <p>Releases up to and including OTP R10 did not check if the + process was already registered. As a consequence the + global name table could become inconsistent. The old + (buggy) behavior can be chosen by giving the Kernel + application variable <c>global_multi_name_action</c> the + value <c>allow</c>.</p> + </note> + + <p>If a process with a registered name dies, or the node goes + down, the name is unregistered on all nodes.</p> + </desc> + </func> + + <func> + <name>registered_names() -> [Name]</name> + <fsummary>All globally registered names</fsummary> + <type> + <v>Name = term()</v> + </type> + <desc> + <p>Returns a lists of all globally registered names.</p> + </desc> + </func> + + <func> + <name>re_register_name(Name, Pid)</name> + <name>re_register_name(Name, Pid, Resolve) -> void()</name> + <fsummary>Atomically re-register a name</fsummary> + <type> + <v>Name = term()</v> + <v>Pid = pid()</v> + <v>Resolve = fun() or {Module, Function} where</v> + <v> Resolve(Name, Pid, Pid2) -> Pid | Pid2 | none</v> + </type> + <desc> + <p>Atomically changes the registered name <c>Name</c> on all + nodes to refer to <c>Pid</c>.</p> + + <p>The <c>Resolve</c> function has the same behavior as in + <c>register_name/2,3</c>.</p> + </desc> + </func> + + <func> + <name>send(Name, Msg) -> Pid</name> + <fsummary>Send a message to a globally registered pid</fsummary> + <type> + <v>Name = term()</v> + <v>Msg = term()</v> + <v>Pid = pid()</v> + </type> + <desc> + <p>Sends the message <c>Msg</c> to the pid globally registered + as <c>Name</c>.</p> + + <p>Failure: If <c>Name</c> is not a globally registered + name, the calling function will exit with reason + <c>{badarg, {Name, Msg}}</c>.</p> + </desc> + </func> + + <func> + <name>set_lock(Id)</name> + <name>set_lock(Id, Nodes)</name> + <name>set_lock(Id, Nodes, Retries) -> boolean()</name> + <fsummary>Set a lock on the specified nodes</fsummary> + <type> + <v>Id = {ResourceId, LockRequesterId}</v> + <v> ResourceId = term()</v> + <v> LockRequesterId = term()</v> + <v>Nodes = [node()]</v> + <v>Retries = int() >= 0 | infinity</v> + </type> + <desc> + <p>Sets a lock on the specified nodes (or on all nodes if none + are specified) on <c>ResourceId</c> for + <c>LockRequesterId</c>. If a lock already exists on + <c>ResourceId</c> for another requester than + <c>LockRequesterId</c>, and <c>Retries</c> is not equal to 0, + the process sleeps for a while and will try to execute + the action later. When <c>Retries</c> attempts have been made, + <c>false</c> is returned, otherwise <c>true</c>. If + <c>Retries</c> is <c>infinity</c>, <c>true</c> is eventually + returned (unless the lock is never released).</p> + + <p>If no value for <c>Retries</c> is given, <c>infinity</c> is + used.</p> + + <p>This function is completely synchronous.</p> + + <p>If a process which holds a lock dies, or the node goes + down, the locks held by the process are deleted.</p> + + <p>The global name server keeps track of all processes sharing + the same lock, that is, if two processes set the same lock, + both processes must delete the lock.</p> + + <p>This function does not address the problem of a deadlock. A + deadlock can never occur as long as processes only lock one + resource at a time. But if some processes try to lock two or + more resources, a deadlock may occur. It is up to the + application to detect and rectify a deadlock.</p> + + <note> + <p>Some values of <c>ResourceId</c> should be avoided or + Erlang/OTP will not work properly. A list of resources to + avoid: <c>global</c>, <c>dist_ac</c>, + <c>mnesia_table_lock</c>, <c>mnesia_adjust_log_writes</c>, + <c>pg2</c>.</p> + </note> + + </desc> + </func> + + <func> + <name>sync() -> void()</name> + <fsummary>Synchronize the global name server</fsummary> + <desc> + <p>Synchronizes the global name server with all nodes known to + this node. These are the nodes which are returned from + <c>erlang:nodes()</c>. When this function returns, + the global name server will receive global information from + all nodes. This function can be called when new nodes are + added to the network.</p> + </desc> + </func> + + <func> + <name>trans(Id, Fun)</name> + <name>trans(Id, Fun, Nodes)</name> + <name>trans(Id, Fun, Nodes, Retries) -> Res | aborted</name> + <fsummary>Micro transaction facility</fsummary> + <type> + <v>Id = {ResourceId, LockRequesterId}</v> + <v> ResourceId = term()</v> + <v> LockRequesterId = term()</v> + <v>Fun = fun() | {M, F}</v> + <v>Nodes = [node()]</v> + <v>Retries = int() >= 0 | infinity</v> + <v>Res = term()</v> + </type> + <desc> + <p>Sets a lock on <c>Id</c> (using <c>set_lock/3</c>). If this + succeeds, <c>Fun()</c> is evaluated and the result <c>Res</c> + is returned. Returns <c>aborted</c> if the lock attempt + failed. If <c>Retries</c> is set to <c>infinity</c>, + the transaction will not abort.</p> + + <p><c>infinity</c> is the default setting and will be used if + no value is given for <c>Retries</c>.</p> + </desc> + </func> + + <func> + <name>unregister_name(Name) -> void()</name> + <fsummary>Remove a globally registered name for a pid</fsummary> + <type> + <v>Name = term()</v> + </type> + <desc> + <p>Removes the globally registered name <c>Name</c> from + the network of Erlang nodes.</p> + </desc> + </func> + + <func> + <name>whereis_name(Name) -> pid() | undefined</name> + <fsummary>Get the pid with a given globally registered name</fsummary> + <type> + <v>Name = term()</v> + </type> + <desc> + <p>Returns the pid with the globally registered name + <c>Name</c>. Returns <c>undefined</c> if the name is not + globally registered.</p> + </desc> + </func> + </funcs> + + <section> + <title>See Also</title> + <p><seealso marker="global_group">global_group(3)</seealso>, + <seealso marker="net_kernel">net_kernel(3)</seealso></p> + </section> +</erlref> + |