[bug#74997,1/4] services: shepherd: Add ‘transient’ and ‘timer’.

Message ID cb5e08911572a5b7a845e8120f3e7593bf8f0bab.1737152077.git.ludo@gnu.org
State New
Headers
Series Adding the 'timer' and 'transient' Shepherd services |

Commit Message

Ludovic Courtès Jan. 17, 2025, 10:19 p.m. UTC
  * gnu/services/shepherd.scm (shepherd-timer-service-type)
(shepherd-transient-service-type): New variables.
* doc/guix.texi (Shepherd Services): Document them.

Change-Id: I9b622e7e947e7a6384c2701a313d0c7080a0a5f6
---
 doc/guix.texi             | 33 ++++++++++++++++++++++++
 gnu/services/shepherd.scm | 54 +++++++++++++++++++++++++++++++++++++--
 2 files changed, 85 insertions(+), 2 deletions(-)
  

Comments

Maxim Cournoyer Jan. 19, 2025, 7:21 a.m. UTC | #1
Hi Ludovic,

Ludovic Courtès <ludo@gnu.org> writes:

> * gnu/services/shepherd.scm (shepherd-timer-service-type)
> (shepherd-transient-service-type): New variables.
> * doc/guix.texi (Shepherd Services): Document them.
>
> Change-Id: I9b622e7e947e7a6384c2701a313d0c7080a0a5f6
> ---
>  doc/guix.texi             | 33 ++++++++++++++++++++++++
>  gnu/services/shepherd.scm | 54 +++++++++++++++++++++++++++++++++++++--
>  2 files changed, 85 insertions(+), 2 deletions(-)
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 0015d739bb..3e377ca9f4 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -45684,6 +45684,39 @@ Shepherd Services
>                                              (shepherd my-shepherd))))))
>  @end lisp
>
> +@cindex @code{transient} service, Shepherd
> +@defvar shepherd-transient-service-type
> +This service type represents the Shepherd's @code{transient} service,
> +which lets you spawn commands in the background and interact with them
> +as regular Shepherd service; it is similar to @command{systemd-run}.
> +
> +For example, the command below spawns @command{rsync} in the background,
> +in an environment where the @env{SSH_AUTH_SOCK} environment variable has
> +the given value:
> +
> +@example
> +herd spawn transient -E SSH_AUTH_SOCK=$SSH_AUTH_SOCK -- \
> +  rsync -e ssh -vur . backup.example.org:
> +@end example

Neat!

> +@xref{Transient Service Maker,,, shepherd, The GNU Shepherd Manual}, for
> +more info on the @code{transient} service.
> +@end defvar
> +
> +@cindex @code{timer} service, Shepherd
> +@defvar shepherd-timer-service-type
> +This is the service type representing the Shepherd's @code{timer}
> +service, which lets you schedule the execution of commands, similar to
> +the venerable @command{at} command.  Here is an example:
> +
> +@example
> +herd schedule timer at 07:00 -- mpg123 Music/alarm.mp3
> +@end example

Also nice, though I'd use 'ogg123 Music/alarm.ogg' to promote more free
formats!

[...]

