Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
supervisor_bridge(3)	   Erlang Module Definition	  supervisor_bridge(3)

NAME
       supervisor_bridge - Generic supervisor bridge behavior.

DESCRIPTION
       This  behavior module provides a	supervisor bridge, a process that con-
       nects 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	super-
       visor, but has a	different interface than a real	supervisor to the sub-
       system. For more	information, see  Supervisor Behaviour in  OTP	Design
       Principles.

       A supervisor bridge assumes the functions for starting and stopping the
       subsystem to be located in a callback module exporting a	predefined set
       of functions.

       The sys(3) module can be	used for debugging a supervisor	bridge.

       Unless otherwise	stated,	all functions in this module fail if the spec-
       ified supervisor	bridge does not	exist or if bad	arguments  are	speci-
       fied.

EXPORTS
       start_link(Module, Args)	-> Result

       start_link(SupBridgeName, Module, Args) -> Result

	      Types:

		 SupBridgeName =
		     {local,  Name}  |	{global,  GlobalName}  | {via, Module,
		 ViaName}
		 Name =	atom()
		 GlobalName = ViaName =	term()
		 Module	= module()
		 Args =	term()
		 Result	= {ok, Pid} | ignore | {error, Error}
		 Error = {already_started, Pid}	| term()
		 Pid = pid()

	      Creates a	supervisor  bridge  process,  linked  to  the  calling
	      process,	which  calls  Module:init/1 to start the subsystem. To
	      ensure a synchronized startup procedure, this function does  not
	      return until Module:init/1 has returned.

		* If SupBridgeName={local,Name}, the supervisor	bridge is reg-
		  istered locally as Name using	register/2.

		* If SupBridgeName={global,GlobalName},	the supervisor	bridge
		  is  registered  globally  as	GlobalName using global:regis-
		  ter_name/2.

		* If SupBridgeName={via,Module,ViaName}, the supervisor	bridge
		  is  registered  as  ViaName  using a registry	represented by
		  Module. The Module callback is to  export  functions	regis-
		  ter_name/2,  unregister_name/1, and send/2, which are	to be-
		  have like  the  corresponding	 functions  in	global.	 Thus,
		  {via,global,GlobalName} is a valid reference.

	      If no name is provided, the supervisor bridge is not registered.

	      Module is	the name of the	callback module.

	      Args is an arbitrary term	that is	passed as the argument to Mod-
	      ule:init/1.

		* If the supervisor bridge and the subsystem are  successfully
		  started,  the	function returns {ok,Pid}, where Pid is	is the
		  pid of the supervisor	bridge.

		* If there already exists a process with  the  specified  Sup-
		  BridgeName,	  the	  function     returns	   {error,{al-
		  ready_started,Pid}}, where Pid is the	pid of that process.

		* If Module:init/1 returns ignore, this	function  returns  ig-
		  nore	as well	and the	supervisor bridge terminates with rea-
		  son normal.

		* If Module:init/1 fails or returns an error tuple or  an  in-
		  correct  value,  this	function returns {error,Errorr}, where
		  Error	is a term with information about the  error,  and  the
		  supervisor bridge terminates with reason Error.

CALLBACK FUNCTIONS
       The following functions must be exported	from a supervisor_bridge call-
       back module.

EXPORTS
       Module:init(Args) -> Result

	      Types:

		 Args =	term()
		 Result	= {ok,Pid,State} | ignore | {error,Error}
		  Pid =	pid()
		  State	= term()
		  Error	= term()

	      Whenever a supervisor bridge is  started	using  start_link/2,3,
	      this  function is	called by the new process to start the subsys-
	      tem and initialize.

	      Args is the Args argument	provided to the	start function.

	      The function is to return	{ok,Pid,State},	where Pid is  the  pid
	      of the main process in the subsystem and State is	any term.

	      If  later	 Pid  terminates  with a reason	Reason,	the supervisor
	      bridge terminates	with reason Reason as well. If later  the  su-
	      pervisor bridge is stopped by its	supervisor with	reason Reason,
	      it calls Module:terminate(Reason,State) to terminate.

	      If the initialization fails, the	function  is  to  return  {er-
	      ror,Error}, where	Error is any term, or ignore.

       Module:terminate(Reason,	State)

	      Types:

		 Reason	= shutdown | term()
		 State = term()

	      This  function  is  called  by  the supervisor bridge when it is
	      about to terminate. It is	to be the  opposite  of	 Module:init/1
	      and stop the subsystem and do any	necessary cleaning up. The re-
	      turn value is ignored.

	      Reason is	shutdown 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 Term, then Reason becomes Term.

	      State is taken from the return value of Module:init/1.

SEE ALSO
       supervisor(3), sys(3)

Ericsson AB			  stdlib 3.17		  supervisor_bridge(3)

NAME | DESCRIPTION | EXPORTS | CALLBACK FUNCTIONS | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=supervisor_bridge&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help