[shepherd] branch main updated: doc: Mention timeliness of #:start and #:stop.

[Ludovic Courtès]

This is an automated email from the git hooks/post-receive script.

civodul pushed a commit to branch main
in repository shepherd.

The following commit(s) were added to refs/heads/main by this push:
     new a324f75  doc: Mention timeliness of #:start and #:stop.
a324f75 is described below

commit a324f7543b1858585923bd289d08ec5946ddf228
Author: Ludovic Courtès <ludo@gnu.org>
AuthorDate: Wed Jan 31 07:41:21 2024 +0100

    doc: Mention timeliness of #:start and #:stop.
    
    * doc/shepherd.texi (Defining Services): Mention timeliness for #:start
    and #:stop.
    (Service De- and Constructors): Rewrite intro.
---
 doc/shepherd.texi | 21 ++++++++++++++++++---
 1 file changed, 18 insertions(+), 3 deletions(-)

diff --git a/doc/shepherd.texi b/doc/shepherd.texi
index aca3a57..253e586 100644
--- a/doc/shepherd.texi
+++ b/doc/shepherd.texi
@@ -791,6 +791,12 @@ attempt failed, it must return @code{#f} or throw an 
exception;
 otherwise, the return value is stored as the @dfn{running value} of the
 service.
 
+@quotation Note
+Constructors must terminate, successfully or not, in a timely fashion,
+typically less than a minute.  Failing to do that, the service would
+remain in ``starting'' state and users would be unable to stop it.
+@end quotation
+
 @xref{Service De- and Constructors}, for info on common service constructors.
 
 @item #:stop
@@ -804,6 +810,12 @@ will again be stored as the running value, so it should
 return @code{#f} if it is now possible again to start the service at a
 later point.
 
+@quotation Note
+Destructors must also terminate in a timely fashion, typically less than
+a minute.  Failing to do that, the service would remain in ``stopping''
+state and users would be unable to stop it.
+@end quotation
+
 @xref{Service De- and Constructors}, for info on common service
 destructors.
 
@@ -1034,9 +1046,12 @@ details!
 @cindex generating destructors
 @cindex constructors, generation of
 @cindex destructors, generation of
-All of the procedures listed below return procedures generated from
-the supplied arguments.  These procedures take one argument in the
-case of destructors and no arguments in the case of constructors.
+Each service has a @code{start} procedure and a @code{stop} procedure,
+also referred to as its @dfn{constructor} and @dfn{destructor}
+(@pxref{Services}).  The procedures listed below return procedures that
+may be used as service constructors and destructors.  They are flexible
+enough to cover most use cases and carefully written to complete in a
+timely fashion.
 
 @deffn {Procedure} make-forkexec-constructor @var{command} @
   [#:user #f] @