> -;;; shepherd.scm ends here
> +
> +;;;
> +;;; Timer and transient service maker.
> +;;;
> +
> +(define shepherd-timer-service-type
> +  (shepherd-service-type
> +   'shepherd-timer
> +   (const (shepherd-service
> +           (provision '(timer))
> +           (requirement '(user-processes))
> +           (modules '((shepherd service timer)))
> +           (free-form #~(timer-service
> +                         '#$provision
> +                         #:requirement '#$requirement))))
> +   #t                                             ;ignored
> +   (description "The Shepherd @code{timer} service lets you schedule commands
> +dynamically, similar to the @code{at} command that your grandparents would use
> +on that Slackware they got on a floppy disk.  For example, consider this
> +command:
> +
> +@example
> +herd schedule timer at 07:00 -- mpg123 Music/alarm.mp3
> +@end example

Ditto (I'd use Ogg Vorbis in the example).

> +It does exactly what you would expect.")))
> +
> +(define shepherd-transient-service-type
> +  (shepherd-service-type
> +   'shepherd-transient
> +   (const (shepherd-service
> +           (provision '(transient))
> +           (requirement '(user-processes))
> +           (modules '((shepherd service transient)))
> +           (free-form #~(transient-service
> +                         '#$provision
> +                         #:requirement '#$requirement))))
> +   #t                                             ;ignored
> +   (description "The Shepherd @code{transient} service lets you run commands
> +asynchronously, in the background, similar to @command{systemd-run}, as in
> +this example:
> +
> +@example
> +herd spawn transient -E SSH_AUTH_SOCK=$SSH_AUTH_SOCK -- \\
> +  rsync -e ssh -vur . backup.example.org:
> +@end example
> +
> +This runs @command{rsync} in the background, as a service that you can inspect
> +with @command{herd status} and stop with @command{herd stop}.")))

Neat!  Taking into account my previous nitpick:

Reviewed-by: Maxim Cournoyer <maxim.cournoyer@gmail>
  

Patch

diff --git a/doc/guix.texi b/doc/guix.texi
index 0015d739bb..3e377ca9f4 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -45684,6 +45684,39 @@  Shepherd Services
                                             (shepherd my-shepherd))))))
 @end lisp
 
+@cindex @code{transient} service, Shepherd
+@defvar shepherd-transient-service-type
+This service type represents the Shepherd's @code{transient} service,
+which lets you spawn commands in the background and interact with them
+as regular Shepherd service; it is similar to @command{systemd-run}.
+
+For example, the command below spawns @command{rsync} in the background,
+in an environment where the @env{SSH_AUTH_SOCK} environment variable has
+the given value:
+
+@example
+herd spawn transient -E SSH_AUTH_SOCK=$SSH_AUTH_SOCK -- \
+  rsync -e ssh -vur . backup.example.org:
+@end example
+
+@xref{Transient Service Maker,,, shepherd, The GNU Shepherd Manual}, for
+more info on the @code{transient} service.
+@end defvar
+
+@cindex @code{timer} service, Shepherd
+@defvar shepherd-timer-service-type
+This is the service type representing the Shepherd's @code{timer}
+service, which lets you schedule the execution of commands, similar to
+the venerable @command{at} command.  Here is an example:
+
+@example
+herd schedule timer at 07:00 -- mpg123 Music/alarm.mp3
+@end example
+
+@xref{Timer Service,,, shepherd, The GNU Shepherd Manual}, for more info
+on the @code{timer} service.
+@end defvar
+
 @defvar %shepherd-root-service
 This service represents PID@tie{}1.
 @end defvar
diff --git a/gnu/services/shepherd.scm b/gnu/services/shepherd.scm
index 0de3c9c55c..5f2625ac20 100644
--- a/gnu/services/shepherd.scm
+++ b/gnu/services/shepherd.scm
@@ -1,5 +1,5 @@ 
 ;;; GNU Guix --- Functional package management for GNU
-;;; Copyright © 2013-2016, 2018-2024 Ludovic Courtès <ludo@gnu.org>
+;;; Copyright © 2013-2016, 2018-2025 Ludovic Courtès <ludo@gnu.org>
 ;;; Copyright © 2017 Clément Lassieur <clement@lassieur.org>
 ;;; Copyright © 2018 Carlo Zancanaro <carlo@zancanaro.id.au>
 ;;; Copyright © 2020 Jan (janneke) Nieuwenhuizen <janneke@gnu.org>
@@ -81,6 +81,8 @@  (define-module (gnu services shepherd)
             shepherd-service-upgrade
 
             user-processes-service-type
+            shepherd-timer-service-type
+            shepherd-transient-service-type
 
             assert-valid-graph))
 
@@ -668,4 +670,52 @@  (define user-processes-service-type
 seconds after @code{SIGTERM} has been sent are terminated with
 @code{SIGKILL}.")))
 
-;;; shepherd.scm ends here
+
+;;;
+;;; Timer and transient service maker.
+;;;
+
+(define shepherd-timer-service-type
+  (shepherd-service-type
+   'shepherd-timer
+   (const (shepherd-service
+           (provision '(timer))
+           (requirement '(user-processes))
+           (modules '((shepherd service timer)))
+           (free-form #~(timer-service
+                         '#$provision
+                         #:requirement '#$requirement))))
+   #t                                             ;ignored
+   (description "The Shepherd @code{timer} service lets you schedule commands
+dynamically, similar to the @code{at} command that your grandparents would use
+on that Slackware they got on a floppy disk.  For example, consider this
+command:
+
+@example
+herd schedule timer at 07:00 -- mpg123 Music/alarm.mp3
+@end example
+
+It does exactly what you would expect.")))
+
+(define shepherd-transient-service-type
+  (shepherd-service-type
+   'shepherd-transient
+   (const (shepherd-service
+           (provision '(transient))
+           (requirement '(user-processes))
+           (modules '((shepherd service transient)))
+           (free-form #~(transient-service
+                         '#$provision
+                         #:requirement '#$requirement))))
+   #t                                             ;ignored
+   (description "The Shepherd @code{transient} service lets you run commands
+asynchronously, in the background, similar to @command{systemd-run}, as in
+this example:
+
+@example
+herd spawn transient -E SSH_AUTH_SOCK=$SSH_AUTH_SOCK -- \\
+  rsync -e ssh -vur . backup.example.org:
+@end example
+
+This runs @command{rsync} in the background, as a service that you can inspect
+with @command{herd status} and stop with @command{herd stop}.")))