[shepherd] 05/06: service: Add 'respawn-limit' slot to <service>.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository shepherd.

commit 93baa23baee1e0c62d46d9fd041fc1dabc081f26
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Mon Jun 12 11:56:52 2023 +0200

    service: Add 'respawn-limit' slot to <service>.
    
    * modules/shepherd/service.scm (<service>)[respawn-limit]: New slot.
    (service): Add #:respawn-limit and honor it.
    (service->sexp): Add 'respawn-limit'.
    (respawn-service): Honor 'service-respawn-limit'.
    * tests/status-sexp.sh: Adjust accordingly.
    * doc/shepherd.texi (Defining Services): Document #:respawn-limit and
    'service-respawn-limit'.
    (Service De- and Constructors): Remove most of the explanation and link
    to "Defining Services" instead.
    * NEWS: Update.
---
 NEWS                         |  5 ++++
 doc/shepherd.texi            | 54 ++++++++++++++++++++++++++++++++------------
 modules/shepherd/service.scm | 12 ++++++++--
 tests/status-sexp.sh         |  9 ++++----
 4 files changed, 59 insertions(+), 21 deletions(-)

diff --git a/NEWS b/NEWS
index b644adb..c839187 100644
--- a/NEWS
+++ b/NEWS
@@ -13,6 +13,11 @@ Please send Shepherd bug reports to bug-guix@gnu.org.
 
 * Changes in 0.10.2
 
+** New #:respawn-limit parameter to ‘service’
+
+The ‘service’ form supports a new #:respawn-limit parameter to specify
+per-service respawn limits.
+
 ** New Bash completion
 
 A Bash completion file is now installed, providing tab completion for the
diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index ec7c18d..dbd0756 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -706,9 +706,38 @@ associated process (its ``running value'' is a PID), 
restart the service
 if that process terminates.
 
 There is a limit to avoid endless respawning: when the service gets
