diff options
Diffstat (limited to 'lib/stdlib/doc/src/supervisor_bridge.xml')
| -rw-r--r-- | lib/stdlib/doc/src/supervisor_bridge.xml | 164 |
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> 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> |