---
name: "supervisor_bridge"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/supervisor_bridge"
---

# supervisor\_bridge(3erl)

Generic supervisor bridge behavior.

## NAME

supervisor\_bridge - Generic supervisor bridge behavior.

## DESCRIPTION

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. 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(3erl)](/sys/3erl.md)* module can be used for debugging a supervisor bridge.

Unless otherwise stated, all functions in this module fail if the specified supervisor bridge does not exist or if bad arguments are specified.

## 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 registered locally as *Name* using *register/2*.

- \*

  If *SupBridgeName={global,GlobalName}*, the supervisor bridge is registered globally as *GlobalName* using *global:register\_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 *register\_name/2*, *unregister\_name/1*, and *send/2*, which are to behave 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 *Module: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 *SupBridgeName*, the function returns *{error,{already\_started,Pid}}*, where *Pid* is the pid of that process.

- \*

  If *Module:init/1* returns *ignore*, this function returns *ignore* as well and the supervisor bridge terminates with reason *normal*.

- \*

  If *Module:init/1* fails or returns an error tuple or an incorrect value, this function returns *{error,Error}*, 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* callback 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 subsystem 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 supervisor 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 *{error,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 return 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(3erl)](/supervisor/3erl.md)*, *[sys(3erl)](/sys/3erl.md)*