A service has the following slots, all of which can be initialized
with a keyword (i.e. #:provides, used when creating the object)
of the same name, except where stated otherwise. You should not
access them directly with slot-ref or slot-set!
usually, use the methods of the service class Methods of services instead.
provides is a list of symbols that are provided by the service.
A symbol can only be provided by one service running at a time,
i.e. if two services provide the same symbol, only one of them can
run, starting the other one will fail. Therefore, these symbols are
mainly used to denote conflicting services. The first symbol in the
list is the canonical name for the service, thus it must be unique.
This slot has no default value and must therefore be initialized.
requires is, like provides, a list of symbols that
specify services. In this case, they name what this service depends
on, i.e. before the service can be started, services that provide
those symbols must be started. If a required symbol is provided by
several services, one will be started. By default, this slot
contains the empty list.
running is a hook that can be used by each service in its own
way. The default value is #f, which indicates that the service
is not running. When an attempt is made to start the service, it will
be set to the return value of the procedure in the start slot.
It will also be passed as an argument to the procedure in the
stop slot. If it is set a value that is an integer, it is
assumed to be a process id, and shepherd will monitor the process for
unexpected exits. If it is a procedure, that procedure is called to get
at the underlying value. This slot cannot be initialized with a keyword.
respawn? specifies whether the service should be respawned by
the Shepherd. If this slot has the value #t, then assume the
running slot specifies a child process PID and restart the
service if that process terminates. Otherwise this slot is #f,
which is the default. See also the last-respawns slot.
one-shot? slot determines whether the service is a one-shot
service. A one-shot service is a service that, as soon as it has been
successfully started, is marked as “stopped.” Other services can
nonetheless require one-shot services. One-shot services are useful to
trigger an action before other services are started, such as a cleanup or an
initialization action.
As for other services, the start method of a one-shot service must
return a truth value to indicate success, and false to indicate failure.
transient? slot determines whether the service is a
transient service. A transient service is automatically
unregistered when it terminates, be it because its stop method is
called or because its associated process terminates.
This is useful in the uncommon case of synthesized services that may not be restarted once they have completed.
start contains the “constructor” for the service, which will
be called to start the service. (Therefore, it is not a constructor
in the sense that it initializes the slots of a <service>
object.) This must be a procedure that accepts any amount of
arguments, which will be the additional arguments supplied by the
user. If the starting attempt failed, it must return #f. The
value will be stored in the running slot. The default value is
a procedure that returns #t and performs no further actions,
therefore it is desirable to specify a different one usually.
stop is, similar to start, a slot containing a
procedure. But in this case, it gets the current value of the
running slot as first argument and the user-supplied arguments
as further arguments; it gets called to stop the service. Its return
value will again be stored in the running slot, so that it
should return #f if it is now possible again to start the
service at a later point. The default value is a procedure that
returns #f and performs no further actions.
handle-termination slot contains the procedure to call when
the process associated with a service—the process whose PID appears in
the running slot—terminates. It is passed the service and its
exit status, an integer as returned by waitpid (see waitpid in GNU Guile Reference Manual).
The default handler is the default-service-termination-handler
procedure, which respawns the service if applicable.
actions specifies the additional actions that can be performed
on a service when it is running. A typical example for this is the
restart action. The macro make-actions Service Convenience is provided to abstract the actual data representation
format for this slot. (It actually is a hash currently.)
enabled? cannot be initialized with a keyword, and contains
#t by default. When the value becomes #f at some point,
this will prevent the service from getting started. A service can be
enabled and disabled with the methods enable and
disable, respectively Methods of services.
last-respawns cannot be initialized with a keyword and is only
ever used when the respawn? slot contains #t; it is a
circular list with (car respawn-limit) elements, where each
element contains the time when it was restarted, initially all 0,
later a time in seconds since the Epoch. The first element is the one
that contains the oldest one, the last one the newest.
stop-delay? being false causes the stop slot to be
unused; instead, stopping the service will just cause the
waiting-for-termination? slot be set to #t.
waiting-for-termination? cannot be initialized with a keyword
and should not be used by others, it is only used internally for
respawnable services when the stop-delay? slot contains a true
value. waiting-for-termination? contains #t if the
service is still running, but the user requested that it be stopped,
in which case if the service terminates the next time, the respawn
handler will not start it again.
otherwise #f.
replacement specifies a service to be used to replace this one
when it is stopped. This service will continue to function normally
until the stop action is invoked. After the service has been
successfully stopped, its definition will be replaced by the value of
this slot, which must itself be a service. This slot is ignored if
its value is #f.