The R13B03 release.OTP_R13B03

1 files changed, 162 insertions, 0 deletions

diff --git a/lib/stdlib/doc/src/supervisor_bridge.xml b/lib/stdlib/doc/src/supervisor_bridge.xml
new file mode 100644
index 0000000000..b334f57caf
--- /dev/null
+++ b/lib/stdlib/doc/src/supervisor_bridge.xml
@@ -0,0 +1,162 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1996</year>
+      <year>2007</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.
+
+  The Initial Developer of the Original Code is Ericsson AB.
+    </legalnotice>
+
+    <title>supervisor_bridge</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>supervisor_bridge</module>
+  <modulesummary>Generic Supervisor Bridge Behaviour.</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
+      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
+      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>
+  </description>
+  <funcs>
+    <func>
+      <name>start_link(Module, Args) -> Result</name>
+      <name>start_link(SupBridgeName, Module, Args) -> Result</name>
+      <fsummary>Create a supervisor bridge process.</fsummary>
+      <type>
+        <v>SupBridgeName = {local,Name} | {global,Name}</v>
+        <v>&nbsp;Name = atom()</v>
+        <v>Module = atom()</v>
+        <v>Args = term()</v>
+        <v>Result = {ok,Pid} | ignore | {error,Error}</v>
+        <v>&nbsp;Pid = pid()</v>
+        <v>&nbsp;Error = {already_started,Pid} | term()</v>
+      </type>
+      <desc>
+        <p>Creates a supervisor_bridge process, linked to the calling
+          process, which calls <c>Module:init/1</c> to start the subsystem.
+          To ensure a synchronized start-up procedure, this function does
+          not return until <c>Module:init/1</c> has returned.</p>
+        <p>If <c>SupBridgeName={local,Name}</c> the supervisor_bridge is
+          registered locally as <c>Name</c> using <c>register/2</c>.
+          If <c>SupBridgeName={global,Name}</c> the supervisor_bridge is
+          registered globally as <c>Name</c> using
+          <c>global:register_name/2</c>.
+          If no name is provided, the supervisor_bridge is not registered.
+          If there already exists a process with the specified
+          <c>SupBridgeName</c> the function returns
+          <c>{error,{already_started,Pid}}</c>, where <c>Pid</c> is the pid
+          of that process.</p>
+        <p><c>Module</c> is the name of the callback module.</p>
+        <p><c>Args</c> is an arbitrary term which is passed as the argument
+          to <c>Module:init/1</c>.</p>
+        <p>If the supervisor_bridge and the subsystem are successfully
+          started the function returns <c>{ok,Pid}</c>, where <c>Pid</c> is
+          is the pid of the supervisor_bridge.</p>
+        <p>If <c>Module: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>Module:init/1</c> fails or returns an error tuple or an
+          incorrect value, this function returns <c>{error,Term}</c> where
+          <c>Term</c> is a term with information about the error, and
+          the supervisor_bridge terminates with reason <c>Term</c>.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>CALLBACK FUNCTIONS</title>
+    <p>The following functions should be exported from a
+      <c>supervisor_bridge</c> callback module.</p>
+  </section>
+  <funcs>
+    <func>
+      <name>Module:init(Args) -> Result</name>
+      <fsummary>Initialize process and start subsystem.</fsummary>
+      <type>
+        <v>Args = term()</v>
+        <v>Result = {ok,Pid,State} | ignore | {error,Error}</v>
+        <v>&nbsp;Pid = pid()</v>
+        <v>&nbsp;State = term()</v>
+        <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
+          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>
+          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
+          <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>
+      </desc>
+    </func>
+    <func>
+      <name>Module:terminate(Reason, State)</name>
+      <fsummary>Clean up and stop subsystem.</fsummary>
+      <type>
+        <v>Reason = shutdown | term()</v>
+        <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>
+          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
+          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>
+        <p><c>State</c> is taken from the return value of
+          <c>Module:init/1</c>.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p><seealso marker="supervisor">supervisor(3)</seealso>, 
+      <seealso marker="sys">sys(3)</seealso></p>
+  </section>
+</erlref>
+