OTP Behavior: supervisor

supervisor
This is a pattern for an erlang process that watches other processes to ensure that they are running, etc.  Unlike gen_server, supervisor is all about the data structure that the callback module returns in response to the init/1 function.


Client API

• start(Module, Arguments)
• start(Name, Module, Arguments)
• start_link(Module, Arguments)
• start_link(Name, Module, Arguments)
• Calls the init/1 function in the supplied Module.
• Name is one of {local, <atom>} or {global, <atom>}
• start_link starts and links to the calling process, start does not.

Server API

• init(Arguments) -> 
      {ok, {SupervisorSpecification, ChildSpecification}}
• SupervisorSpecification has the form:
  { Strategy, AllowedRestarts, MaxSeconds }
• Strategy determines how crashed children are restarted.  Possible values for this are:
• one_for_one - if a child terminates, restart it
• one_for_all - if a child terminates terminate all the other children and then restart all of them.
• rest_for_one - if a child terminates, terminate all the children after it in the child specification then restart them.
• AllowedRestarts and MaxSeconds specify the maximum number of restarts that the server will allow during MaxSeconds seconds before giving up and terminating itself.
• ChildSpecification is a list of tuples of the form:
  { Id, {M,F,A}, Restart, Shutdown, Type, ModuleList }
• ID is an atom used to identify the process in the context of the supervisor.
• { Module, Function, Arguments } is used to start the child.
• Restart is one of
• transient - never restart the child
• temporary - restart only if the Reason for the terminate is not "normal"
• permanent - always restart
• Shutdown determines how long the supervisor will wait after calling the child's terminate function before unconditionally killing the child.  Possible values are:
• <integer> - the number of milliseconds to wait
• infinity - wait until the child returns.
• brutal_kill - immediately terminate the child without invoking the terminate callback
• Type is either supervisor or worker.  Its value does not seem to do anything.

Dynamic Children

Supervisors can also change the children that they manage dynamically.  This is basically just changing the list of child specifications at run time.  The corresponding functions are:

• supervisor:start_child(Supervisor, ChildSpec)
  Add a new child to the tree of processes.  Supervisor is either the name of the of the supervisor as provided in the start function or the PID of the supervisor process.
  
• supervisor:terminate_child(Supervisor, ChildId)
  Terminates the child.  I'm assuming that the usual restart process is suspended so that the supervisor will not restart the child unless supervisor:restart_child is called.
  
• supervisor:restart_child(Supervisor, ChildId)
  Restarts a child that was previously stopped with terminate_child.
  
• supervisor:delete_child(Supervisor, ChildId)
  This removes the child specification from the supervisor.  The child should have been terminated via terminate_child before calling this.

Next up: gen_fsm