From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:49020) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1fdN5f-00057G-PA for guix-patches@gnu.org; Wed, 11 Jul 2018 17:56:05 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1fdN5e-0004Mv-MS for guix-patches@gnu.org; Wed, 11 Jul 2018 17:56:03 -0400 Received: from debbugs.gnu.org ([208.118.235.43]:48115) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1fdN5e-0004Mp-IO for guix-patches@gnu.org; Wed, 11 Jul 2018 17:56:02 -0400 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1fdN5e-0005C8-5o for guix-patches@gnu.org; Wed, 11 Jul 2018 17:56:02 -0400 Subject: [bug#32128] [PATCH 1/2] services: shepherd: Support custom actions. References: <20180711214717.29955-1-ludo@gnu.org> In-Reply-To: <20180711214717.29955-1-ludo@gnu.org> Resent-Message-ID: From: Ludovic =?UTF-8?Q?Court=C3=A8s?= Date: Wed, 11 Jul 2018 23:55:03 +0200 Message-Id: <20180711215504.30221-1-ludo@gnu.org> List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: 32128@debbugs.gnu.org * gnu/services/shepherd.scm ()[actions]: New field. (): New record type. (shepherd-service-file): Pass #:actions to 'make'. * doc/guix.texi (Shepherd Services): Document custom actions. --- doc/guix.texi | 59 +++++++++++++++++++++++++++++++++++++++ gnu/services/shepherd.scm | 23 ++++++++++++++- 2 files changed, 81 insertions(+), 1 deletion(-) diff --git a/doc/guix.texi b/doc/guix.texi index 8026bea35..0a6b2244d 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -21963,6 +21963,17 @@ Constructors,,, shepherd, The GNU Shepherd Manual}). They are given as G-expressions that get expanded in the Shepherd configuration file (@pxref{G-Expressions}). +@item @code{actions} (default: @code{'()}) +@cindex actions, of Shepherd services +This is a list of @code{shepherd-action} objects (see below) defining +@dfn{actions} supported by the service, in addition to the standard +@code{start} and @code{stop} actions. Actions listed here become available as +@command{herd} sub-commands: + +@example +herd @var{action} @var{service} [@var{arguments}@dots{}] +@end example + @item @code{documentation} A documentation string, as shown when running: @@ -21980,6 +21991,54 @@ This is the list of modules that must be in scope when @code{start} and @end table @end deftp +@deftp {Data Type} shepherd-action +This is the data type that defines additional actions implemented by a +Shepherd service (see above). + +@table @code +@item name +Symbol naming the action. + +@item documentation +This is a documentation string for the action. It can be viewed by running: + +@example +herd doc @var{service} action @var{action} +@end example + +@item procedure +This should be a gexp that evaluates to a procedure of at least one argument, +which is the ``running value'' of the service (@pxref{Slots of services,,, +shepherd, The GNU Shepherd Manual}). +@end table + +The following example defines an action called @code{say-hello} that kindly +greets the user: + +@example +(shepherd-action + (name 'say-hello) + (documentation "Say hi!") + (procedure #~(lambda (running . args) + (format #t "Hello, friend! arguments: ~s\n" + args) + #t))) +@end example + +Assuming this action is added to the @code{example} service, then you can do: + +@example +# herd say-hello example +Hello, friend! arguments: () +# herd say-hello example a b c +Hello, friend! arguments: ("a" "b" "c") +@end example + +This, as you can see, is a fairly sophisticated way to say hello. +@xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more +info on actions. +@end deftp + @defvr {Scheme Variable} shepherd-root-service-type The service type for the Shepherd ``root service''---i.e., PID@tie{}1. diff --git a/gnu/services/shepherd.scm b/gnu/services/shepherd.scm index 6ca53faa3..4cd224984 100644 --- a/gnu/services/shepherd.scm +++ b/gnu/services/shepherd.scm @@ -49,6 +49,12 @@ shepherd-service-auto-start? shepherd-service-modules + shepherd-action + shepherd-action? + shepherd-action-name + shepherd-action-documentation + shepherd-action-procedure + %default-modules shepherd-service-file @@ -146,11 +152,20 @@ DEFAULT is given, use it as the service's default value." (start shepherd-service-start) ;g-expression (procedure) (stop shepherd-service-stop ;g-expression (procedure) (default #~(const #f))) + (actions shepherd-service-actions ;list of + (default '())) (auto-start? shepherd-service-auto-start? ;Boolean (default #t)) (modules shepherd-service-modules ;list of module names (default %default-modules))) +(define-record-type* + shepherd-action make-shepherd-action + shepherd-action? + (name shepherd-action-name) ;symbol + (procedure shepherd-action-procedure) ;gexp + (documentation shepherd-action-documentation)) ;string + (define (shepherd-service-canonical-name service) "Return the 'canonical name' of SERVICE." (first (shepherd-service-provision service))) @@ -223,7 +238,13 @@ stored." #:requires '#$(shepherd-service-requirement service) #:respawn? '#$(shepherd-service-respawn? service) #:start #$(shepherd-service-start service) - #:stop #$(shepherd-service-stop service)))))) + #:stop #$(shepherd-service-stop service) + #:actions + (make-actions + #$@(map (match-lambda + (($ name proc doc) + #~(#$name #$doc #$proc))) + (shepherd-service-actions service)))))))) (define (shepherd-configuration-file services) "Return the shepherd configuration file for SERVICES." -- 2.18.0