<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>1996</year>
      <year>2011</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 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
          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>
        <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>
      </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>

