otplike.supervisor — otplike 0.6.0-alpha

Provides a supervisor, a process that supervises other processes called child processes.

A child process can either be another supervisor or a worker process. Worker processes are normally implemented using gen_server behavior. Supervisors are used to build a hierarchical process structure called a supervision tree, a nice way to structure a fault-tolerant application. For more information, see Supervisor Behaviour in OTP Design Principles.

A supervisor expects the definition of which child processes to supervise to be specified in the return value of a supervisor's function.

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

Supervision Principles

The supervisor is responsible for starting, stopping, and monitoring its child processes. The basic idea of a supervisor is that it must keep its child processes alive by restarting them when necessary.

The children of a supervisor are defined as a list of child specifications. When the supervisor is started, the child processes are started in order from left to right according to this list. When the supervisor terminates, it first terminates its child processes in reversed start order, from right to left.

The supervisor properties are defined by the supervisor flags. The spec definition for the supervisor flags is as follows:

(spec/def ::intensity nat-int?)
(spec/def ::period pos-int?)
(spec/def ::strategy
  #{:one-for-all
    :one-for-one
    :rest-for-one})

(spec/def ::sup-flags
(spec/keys
  :opt-un [::strategy
           ::intensity
           ::period]))

A supervisor can have one of the following restart strategies specified with the strategy key in the above map:

:one-for-one - If one child process terminates and is to be restarted, only that child process is affected. This is the default restart strategy.

:one-for-all - If one child process terminates and is to be restarted, all other child processes are terminated and then all child processes are restarted.

:rest-for-one - If one child process terminates and is to be restarted, the 'rest' of the child processes (that is, the child processes after the terminated child process in the start order) are terminated. Then the terminated child process and all child processes after it are restarted.

To prevent a supervisor from getting into an infinite loop of child process terminations and restarts, a maximum restart intensity is defined using two integer values specified with keys :intensity and :period in the above map. Assuming the values max-r for :intensity and max-t for :period, then, if more than max-r restarts occur within max-t seconds, the supervisor terminates all child processes and then itself. The termination reason for the supervisor itself in that case will be :shutdown. intensity defaults to 1 and period defaults to 5.

The spec definition of a child specification is as follows:

