EVOLUTION-MANAGER

Edit File: supervisor_bridge.3

.TH supervisor_bridge 3 "stdlib 1.19.4" "Ericsson AB" "Erlang Module Definition" .SH NAME supervisor_bridge \- Generic Supervisor Bridge Behaviour. .SH DESCRIPTION .LP 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 \fIOTP Design Principles\fR\& for more information\&. .LP 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\&. .LP The \fIsys\fR\& module can be used for debugging a supervisor_bridge\&. .LP Unless otherwise stated, all functions in this module will fail if the specified supervisor_bridge does not exist or if bad arguments are given\&. .SH EXPORTS .LP .nf .B start_link(Module, Args) -> Result .br .fi .br .nf .B start_link(SupBridgeName, Module, Args) -> Result .br .fi .br .RS .LP Types: .RS 3 SupBridgeName = {local, Name} | {global, Name} .br Name = atom() .br Module = module() .br Args = term() .br Result = {ok, Pid} | ignore | {error, Error} .br Error = {already_started, Pid} | term() .br Pid = pid() .br .RE .RE .RS .LP Creates a supervisor_bridge process, linked to the calling process, which calls \fIModule:init/1\fR\& to start the subsystem\&. To ensure a synchronized start-up procedure, this function does not return until \fIModule:init/1\fR\& has returned\&. .LP If \fISupBridgeName={local,Name}\fR\& the supervisor_bridge is registered locally as \fIName\fR\& using \fIregister/2\fR\&\&. If \fISupBridgeName={global,Name}\fR\& the supervisor_bridge is registered globally as \fIName\fR\& using \fIglobal:register_name/2\fR\&\&. If \fISupBridgeName={via,Module,Name}\fR\& the supervisor_bridge is registered as \fIName\fR\& using a registry represented by Module\&. The \fIModule\fR\& callback should export the functions \fIregister_name/2\fR\&, \fIunregister_name/1\fR\& and \fIsend/2\fR\&, which should behave like the corresponding functions in \fIglobal\fR\&\&. Thus, \fI{via,global,GlobalName}\fR\& is a valid reference\&. If no name is provided, the supervisor_bridge is not registered\&. If there already exists a process with the specified \fISupBridgeName\fR\& the function returns \fI{error,{already_started,Pid}}\fR\&, where \fIPid\fR\& is the pid of that process\&. .LP \fIModule\fR\& is the name of the callback module\&. .LP \fIArgs\fR\& is an arbitrary term which is passed as the argument to \fIModule:init/1\fR\&\&. .LP If the supervisor_bridge and the subsystem are successfully started the function returns \fI{ok,Pid}\fR\&, where \fIPid\fR\& is is the pid of the supervisor_bridge\&. .LP If \fIModule:init/1\fR\& returns \fIignore\fR\&, this function returns \fIignore\fR\& as well and the supervisor_bridge terminates with reason \fInormal\fR\&\&. If \fIModule:init/1\fR\& fails or returns an error tuple or an incorrect value, this function returns \fI{error,Errorr}\fR\& where \fIError\fR\& is a term with information about the error, and the supervisor_bridge terminates with reason \fIError\fR\&\&. .RE .SH "CALLBACK FUNCTIONS" .LP The following functions should be exported from a \fIsupervisor_bridge\fR\& callback module\&. .SH EXPORTS .LP .B Module:init(Args) -> Result .br .RS .LP Types: .RS 3 Args = term() .br Result = {ok,Pid,State} | ignore | {error,Error} .br Pid = pid() .br State = term() .br Error = term() .br .RE .RE .RS .LP Whenever a supervisor_bridge is started using \fIsupervisor_bridge:start_link/2,3\fR\&, this function is called by the new process to start the subsystem and initialize\&. .LP \fIArgs\fR\& is the \fIArgs\fR\& argument provided to the start function\&. .LP The function should return \fI{ok,Pid,State}\fR\& where \fIPid\fR\& is the pid of the main process in the subsystem and \fIState\fR\& is any term\&. .LP If later \fIPid\fR\& terminates with a reason \fIReason\fR\&, the supervisor bridge will terminate with reason \fIReason\fR\& as well\&. If later the supervisor_bridge is stopped by its supervisor with reason \fIReason\fR\&, it will call \fIModule:terminate(Reason,State)\fR\& to terminate\&. .LP If something goes wrong during the initialization the function should return \fI{error,Error}\fR\& where \fIError\fR\& is any term, or \fIignore\fR\&\&. .RE .LP .B Module:terminate(Reason, State) .br .RS .LP Types: .RS 3 Reason = shutdown | term() .br State = term() .br .RE .RE .RS .LP This function is called by the supervisor_bridge when it is about to terminate\&. It should be the opposite of \fIModule:init/1\fR\& and stop the subsystem and do any necessary cleaning up\&. The return value is ignored\&. .LP \fIReason\fR\& is \fIshutdown\fR\& 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 \fITerm\fR\&, \fIReason\fR\& will be \fITerm\fR\&\&. .LP \fIState\fR\& is taken from the return value of \fIModule:init/1\fR\&\&. .RE .SH "SEE ALSO" .LP \fBsupervisor(3)\fR\&, \fBsys(3)\fR\&