From a35fa2d2cb5b53c19e7841fb5752a2e31f3c55fe Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= <ludo@gnu.org>
Date: Sat, 22 Mar 2025 11:46:57 +0100
Subject: [PATCH] =?UTF-8?q?services:=20shepherd:=20Add=20=E2=80=98shepherd?=
 =?UTF-8?q?-timer=E2=80=99.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* gnu/services/shepherd.scm (shepherd-timer): New procedure.
* gnu/home/services/shepherd.scm: Re-export it.

Suggested-by: Luis Guilherme Coelho <lgcoelho@disroot.org>
Reviewed-by: Maxim Cournoyer <maxim.cournoyer@gmail.com>
Change-Id: I5f702d4119eee47381a7a1ac650b8ad3fc5e6cdd
---
 gnu/home/services/shepherd.scm |  3 ++-
 gnu/services/shepherd.scm      | 26 ++++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 1 deletion(-)

diff --git a/gnu/home/services/shepherd.scm b/gnu/home/services/shepherd.scm
index 25f1641b32d..b4d826f6bbc 100644
--- a/gnu/home/services/shepherd.scm
+++ b/gnu/home/services/shepherd.scm
@@ -53,7 +53,8 @@
 
                shepherd-action
                shepherd-configuration-action
-               shepherd-trigger-action))
+               shepherd-trigger-action
+               shepherd-timer))
 
 (define-record-type* <home-shepherd-configuration>
   home-shepherd-configuration make-home-shepherd-configuration
diff --git a/gnu/services/shepherd.scm b/gnu/services/shepherd.scm
index e7e414b9205..c8e01c9d832 100644
--- a/gnu/services/shepherd.scm
+++ b/gnu/services/shepherd.scm
@@ -72,6 +72,7 @@
             shepherd-action-procedure
 
             shepherd-configuration-action
+            shepherd-timer
             shepherd-trigger-action
 
             %default-modules
@@ -257,6 +258,31 @@ DEFAULT is given, use it as the service's default value."
   "Return the 'canonical name' of SERVICE."
   (first (shepherd-service-provision service)))
 
+(define %default-timer-documentation
+  "Periodically run a command.") ;no i18n since it gets in the shepherd process
+
+(define* (shepherd-timer provision schedule command
+                         #:key
+                         (requirement '())
+                         (documentation %default-timer-documentation))
+  "Return a Shepherd service with the given PROVISION periodically running
+COMMAND, a list-valued gexp, according to SCHEDULE, a string in Vixie cron
+syntax or a gexp providing a Shepherd calendar event.  DOCUMENTATION is the
+string that appears when running 'herd doc SERVICE'."
+  (shepherd-service
+   (provision provision)
+   (requirement requirement)
+   (modules '((shepherd service timer)))
+   (start #~(make-timer-constructor
+             #$(if (string? schedule)
+                   #~(cron-string->calendar-event #$schedule)
+                   schedule)
+             (command '(#$@command))
+             #:wait-for-termination? #t))
+   (stop #~(make-timer-destructor))
+   (documentation documentation)
+   (actions (list shepherd-trigger-action))))
+
 (define (assert-valid-graph services)
   "Raise an error if SERVICES does not define a valid shepherd service graph,
 for instance if a service requires a nonexistent service, or if more than one