From 5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 16:01:56 +0200 Subject: Use Erlang specs and types for documentation --- lib/kernel/doc/src/global.xml | 176 ++++++++++++++++-------------------------- 1 file changed, 68 insertions(+), 108 deletions(-) (limited to 'lib/kernel/doc/src/global.xml') diff --git a/lib/kernel/doc/src/global.xml b/lib/kernel/doc/src/global.xml index 077109d6c9..304a9b1d88 100644 --- a/lib/kernel/doc/src/global.xml +++ b/lib/kernel/doc/src/global.xml @@ -4,7 +4,7 @@
- 19962009 + 19962011 Ericsson AB. All Rights Reserved. @@ -106,45 +106,37 @@ + + + + + + - del_lock(Id) - del_lock(Id, Nodes) -> void() + + Delete a lock - - Id = {ResourceId, LockRequesterId} -  ResourceId = term() -  LockRequesterId = term() - Nodes = [node()] - -

Deletes the lock Id synchronously.

+

Deletes the lock Id synchronously.

- notify_all_name(Name, Pid1, Pid2) -> none + Name resolving function that notifies both pids - - Name = term() - Pid1 = Pid2 = pid() -

This function can be used as a name resolving function for register_name/3 and re_register_name/3. It unregisters both pids, and sends the message - {global_name_conflict, Name, OtherPid} to both + {global_name_conflict, Name, OtherPid} to both processes.

- random_exit_name(Name, Pid1, Pid2) -> Pid1 | Pid2 + Name resolving function that kills one pid - - Name = term() - Pid1 = Pid2 = pid() -

This function can be used as a name resolving function for register_name/3 and re_register_name/3. It @@ -154,33 +146,27 @@ - random_notify_name(Name, Pid1, Pid2) -> Pid1 | Pid2 + Name resolving function that notifies one pid - - Name = term() - Pid1 = Pid2 = pid() -

This function can be used as a name resolving function for register_name/3 and re_register_name/3. It randomly chooses one of the pids for registration, and sends - the message {global_name_conflict, Name} to the other + the message {global_name_conflict, Name} to the other pid.

- register_name(Name, Pid) - register_name(Name, Pid, Resolve) -> yes | no + + Globally register a name for a pid - - Name = term() - Pid = pid() - Resolve = fun() or {Module, Function} where -   Resolve(Name, Pid, Pid2) -> Pid | Pid2 | none - + + {Module, Function} + is also allowed + -

Globally associates the name Name with a pid, that is, +

Globally associates the name Name with a pid, that is, Globally notifies all nodes of a new global name in a network of Erlang nodes.

@@ -188,7 +174,7 @@ 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 Resolve function is called. Its purpose is to + the Resolve 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 @@ -196,7 +182,7 @@

There are three pre-defined resolve functions: random_exit_name/3, random_notify_name/3, and - notify_all_name/3. If no Resolve function is + notify_all_name/3. If no Resolve function is defined, random_exit_name is used. This means that one of the two registered processes will be selected as correct while the other is killed.

@@ -225,78 +211,63 @@
- registered_names() -> [Name] + All globally registered names - - Name = term() -

Returns a lists of all globally registered names.

- re_register_name(Name, Pid) - re_register_name(Name, Pid, Resolve) -> void() + + Atomically re-register a name - - Name = term() - Pid = pid() - Resolve = fun() or {Module, Function} where -   Resolve(Name, Pid, Pid2) -> Pid | Pid2 | none - + + {Module, Function} + is also allowed + -

Atomically changes the registered name Name on all - nodes to refer to Pid.

+

Atomically changes the registered name Name on all + nodes to refer to Pid.

-

The Resolve function has the same behavior as in +

The Resolve function has the same behavior as in register_name/2,3.

- send(Name, Msg) -> Pid + Send a message to a globally registered pid - - Name = term() - Msg = term() - Pid = pid() - -

Sends the message Msg to the pid globally registered - as Name.

+

Sends the message Msg to the pid globally registered + as Name.

-

Failure: If Name is not a globally registered +

Failure: If Name is not a globally registered name, the calling function will exit with reason - {badarg, {Name, Msg}}.

+ {badarg, {Name, Msg}}.

- set_lock(Id) - set_lock(Id, Nodes) - set_lock(Id, Nodes, Retries) -> boolean() + + + Set a lock on the specified nodes - - Id = {ResourceId, LockRequesterId} -  ResourceId = term() -  LockRequesterId = term() - Nodes = [node()] - Retries = int() >= 0 | infinity - + +

Sets a lock on the specified nodes (or on all nodes if none - are specified) on ResourceId for - LockRequesterId. If a lock already exists on - ResourceId for another requester than - LockRequesterId, and Retries is not equal to 0, + are specified) on ResourceId for + LockRequesterId. If a lock already exists on + ResourceId for another requester than + LockRequesterId, and Retries is not equal to 0, the process sleeps for a while and will try to execute - the action later. When Retries attempts have been made, + the action later. When Retries attempts have been made, false is returned, otherwise true. If - Retries is infinity, true is eventually + Retries is infinity, true is eventually returned (unless the lock is never released).

-

If no value for Retries is given, infinity is +

If no value for Retries is given, infinity is used.

This function is completely synchronous.

@@ -315,7 +286,7 @@ application to detect and rectify a deadlock.

-

Some values of ResourceId should be avoided or +

Some values of ResourceId should be avoided or Erlang/OTP will not work properly. A list of resources to avoid: global, dist_ac, mnesia_table_lock, mnesia_adjust_log_writes, @@ -326,7 +297,7 @@ - sync() -> void() + Synchronize the global name server

Synchronizes the global name server with all nodes known to @@ -335,56 +306,45 @@ the global name server will receive global information from all nodes. This function can be called when new nodes are added to the network.

+

The only possible error reason Reason is + {"global_groups definition error", Error}.

- trans(Id, Fun) - trans(Id, Fun, Nodes) - trans(Id, Fun, Nodes, Retries) -> Res | aborted + + + Micro transaction facility - - Id = {ResourceId, LockRequesterId} -  ResourceId = term() -  LockRequesterId = term() - Fun = fun() | {M, F} - Nodes = [node()] - Retries = int() >= 0 | infinity - Res = term() - + + -

Sets a lock on Id (using set_lock/3). If this - succeeds, Fun() is evaluated and the result Res +

Sets a lock on Id (using set_lock/3). If this + succeeds, Fun() is evaluated and the result Res is returned. Returns aborted if the lock attempt - failed. If Retries is set to infinity, + failed. If Retries is set to infinity, the transaction will not abort.

infinity is the default setting and will be used if - no value is given for Retries.

+ no value is given for Retries.

- unregister_name(Name) -> void() + Remove a globally registered name for a pid - - Name = term() - -

Removes the globally registered name Name from +

Removes the globally registered name Name from the network of Erlang nodes.

- whereis_name(Name) -> pid() | undefined + Get the pid with a given globally registered name - - Name = term() -

Returns the pid with the globally registered name - Name. Returns undefined if the name is not + Name. Returns undefined if the name is not globally registered.

-- cgit v1.2.3