(spec/def ::timeout (spec/or :ms nat-int? :inf #{:infinity}))
(spec/def ::args (spec/coll-of any?))

(spec/def ::id any?)
(spec/def ::start (spec/tuple fn? ::args))
(spec/def ::restart #{:permanent :transient :temporary})
(spec/def ::shutdown
(spec/or :brutal-kill #{:brutal-kill}
         :timeout ::timeout))
(spec/def ::type #{:worker :supervisor})

(spec/def ::child-spec
(spec/keys
  :req-un [::id
           ::start]
  :opt-un [::restart
           ::shutdown
           ::type]))

:id is used to identify the child specification internally by the supervisor.

:start defines the function call used to start the child process. It must be a function-arguments tuple [f args] used as (apply f args).

The start function must create a child process and link to it, and must return [:ok child-pid] or [:ok child-pid info], where info is any value that is ignored by the supervisor. The function is allowed to return async value wrapping the actual return.

If something goes wrong, the function can also return an error tuple [:error error].

Notice that the gen-server/start-link functions fulfill the above requirements.

:restart defines when a terminated child process must be restarted. A :permanent child process is always restarted. A :temporary child process is never restarted (even when the supervisor's restart strategy is :rest-for-one or one-for-all and a sibling's death causes the temporary process to be terminated). A :transient child process is restarted only if it terminates abnormally, that is, with another exit reason than :normal, :shutdown, or [:shutdown reason]. The :restart key is optional and defaults to :permanent.

:shutdown defines how a child process must be terminated. :brutal-kill means that the child process is unconditionally terminated using (process/exit child-pid :kill). An integer time-out value means that the supervisor tells the child process to terminate by calling (process/exit child-pid :shutdown) and then wait for an exit signal with reason :shutdown back from the child process. If no exit signal is received within the specified number of milliseconds, the child process is unconditionally terminated using (process/exit child-id :kill).

If the child process is another supervisor, the shutdown time is to be set to :infinity to give the subtree ample time to shut down. It is also allowed to set it to :infinity, if the child process is a worker.

Warning! Be careful when setting the shutdown time to :infinity when the child process is a worker. Because, in this situation, the termination of the supervision tree depends on the child process, it must be implemented in a safe way and its cleanup procedure must always return.

Notice that all child processes implemented using the standard behaviors (gen-server) automatically adhere to the shutdown protocol.

The :shutdown key is optional. If it is not specified, it defaults to 5000 if the child is of type :worker and it defaults to :infinity if the child is of type :supervisor.

:type specifies if the child process is a supervisor or a worker. The :type key is optional and defaults to :worker.

check-child-specs clj

(check-child-specs spec)

Takes a list of child specification and returns :ok if all of them are syntactically correct, otherwise [error, reason].

delete-child clj

(delete-child sup id)

The same as delete-child! but returns async value.

delete-child! clj macro

(delete-child! sup id)

Tells supervisor to delete the child specification identified by id. The corresponding child process must not be running. Use terminate-child to terminate it.

If successful, the function returns :ok. If the child specification identified by id exists but the corresponding child process is running or is about to be restarted, the function returns [:error :running] or [:error :restarting], respectively. If the child specification identified by id does not exist, the function returns [:error :not-found].

restart-child clj

(restart-child sup id)

The same as restart-child! but returns async value.

restart-child! clj macro

(restart-child! sup id)

Tells supervisor to restart a child process corresponding to the child specification identified by id. The child specification must exist, and the corresponding child process must not be running.

Notice that for temporary children, the child specification is automatically deleted when the child terminates; thus, it is not possible to restart such children.

If the child specification identified by id does not exist, the function returns [:error :not-found]. If the child specification exists but the corresponding process is already running, the function returns [:error :running].

If the child process start function returns [:ok pid], the pid is added to the supervisor and the function returns the same value.

If the child process start function returns an error tuple or an erroneous value, or if it fails, the function returns [:error error], where error is a form containing information about the error.

start-child clj

(start-child sup child-spec)

The same as start-child! but returns async value.

start-child! clj macro

(start-child! sup child-spec)

Dynamically adds a child specification to supervisor sup, which starts the corresponding child process.

sup can be a pid or a registered name.

child-spec must be a valid child specification. The child process is started by using the start function as defined in the child specification.

If there already exists a child specification with the specified identifier, child-spec is discarded, and the function returns [:error :already-present] or [:error [:already-started child]], depending on if the corresponding child process is running or not.

If the child process start function returns [:ok child-pid], the child specification and pid are added to the supervisor and the function returns the same value.

If the child process start function returns an error tuple or an erroneous value, or if it fails, the child specification is discarded, and the function returns [:error error], where error is a form containing information about the error and child specification.

start-link clj

(start-link sup-fn)

(start-link sup-fn args)

(start-link sup-name sup-fn args)

The same as start-link! but returns async value.

start-link! clj macro

(start-link! sup-fn)

(start-link! sup-fn args)

(start-link! sup-name sup-fn args)

Creates a supervisor process as part of a supervision tree. For example, the function ensures that the supervisor is linked to the calling process (its supervisor).

The created supervisor process calls sup-fn to find out about restart strategy, maximum restart intensity, and child processes. To ensure a synchronized startup procedure, start-link! does not return until sup-fn has returned and all child processes have been started. sup-fn is allowed to return async value wrapping the actual return.

If sup-name is provided, the supervisor is registered locally as sup-name.

args is a vector of the arguments to sup-fn.

If the supervisor and its child processes are successfully created (that is, if all child process start functions return [ok, child-pid]), the function returns [ok, pid], where pid is the pid of the supervisor.

If there already exists a process with the specified sup-name, the function retunrs [:error reason].

If sup-fn fails or returns an incorrect value, this function returns [:error ([:bad-return-value 'init ret] :as reason)] , where ret is the returned value, and the supervisor terminates with the same reason.

If any child process start function fails or returns an error tuple or an erroneous value, the supervisor first terminates all already started child processes with reason :shutdown and then terminate itself and returns [:error, [:shutdown reason]].

terminate-child clj

(terminate-child sup id)

The same as terminate-child! but returns async value.

terminate-child! clj macro

(terminate-child! sup id)

Tells supervisor to terminate the specified child.

id must be the child specification identifier. The process, if any, is terminated and, unless it is a temporary child, the child specification is kept by the supervisor. The child process can later be restarted by the supervisor. The child process can also be restarted explicitly by calling restart-child. Use delete-child to remove the child specification.

If the child is temporary, the child specification is deleted as soon as the process terminates. This means that delete-child has no meaning and restart-child cannot be used for these children.

If successful, the function returns :ok. If there is no child specification with the specified id, the function returns [:error :not-found].