[bug#69591] services: shepherd: Support “free-form” services.

* gnu/services/shepherd.scm (<shepherd-service>)[free-form]: New field.
[start]: Add default value.
(shepherd-service-file): Rename to…
(shepherd-service-file/regular): … this.
(shepherd-service-file/free-form): New procedure.
(shepherd-service-file): Dispatch to one of the two procedures above.
* doc/guix.texi (Shepherd Services): Document the ‘free-form’ field.

Change-Id: I206374e950ef6d1e4a996c0f507fb5fcd9cadde3
---
 doc/guix.texi             | 26 +++++++++++++++++++++++++-
 gnu/services/shepherd.scm | 25 ++++++++++++++++++++++---
 2 files changed, 47 insertions(+), 4 deletions(-)

Hi!

This patch fixes a limitation that became apparent with Shepherd 0.10,
where users could not instantiate services from the built-in service
collection for which they do not explicitly specify the ‘start’
and ‘stop’ methods (see REPL service example below).

Thoughts?

Ludo’.


base-commit: 2aeb37def258ad4dd23aaf57ed32f0be44d1bea5
  

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

> * gnu/services/shepherd.scm (<shepherd-service>)[free-form]: New field.
> [start]: Add default value.
> (shepherd-service-file): Rename to…
> (shepherd-service-file/regular): … this.
> (shepherd-service-file/free-form): New procedure.
> (shepherd-service-file): Dispatch to one of the two procedures above.
> * doc/guix.texi (Shepherd Services): Document the ‘free-form’ field.
>
> Change-Id: I206374e950ef6d1e4a996c0f507fb5fcd9cadde3

Oops, wrong issue!  (I used ‘mumi send-email’ while this issue was
current…)
  

Hi Ludovic,

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

> * gnu/services/shepherd.scm (<shepherd-service>)[free-form]: New field.
> [start]: Add default value.
> (shepherd-service-file): Rename to…
> (shepherd-service-file/regular): … this.
> (shepherd-service-file/free-form): New procedure.
> (shepherd-service-file): Dispatch to one of the two procedures above.
> * doc/guix.texi (Shepherd Services): Document the ‘free-form’ field.
>
> Change-Id: I206374e950ef6d1e4a996c0f507fb5fcd9cadde3
> ---
>  doc/guix.texi             | 26 +++++++++++++++++++++++++-
>  gnu/services/shepherd.scm | 25 ++++++++++++++++++++++---
>  2 files changed, 47 insertions(+), 4 deletions(-)
>
> Hi!
>
> This patch fixes a limitation that became apparent with Shepherd 0.10,
> where users could not instantiate services from the built-in service
> collection for which they do not explicitly specify the ‘start’
> and ‘stop’ methods (see REPL service example below).
>
> Thoughts?
>
> Ludo’.
>
> diff --git a/doc/guix.texi b/doc/guix.texi
> index 0102fd0fad3..4d9145445cc 100644
> --- a/doc/guix.texi
> +++ b/doc/guix.texi
> @@ -43909,7 +43909,7 @@ Shepherd Services
>  When true, this is the delay in seconds before restarting a failed
>  service.
>  
> -@item @code{start}
> +@item @code{start} (default: @code{#~(const #t)})
>  @itemx @code{stop} (default: @code{#~(const #f)})
>  The @code{start} and @code{stop} fields refer to the Shepherd's
>  facilities to start and stop processes (@pxref{Service De- and
> @@ -43928,6 +43928,30 @@ Shepherd Services
>  herd @var{action} @var{service} [@var{arguments}@dots{}]
>  @end example
>  
> +@item @code{free-form} (default: @code{#f})
> +When set, this field replaces the @code{start}, @code{stop}, and
> +@code{actions} fields.  It is meant to be used when the service
> +definition comes from some other source, typically the service
> +collection provided by the Shepherd proper (@pxref{Service Collection,,,
> +shepherd, The GNU Shepherd Manual}).
> +
> +@cindex REPL service, for shepherd
> +For example, the snippet below defines a service for the Shepherd's
> +built-in @acronym{REPL, read-eval-print loop} service (@pxref{REPL
> +Service,,, shepherd, The GNU Shepherd Manual}):
> +
> +@lisp
> +(shepherd-service
> +  (provision '(repl))
> +  (modules '((shepherd service repl)))
> +  (free-form #~(repl-service)))
> +@end lisp
> +
> +In this case, the service object is returned by the @code{repl-service}
> +procedure of the Shepherd, so all the @code{free-form} G-expression does
> +is call that procedure.  Note that the @code{provision} field must be
> +consistent with the actual service provision.

Hm, if free-form is expected to be a built-in procedure provided by
Shepherd, should we call it 'built-in' instead of 'free-form' ?  Or
could it have a more general use that I'm not seeing.  It seems the
contract is that it could be any code used 'provision' a shepherd
service object, overriding e.g. the start and stop slots.  I guess
that's more flexibility, and that its 'free-form' name is OK if that's
so.

The rest LGTM.
  

Hi Maxim,

(Cc’ing 71739, which is actually the right one.  :-))

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

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

[...]

>> +@item @code{free-form} (default: @code{#f})
>> +When set, this field replaces the @code{start}, @code{stop}, and
>> +@code{actions} fields.  It is meant to be used when the service
>> +definition comes from some other source, typically the service
>> +collection provided by the Shepherd proper (@pxref{Service Collection,,,
>> +shepherd, The GNU Shepherd Manual}).
>> +
>> +@cindex REPL service, for shepherd
>> +For example, the snippet below defines a service for the Shepherd's
>> +built-in @acronym{REPL, read-eval-print loop} service (@pxref{REPL
>> +Service,,, shepherd, The GNU Shepherd Manual}):
>> +
>> +@lisp
>> +(shepherd-service
>> +  (provision '(repl))
>> +  (modules '((shepherd service repl)))
>> +  (free-form #~(repl-service)))
>> +@end lisp

[...]

> Hm, if free-form is expected to be a built-in procedure provided by
> Shepherd, should we call it 'built-in' instead of 'free-form' ?

I view it as something more generic: it’s typically, but not just, for
when the service comes from a procedure defined in the Shepherd itself.

Other use case is when as a service author you need more freedom that
what you get with the ‘start’ and ‘stop’ fields, like:

  (shepherd-service
    ;; …
    (free-from #~(let ((whatever (spawn-fiber …)))
                   (service '(foo) #:start …))))

It’s probably going to be a relatively marginal use case, but it’s good
to have that extra level of flexibility.

WDYT?

Thanks!

Ludo’.
  

Hi Ludovic,

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

[...]

>> Hm, if free-form is expected to be a built-in procedure provided by
>> Shepherd, should we call it 'built-in' instead of 'free-form' ?
>
> I view it as something more generic: it’s typically, but not just, for
> when the service comes from a procedure defined in the Shepherd itself.
>
> Other use case is when as a service author you need more freedom that
> what you get with the ‘start’ and ‘stop’ fields, like:
>
>   (shepherd-service
>     ;; …
>     (free-from #~(let ((whatever (spawn-fiber …)))
>                    (service '(foo) #:start …))))
>
> It’s probably going to be a relatively marginal use case, but it’s good
> to have that extra level of flexibility.
>
> WDYT?

Thanks for the extra explanation and example.  The extra flexibility
sounds good to me!

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

Maxim Cournoyer <maxim.cournoyer@gmail.com> skribis:

> Thanks for the extra explanation and example.  The extra flexibility
> sounds good to me!
>
> Reviewed-by: Maxim Cournoyer <maxim.cournoyer@gmail>

Pushed as 0a220c1599613b7bee38c0bf8bc1bb3e9cbcaeb8, thanks!

Ludo’.