aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/global.xml
diff options
context:
space:
mode:
authorErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
committerErlang/OTP <[email protected]>2009-11-20 14:54:40 +0000
commit84adefa331c4159d432d22840663c38f155cd4c1 (patch)
treebff9a9c66adda4df2106dfd0e5c053ab182a12bd /lib/kernel/doc/src/global.xml
downloadotp-84adefa331c4159d432d22840663c38f155cd4c1.tar.gz
otp-84adefa331c4159d432d22840663c38f155cd4c1.tar.bz2
otp-84adefa331c4159d432d22840663c38f155cd4c1.zip
The R13B03 release.OTP_R13B03
Diffstat (limited to 'lib/kernel/doc/src/global.xml')
-rw-r--r--lib/kernel/doc/src/global.xml399
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&ouml;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>&nbsp;ResourceId = term()</v>
+ <v>&nbsp;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>&nbsp;&nbsp;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>&nbsp;&nbsp;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>&nbsp;ResourceId = term()</v>
+ <v>&nbsp;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>&nbsp;ResourceId = term()</v>
+ <v>&nbsp;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>
+