aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc/src/supervisor_bridge.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc/src/supervisor_bridge.xml')
-rw-r--r--lib/stdlib/doc/src/supervisor_bridge.xml164
1 files changed, 99 insertions, 65 deletions
diff --git a/lib/stdlib/doc/src/supervisor_bridge.xml b/lib/stdlib/doc/src/supervisor_bridge.xml
index e40c8bbd6f..c4c1b37548 100644
--- a/lib/stdlib/doc/src/supervisor_bridge.xml
+++ b/lib/stdlib/doc/src/supervisor_bridge.xml
@@ -31,73 +31,106 @@
<rev></rev>
</header>
<module>supervisor_bridge</module>
- <modulesummary>Generic Supervisor Bridge Behaviour.</modulesummary>
+ <modulesummary>Generic supervisor bridge behavior.</modulesummary>
<description>
- <p>A behaviour module for implementing a supervisor_bridge, a process
- which connects a subsystem not designed according to the OTP design
- principles to a supervision tree. The supervisor_bridge sits between
+ <p>This behavior module provides a supervisor bridge, a process
+ that connects a subsystem not designed according to the OTP design
+ principles to a supervision tree. The supervisor bridge sits between
a supervisor and the subsystem. It behaves like a real supervisor to
its own supervisor, but has a different interface than a real
- supervisor to the subsystem. Refer to <em>OTP Design Principles</em>
- for more information.</p>
- <p>A supervisor_bridge assumes the functions for starting and stopping
+ supervisor to the subsystem. For more information, see
+ <seealso marker="doc/design_principles:sup_princ">
+ Supervisor Behaviour</seealso> in OTP Design Principles.
+ </p>
+
+ <p>A supervisor bridge assumes the functions for starting and stopping
the subsystem to be located in a callback module exporting a
- pre-defined set of functions.</p>
- <p>The <c>sys</c> module can be used for debugging a
- supervisor_bridge.</p>
- <p>Unless otherwise stated, all functions in this module will fail if
- the specified supervisor_bridge does not exist or if bad arguments are
- given.</p>
+ predefined set of functions.</p>
+
+ <p>The <seealso marker="sys"><c>sys(3)</c></seealso> module can be used
+ for debugging a supervisor bridge.</p>
+
+ <p>Unless otherwise stated, all functions in this module fail if
+ the specified supervisor bridge does not exist or if bad arguments are
+ specified.</p>
</description>
+
<funcs>
<func>
<name name="start_link" arity="2"/>
<name name="start_link" arity="3"/>
<fsummary>Create a supervisor bridge process.</fsummary>
<desc>
- <p>Creates a supervisor_bridge process, linked to the calling
- process, which calls <c><anno>Module</anno>:init/1</c> to start the subsystem.
- To ensure a synchronized start-up procedure, this function does
+ <p>Creates a supervisor bridge process, linked to the calling process,
+ which calls <c><anno>Module</anno>:init/1</c> to start the subsystem.
+ To ensure a synchronized startup procedure, this function does
not return until <c><anno>Module</anno>:init/1</c> has returned.</p>
- <p>If <c><anno>SupBridgeName</anno>={local,<anno>Name</anno>}</c> the supervisor_bridge is
- registered locally as <c><anno>Name</anno></c> using <c>register/2</c>.
- If <c><anno>SupBridgeName</anno>={global,<anno>Name</anno>}</c> the supervisor_bridge is
- registered globally as <c><anno>Name</anno></c> using
- <c>global:register_name/2</c>.
- If <c><anno>SupBridgeName</anno>={via,<anno>Module</anno>,<anno>Name</anno>}</c> the supervisor_bridge is
- registered as <c><anno>Name</anno></c> using a registry represented
- by <anno>Module</anno>. The <c>Module</c> callback should export
- the functions <c>register_name/2</c>, <c>unregister_name/1</c>
- and <c>send/2</c>, which should behave like the
- corresponding functions in <c>global</c>. Thus,
- <c>{via,global,GlobalName}</c> is a valid reference.
- If no name is provided, the supervisor_bridge is not registered.
- If there already exists a process with the specified
- <c><anno>SupBridgeName</anno></c> the function returns
- <c>{error,{already_started,<anno>Pid</anno>}}</c>, where <c><anno>Pid</anno></c> is the pid
- of that process.</p>
+ <list type="bulleted">
+ <item>
+ <p>If <c><anno>SupBridgeName</anno>={local,<anno>Name</anno>}</c>,
+ the supervisor bridge is registered locally as
+ <c><anno>Name</anno></c> using <c>register/2</c>.</p>
+ </item>
+ <item>
+ <p>If <c><anno>SupBridgeName</anno>={global,<anno>Name</anno>}</c>,
+ the supervisor bridge is registered globally as
+ <c><anno>Name</anno></c> using
+ <seealso marker="kernel:global#register_name/2">
+ <c>global:register_name/2</c></seealso>.</p>
+ </item>
+ <item>
+ <p>If
+ <c><anno>SupBridgeName</anno>={via,<anno>Module</anno>,<anno>Name</anno>}</c>,
+ the supervisor bridge is registered as <c><anno>Name</anno></c>
+ using a registry represented by <anno>Module</anno>. The
+ <c>Module</c> callback is to export functions
+ <c>register_name/2</c>, <c>unregister_name/1</c>, and <c>send/2</c>,
+ which are to behave like the corresponding functions in
+ <seealso marker="kernel:global"><c>global</c></seealso>.
+ Thus, <c>{via,global,GlobalName}</c> is a valid reference.</p>
+ </item>
+ </list>
+ <p>If no name is provided, the supervisor bridge is not registered.</p>
<p><c><anno>Module</anno></c> is the name of the callback module.</p>
- <p><c><anno>Args</anno></c> is an arbitrary term which is passed as the argument
- to <c><anno>Module</anno>:init/1</c>.</p>
- <p>If the supervisor_bridge and the subsystem are successfully
- started the function returns <c>{ok,<anno>Pid</anno>}</c>, where <c><anno>Pid</anno></c> is
- is the pid of the supervisor_bridge.</p>
- <p>If <c><anno>Module</anno>:init/1</c> returns <c>ignore</c>, this function
- returns <c>ignore</c> as well and the supervisor_bridge terminates
- with reason <c>normal</c>.
- If <c><anno>Module</anno>:init/1</c> fails or returns an error tuple or an
- incorrect value, this function returns <c>{error,<anno>Error</anno>r}</c> where
- <c><anno>Error</anno></c> is a term with information about the error, and
- the supervisor_bridge terminates with reason <c><anno>Error</anno></c>.</p>
+ <p><c><anno>Args</anno></c> is an arbitrary term that is passed as the
+ argument to <c><anno>Module</anno>:init/1</c>.</p>
+ <list type="bulleted">
+ <item>
+ <p>If the supervisor bridge and the subsystem are successfully
+ started, the function returns <c>{ok,<anno>Pid</anno>}</c>, where
+ <c><anno>Pid</anno></c> is is the pid of the supervisor
+ bridge.</p>
+ </item>
+ <item>
+ <p>If there already exists a process with the specified
+ <c><anno>SupBridgeName</anno></c>, the function returns
+ <c>{error,{already_started,<anno>Pid</anno>}}</c>, where
+ <c><anno>Pid</anno></c> is the pid of that process.</p>
+ </item>
+ <item>
+ <p>If <c><anno>Module</anno>:init/1</c> returns <c>ignore</c>, this
+ function returns <c>ignore</c> as well and the supervisor bridge
+ terminates with reason <c>normal</c>.</p>
+ </item>
+ <item>
+ <p>If <c><anno>Module</anno>:init/1</c> fails or returns an error
+ tuple or an incorrect value, this function returns
+ <c>{error,<anno>Error</anno>r}</c>, where
+ <c><anno>Error</anno></c> is a term with information about the
+ error, and the supervisor bridge
+ terminates with reason <c><anno>Error</anno></c>.</p>
+ </item>
+ </list>
</desc>
</func>
</funcs>
<section>
- <title>CALLBACK FUNCTIONS</title>
- <p>The following functions should be exported from a
+ <title>Callback Functions</title>
+ <p>The following functions must be exported from a
<c>supervisor_bridge</c> callback module.</p>
</section>
+
<funcs>
<func>
<name>Module:init(Args) -> Result</name>
@@ -110,25 +143,26 @@
<v>&nbsp;Error = term()</v>
</type>
<desc>
- <p>Whenever a supervisor_bridge is started using
- <c>supervisor_bridge:start_link/2,3</c>, this function is called
+ <p>Whenever a supervisor bridge is started using
+ <seealso marker="#start_link/2"><c>start_link/2,3</c></seealso>,
+ this function is called
by the new process to start the subsystem and initialize.</p>
<p><c>Args</c> is the <c>Args</c> argument provided to the start
function.</p>
- <p>The function should return <c>{ok,Pid,State}</c> where <c>Pid</c>
+ <p>The function is to return <c>{ok,Pid,State}</c>, where <c>Pid</c>
is the pid of the main process in the subsystem and <c>State</c>
is any term.</p>
<p>If later <c>Pid</c> terminates with a reason <c>Reason</c>,
- the supervisor bridge will terminate with reason <c>Reason</c> as
- well.
- If later the supervisor_bridge is stopped by its supervisor with
- reason <c>Reason</c>, it will call
+ the supervisor bridge terminates with reason <c>Reason</c> as well.
+ If later the supervisor bridge is stopped by its supervisor with
+ reason <c>Reason</c>, it calls
<c>Module:terminate(Reason,State)</c> to terminate.</p>
- <p>If something goes wrong during the initialization the function
- should return <c>{error,Error}</c> where <c>Error</c> is any
- term, or <c>ignore</c>.</p>
+ <p>If the initialization fails, the function is to return
+ <c>{error,Error}</c>, where <c>Error</c> is any term,
+ or <c>ignore</c>.</p>
</desc>
</func>
+
<func>
<name>Module:terminate(Reason, State)</name>
<fsummary>Clean up and stop subsystem.</fsummary>
@@ -137,15 +171,15 @@
<v>State = term()</v>
</type>
<desc>
- <p>This function is called by the supervisor_bridge when it is about
- to terminate. It should be the opposite of <c>Module:init/1</c>
+ <p>This function is called by the supervisor bridge when it is about
+ to terminate. It is to be the opposite of <c>Module:init/1</c>
and stop the subsystem and do any necessary cleaning up.
The return value is ignored.</p>
- <p><c>Reason</c> is <c>shutdown</c> if the supervisor_bridge is
- terminated by its supervisor. If the supervisor_bridge terminates
+ <p><c>Reason</c> is <c>shutdown</c> if the supervisor bridge is
+ terminated by its supervisor. If the supervisor bridge terminates
because a a linked process (apart from the main process of
the subsystem) has terminated with reason <c>Term</c>,
- <c>Reason</c> will be <c>Term</c>.</p>
+ then <c>Reason</c> becomes <c>Term</c>.</p>
<p><c>State</c> is taken from the return value of
<c>Module:init/1</c>.</p>
</desc>
@@ -153,9 +187,9 @@
</funcs>
<section>
- <title>SEE ALSO</title>
- <p><seealso marker="supervisor">supervisor(3)</seealso>,
- <seealso marker="sys">sys(3)</seealso></p>
+ <title>See Also</title>
+ <p><seealso marker="supervisor"><c>supervisor(3)</c></seealso>,
+ <seealso marker="sys"><c>sys(3)</c></seealso></p>
</section>
</erlref>