What we have seen so far is the interface to define a service and
to access it (see Defining Services). The procedures below, also
exported by the (shepherd service) module, let you modify and
access the state of a service. You may use them in your configuration
file, for instance to start some or all of the services you defined
(see Service Examples).
Under the hood, each service record has an associated fiber (really: an actor) that encapsulates its state and serves user requests—a fiber is a lightweight execution thread (see Service Internals).
The procedures below let you change the state of a service.
Start service and its dependencies, passing args to its
start method. Return its running value, #f on failure.
Stop service and any service that depends on it. Return the list of services that have been stopped (including transitive dependent services).
If service is not running, print a warning and return its canonical name in a list.
Perform the-action (a symbol such as 'restart or 'status)
on service, passing it args. The meaning of args depends on
the action.
The start-in-the-background procedure, described below, is
provided for your convenience: it makes it easy to start a set of
services right from your configuration file, while letting
shepherd run in the background.
Start the services named by services, a list of symbols, in the background. In other words, this procedure returns immediately without waiting until all of services have been started.
This procedure can be useful in a configuration file because it lets you
interact right away with shepherd using the herd command.
The following procedures let you query the current state of a service.
Return true if service is currently running/stopped/enabled, false otherwise.
Return the status of service as a symbol, one of: 'stopped,
'starting, 'running, or 'stopping.
Return the current “running value” of service—a Scheme value
associated with it. It is #f when the service is stopped;
otherwise, it is a truth value, such as an integer denoting a PID
(see Service De- and Constructors).
Return the list of symbol/timestamp pairs representing recent state changes for service.
Return the list of startup failure times or respawn times of service.
Return the list of last exit statuses of service’s main process (most recent first).
Return the replacement of service, or #f if there is
none.
The replacement is the service that will replace service when it is eventually stopped.
Return a list of messages recently logged by service—typically lines written by a daemon on standard output. Each element of the list is a timestamp/string pair where the timestamp is the number of seconds since January 1st, 1970 (an integer).
Return the file where messages by service are logged, or #f
if there is no such file, for instance because service’s output is
logged by some mechanism not under shepherd’s control.
See Service Internals, if you’re curious about the nitty-gritty details!