-respawned ``too fast'', it is @dfn{disabled}.  The limit is defined by
-@code{default-respawn-limit} (@pxref{Service De- and Constructors,
-@code{default-respawn-limit}}).
+respawned ``too fast'', it is @dfn{disabled}---see
+@code{#:respawn-limit} below.
+
+@cindex respawn limit
+@item #:respawn-limit
+Specify the limit that prevents @command{shepherd} from respawning too
+quickly the service marked with @code{#:respawn? #t}.  Its default value
+is @code{(default-respawn-limit)} (@pxref{Service De- and
+Constructors}).
+
+The limit is expressed as a pair of integers: the first integer,
+@var{n}, specifies a number of consecutive respawns and the second
+integer, @var{t}, specifies a number of seconds.  If the service gets
+respawned more than @var{n} times over a period of @var{t} seconds, it
+is automatically @dfn{disabled} (@pxref{Interacting with Services,
+@code{service-enabled?}}).  Once it is disabled, the service must be
+explicitly re-enabled using @command{herd enable @var{service}} before
+it can be started again.
+
+Consider the service below:
+
+@lisp
+(service '(xyz)
+         #:start (make-forkexec-constructor @dots{})
+         #:stop (make-kill-destructor)
+         #:respawn? #t
+         #:respawn-limit '(3 . 5))
+@end lisp
+
+The effect is that this service will be respawned at most 3 times over a
+period of 5 seconds; if its associated process terminates a fourth time
+during that period, the service will be marked as disabled.
 
 @item #:one-shot?
 @cindex one-shot services
@@ -829,6 +858,11 @@ Return true if @var{service} is meant to be respawned if 
its associated
 process terminates prematurely.
 @end deffn
 
+@deffn {Procedure} service-respawn-limit @var{service}
+Return the respawn limit of @var{service}, expressed as a pair---see
+@code{#:respawn-limit} above.
+@end deffn
+
 @deffn {Procedure} service-documentation @var{service}
 Return the documentation (a string) of @var{service}.
 @end deffn
@@ -1106,18 +1140,8 @@ seconds.
 @cindex respawn limit
 @cindex disabled service
 @defvar default-respawn-limit
-This parameter specifies a limit that prevents @command{shepherd} from
-respawning too quickly a service marked with @code{#:respawn? #t}
-(@pxref{Defining Services}).
-
-The limit is expressed as a pair of integers: the first integer,
-@var{n}, specifies a number of consecutive respawns and the second
-integer, @var{t}, specifies a number of seconds.  If the service gets
-respawned more than @var{n} times over a period of @var{t} seconds, it
-is automatically @dfn{disabled} (@pxref{Interacting with Services,
-@code{service-enabled?}}).  Once it is disabled, the service must be
-explicitly re-enabled using @command{herd enable @var{service}} before
-it can be started again.
+This parameter specifies the default value of the @code{#:respawn-limit}
+parameter of @code{service} (@pxref{Defining Services}).
 
 As an example, suppose you add this line to your configuration file:
 
diff --git a/modules/shepherd/service.scm b/modules/shepherd/service.scm
index 6a2b2de..5097933 100644
--- a/modules/shepherd/service.scm
+++ b/modules/shepherd/service.scm
@@ -57,6 +57,7 @@
             one-shot-service?
             transient-service?
             respawn-service?
+            service-respawn-limit
             service-documentation
 
             service-canonical-name
@@ -282,6 +283,10 @@ Log abnormal termination reported by @var{status}."
   (respawn? #:init-keyword #:respawn?
            #:init-value #f
            #:getter respawn-service?)
+  ;; Pair denoting the respawn limit of this service.
+  (respawn-limit #:init-keyword #:respawn-limit
+                 #:init-thunk default-respawn-limit
+                 #:getter service-respawn-limit)
   ;; The action to perform to start the service.  This must be a
   ;; procedure and may take an arbitrary amount of arguments, but it
   ;; must be possible to call it without any argument.  If the
@@ -326,6 +331,7 @@ Log abnormal termination reported by @var{status}."
                   (one-shot? #f)
                   (transient? #f)
                   (respawn? #f)
+                  (respawn-limit (default-respawn-limit))
                   (start (lambda () #t))
                   (stop (lambda (running) #f))
                   (actions (actions))
@@ -341,6 +347,7 @@ denoting what the service provides."
        #:one-shot? one-shot?
        #:transient? transient?
        #:respawn? respawn?
+       #:respawn-limit respawn-limit
        #:start start
        #:stop stop
        #:actions actions
@@ -1059,7 +1066,8 @@ clients."
             (startup-failures ,(service-startup-failures service))
             (status ,(service-status service))
             (one-shot? ,(one-shot-service? service))
-            (transient? ,(transient-service? service))))
+            (transient? ,(transient-service? service))
+            (respawn-limit ,(service-respawn-limit service))))
 
 
 ;;;
@@ -2492,7 +2500,7 @@ terminated."
 attempted to respawn the service a number of times already and it keeps dying,
 then disable it."
   (define respawn-limit
-    (default-respawn-limit))
+    (service-respawn-limit serv))
 
   (if (and (respawn-service? serv)
            (not (respawn-limit-hit? (service-respawn-times serv)
diff --git a/tests/status-sexp.sh b/tests/status-sexp.sh
index b9847ad..f35c23b 100644
--- a/tests/status-sexp.sh
+++ b/tests/status-sexp.sh
@@ -77,7 +77,8 @@ root_service_sexp="
       (startup-failures ())
       (status running)
       (one-shot? #f)
-      (transient? #f))"
+      (transient? #f)
+      (respawn-limit (5 . 7)))"
 
 # Define a helper procedure that resets timestamps in the 'status-changes'
 # property to make it easier to compare them.
@@ -116,7 +117,7 @@ $define_reset_timestamps
                (status-changes ((running . 0) (starting . 0)))
                (startup-failures ())
                (status running)
-               (one-shot? #f) (transient? #f))
+               (one-shot? #f) (transient? #f) (respawn-limit (5 . 7)))
              (service (version 0)
                (provides (bar)) (requires (foo))
                (respawn? #f) (docstring \"Bar!\")
@@ -125,7 +126,7 @@ $define_reset_timestamps
                (status-changes ())
                (startup-failures ())
                (status stopped)
-               (one-shot? #f) (transient? #f)))))))
+               (one-shot? #f) (transient? #f) (respawn-limit (5 . 7))))))))
 "
 
 # The 'start' command should return the service sexp on success.
@@ -152,7 +153,7 @@ $define_reset_timestamps
                (status-changes ((running . 0) (starting . 0)))
                (startup-failures ())
                (status running)
-               (one-shot? #f) (transient? #f))))))
+               (one-shot? #f) (transient? #f) (respawn-limit (5 . 7)))))))
 "
 
 # Make sure we get an 'error' sexp when querying a nonexistent service.