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
usually, use the methods of the service class Methods of services instead.
providesis 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.
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.
runningis 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
startslot. It will also be passed as an argument to the procedure in the
stopslot. 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
runningslot 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
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
stopmethod 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.
startcontains 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
runningslot. The default value is a procedure that returns
#tand performs no further actions, therefore it is desirable to specify a different one usually.
stopis, similar to
start, a slot containing a procedure. But in this case, it gets the current value of the
runningslot 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
runningslot, so that it should return
#fif it is now possible again to start the service at a later point. The default value is a procedure that returns
#fand performs no further actions.
handle-terminationslot contains the procedure to call when the process associated with a service—the process whose PID appears in the
runningslot—terminates. It is passed the service and its exit status, an integer as returned by
waitpidin GNU Guile Reference Manual).
The default handler is the
procedure, which respawns the service if applicable.
actionsspecifies the additional actions that can be performed on a service when it is running. A typical example for this is the
restartaction. The macro
make-actionsService 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
#tby default. When the value becomes
#fat some point, this will prevent the service from getting started. A service can be enabled and disabled with the methods
disable, respectively Methods of services.
last-respawnscannot be initialized with a keyword and is only ever used when the
#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
stopslot to be unused; instead, stopping the service will just cause the
waiting-for-termination?slot be set to
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.
#tif 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.
replacementspecifies a service to be used to replace this one when it is stopped. This service will continue to function normally until the
stopaction 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