4.3 Interacting with Services

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.

Procedure: start-service service . args

Start service and its dependencies, passing args to its start method. Return its running value, #f on failure.

Procedure: stop-service service . args

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.

Procedure: perform-service-action service the-action . args

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.

Procedure: start-in-the-background services

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.

Procedure: service-running? service
Procedure: service-stopped? service
Procedure: service-enabled? service

Return true if service is currently running/stopped/enabled, false otherwise.

Procedure: service-status service

Return the status of service as a symbol, one of: 'stopped, 'starting, 'running, or 'stopping.

Procedure: service-running-value service

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).

Procedure: service-status-changes service

Return the list of symbol/timestamp pairs representing recent state changes for service.

Procedure: service-startup-failures service
Procedure: service-respawn-times service

Return the list of startup failure times or respawn times of service.

Procedure: service-replacement service

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.

See Service Internals, if you’re curious about the nitty-gritty details!