aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/pg2.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/pg2.xml')
-rw-r--r--lib/kernel/doc/src/pg2.xml199
1 files changed, 199 insertions, 0 deletions
diff --git a/lib/kernel/doc/src/pg2.xml b/lib/kernel/doc/src/pg2.xml
new file mode 100644
index 0000000000..7463fd10f5
--- /dev/null
+++ b/lib/kernel/doc/src/pg2.xml
@@ -0,0 +1,199 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</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>pg2</title>
+ <prepared>[email protected]</prepared>
+ <responsible>[email protected]</responsible>
+ <docno></docno>
+ <approved>Bjarne D&auml;cker</approved>
+ <checked>[email protected]</checked>
+ <date>1997-08-18</date>
+ <rev>A2</rev>
+ <file>pg2.sgml</file>
+ </header>
+ <module>pg2</module>
+ <modulesummary>Distributed Named Process Groups</modulesummary>
+ <description>
+ <p>This module implements process groups. The groups in this
+ module differ from the groups in the module <c>pg</c> in several
+ ways. In <c>pg</c>, each message is sent to all members in the
+ group. In this module, each message may be sent to one, some, or
+ all members.
+ </p>
+ <p>A group of processes can be accessed by a common name. For
+ example, if there is a group named <c>foobar</c>, there can be a
+ set of processes (which can be located on different nodes) which
+ are all members of the group <c>foobar</c>. There are no special
+ functions for sending a message to the group. Instead, client
+ functions should be written with the functions
+ <c>get_members/1</c> and <c>get_local_members/1</c> to find out
+ which processes are members of the group. Then the message can be
+ sent to one or more members of the group.
+ </p>
+ <p>If a member terminates, it is automatically removed from the
+ group.
+ </p>
+ <warning>
+ <p>This module is used by the <c>disk_log</c> module for
+ managing distributed disk logs. The disk log names are used as
+ group names, which means that some action may need to be taken
+ to avoid name clashes.</p>
+ </warning>
+ </description>
+ <funcs>
+ <func>
+ <name>create(Name) -> void()</name>
+ <fsummary>Create a new, empty process group</fsummary>
+ <type>
+ <v>Name = term()</v>
+ </type>
+ <desc>
+ <p>Creates a new, empty process group. The group is globally
+ visible on all nodes. If the group exists, nothing happens.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>delete(Name) -> void()</name>
+ <fsummary>Delete a process group</fsummary>
+ <type>
+ <v>Name = term()</v>
+ </type>
+ <desc>
+ <p>Deletes a process group.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>get_closest_pid(Name) -> Pid | {error, Reason}</name>
+ <fsummary>Common dispatch function</fsummary>
+ <type>
+ <v>Name = term()</v>
+ <v>Pid = pid()</v>
+ <v>Reason = {no_process, Name} | {no_such_group, Name}</v>
+ </type>
+ <desc>
+ <p>This is a useful dispatch function which can be used from
+ client functions. It returns a process on the local node, if
+ such a process exist. Otherwise, it chooses one randomly.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>get_members(Name) -> [Pid] | {error, Reason}</name>
+ <fsummary>Return all processes in a group</fsummary>
+ <type>
+ <v>Name = term()</v>
+ <v>Pid = pid()</v>
+ <v>Reason = {no_such_group, Name}</v>
+ </type>
+ <desc>
+ <p>Returns all processes in the group <c>Name</c>. This
+ function should be used from within a client function that
+ accesses the group. It is therefore optimized for speed.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>get_local_members(Name) -> [Pid] | {error, Reason}</name>
+ <fsummary>Return all local processes in a group</fsummary>
+ <type>
+ <v>Name = term()</v>
+ <v>Pid = pid()</v>
+ <v>Reason = {no_such_group, Name}</v>
+ </type>
+ <desc>
+ <p>Returns all processes running on the local node in the
+ group <c>Name</c>. This function should to be used from
+ within a client function that accesses the group. It is therefore
+ optimized for speed.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>join(Name, Pid) -> ok | {error, Reason}</name>
+ <fsummary>Join a process to a group</fsummary>
+ <type>
+ <v>Name = term()</v>
+ <v>Pid = pid()</v>
+ <v>Reason = {no_such_group, Name}</v>
+ </type>
+ <desc>
+ <p>Joins the process <c>Pid</c> to the group <c>Name</c>.
+ A process can join a group several times; it must then
+ leave the group the same number of times.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>leave(Name, Pid) -> ok | {error, Reason}</name>
+ <fsummary>Make a process leave a group</fsummary>
+ <type>
+ <v>Name = term()</v>
+ <v>Pid = pid()</v>
+ <v>Reason = {no_such_group, Name}</v>
+ </type>
+ <desc>
+ <p>Makes the process <c>Pid</c> leave the group <c>Name</c>.
+ If the process is not a member of the group, <c>ok</c> is
+ returned.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>which_groups() -> [Name]</name>
+ <fsummary>Return a list of all known groups</fsummary>
+ <type>
+ <v>Name = term()</v>
+ </type>
+ <desc>
+ <p>Returns a list of all known groups.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>start()</name>
+ <name>start_link() -> {ok, Pid} | {error, Reason}</name>
+ <fsummary>Start the pg2 server</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Starts the pg2 server. Normally, the server does not need
+ to be started explicitly, as it is started dynamically if it
+ is needed. This is useful during development, but in a
+ target system the server should be started explicitly. Use
+ configuration parameters for <c>kernel</c> for this.
+ </p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>See Also</title>
+ <p><seealso marker="kernel_app">kernel(6)</seealso>,
+ <seealso marker="stdlib:pg">pg(3)</seealso></p>
+ </section>
+</erlref>
+