supervisor_bridge(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

💫 supervisor_bridge (the Erlang module, bestie) 💫

okay so real quick, this is supervisor_bridge, an Erlang module definition, and it's literally the friendliest little glue layer in the whole stdlib. no cap.

✨ NAME ✨

supervisor_bridge — the Generic supervisor bridge behavior. she's a behavior, she's a bridge, she's iconic. 🎀

🌸 DESCRIPTION 🌸

Okay so picture this: this behavior module gives you a supervisor bridge, which is a process that connects a subsystem that was not built according to the OTP design principles to a supervision tree. the way that works — the supervisor bridge sits between a supervisor and the subsystem. so to its own supervisor it behaves like a real supervisor (main character energy, no notes), but to the subsystem it has a totally different interface than a real supervisor would. for more info, see Supervisor Behaviour in OTP Design Principles. 💅

A supervisor bridge assumes the functions for starting and stopping the subsystem live in a callback module that exports a predefined set of functions. yes, predefined. you don't get to freestyle it. 🙈

The sys module can be used for debugging a supervisor bridge. literally your bestie when things get weird. 🦋

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

See Also

supervisor, sys

🔥 FUNCTIONS 🔥

when
    Module :: module(),
    Args :: term(),
    Result :: {ok, Pid} | ignore | {error, Error},
    Error :: {already_started, Pid} | term(),
    Pid :: pid().

Creates a nameless supervisor bridge process as part of a supervision tree. she's mysterious, she's unnamed, she's serving. 👑

Equivalent to start_link/3 except that the supervisor process is not registered.

when
    SupBridgeName ::
        {local, Name} |
        {global, GlobalName} |
        {via, Module, ViaName},
    Name :: atom(),
    GlobalName :: term(),
    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. okay bestie this is the one with the whole menu of registration options, stay with me. ✨

To ensure a synchronized startup procedure, this function does not return until Module:init/1 has returned. no cutting the line, we wait our turn. ⏳

  • 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. (yes, that combo is legal bestie, go off)

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. (yes the original says "is is", we're not fixing it, we're honoring it 💖)
  • 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. name already taken bestie, pick another 💀
  • If Module:init/1 returns ignore, this function returns ignore as well and the supervisor bridge terminates with reason normal. okay she simply left, no drama. 🍓
  • 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. full on meltdown, but organized. 😭

🦋 CALLBACKS 🦋

init(Args)

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. give us the whole trio, don't be shy. 🎀

If later Pid terminates with a reason Reason, the supervisor bridge terminates with reason Reason as well. so like, one falls, they both fall. ride or die. 💜 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.

terminate(Reason, State)

This function is called by the supervisor bridge when it is about to terminate. she's wrapping up, saying her goodbyes, closing the group chat. 🫶 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. so don't stress about it bestie, nobody's reading that. 💅

Reason is shutdown if the supervisor bridge is terminated by its supervisor. If the supervisor bridge terminates because a linked process (apart from the main process of the subsystem) has terminated with reason Term, then Reason becomes Term. iykyk — that "apart from the main process of the subsystem" part is doing a LOT of work. don't skip it.

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

quick vibe check: everything above fails if the supervisor bridge doesn't exist or if the arguments are bad. not a maybe, not a sometimes. just fails. that's the rule, periodt. ✨

and that's the whole page!! brought to you by the lovely people at Ericsson AB, fresh from stdlib 8.0.4 — mwah, thanks for the manual, we ate 💅💖✨

📦 where this page comes from