supervision - discussion about system services, daemon supervision, init, runlevel management, and tools such as s6 and runit
 help / color / mirror / Atom feed
* [PATCH 1/2] doc/s6-rc-compile.html: document bundle flattening
@ 2023-09-26  0:41 Adam Joseph
  2023-09-26  0:41 ` [PATCH 2/2] doc: define "singleton bundle", document special rules Adam Joseph
  0 siblings, 1 reply; 2+ messages in thread
From: Adam Joseph @ 2023-09-26  0:41 UTC (permalink / raw)
  To: supervision; +Cc: Adam Joseph

This commit adds a single sentence explaining that nested bundles
are flattened by s6-rc-compile; the fact that one bundle contains
another (rather than merely happening to contain all the atomics
that the latter contains) is not preserved by s6-rc-compile.

Although this is the most reasonable handling it is not the only
possible handling.  I had to read the source code in order to make
sure that bundle nesting was not represented in the output of
s6-rc-compile, and figured that adding a mention of this fact to the
documentation might save others the trouble.

More importantly, the special rules for singleton bundles (see next
patch in series) depend on this flattening behavior.

Signed-off-by: Adam Joseph <adam@westernsemico.com>
---
 doc/s6-rc-compile.html | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html
index e1ad82b..ef06893 100644
--- a/doc/s6-rc-compile.html
+++ b/doc/s6-rc-compile.html
@@ -136,6 +136,9 @@ deprecated. </li>
 <tt>contents</tt> file.
 However, if s6-rc-compile detects a cycle in bundle definitions, it will
 complain and exit 1.
+Bundles are flattened during compilation: a parent bundle which
+contains a child bundle will be compiled as if the parent bundle had
+directly included the child bundle's contents.
 </p>
 
 <h3> For atomic services </h3>
-- 
2.41.0


^ permalink raw reply	[flat|nested] 2+ messages in thread

* [PATCH 2/2] doc: define "singleton bundle", document special rules
  2023-09-26  0:41 [PATCH 1/2] doc/s6-rc-compile.html: document bundle flattening Adam Joseph
@ 2023-09-26  0:41 ` Adam Joseph
  0 siblings, 0 replies; 2+ messages in thread
From: Adam Joseph @ 2023-09-26  0:41 UTC (permalink / raw)
  To: supervision; +Cc: Adam Joseph

While reviewing the source code for s6-rc-update I noticed that it
has special handling for singleton bundles; these are not explicitly
defined in the documentation, nor is this behavior described.  This
commit does so.

Signed-off-by: Adam Joseph <adam@westernsemico.com>
---
 doc/s6-rc-compile.html |  9 +++++++++
 doc/s6-rc-update.html  | 13 ++++++++-----
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/doc/s6-rc-compile.html b/doc/s6-rc-compile.html
index ef06893..0c7301b 100644
--- a/doc/s6-rc-compile.html
+++ b/doc/s6-rc-compile.html
@@ -141,6 +141,15 @@ contains a child bundle will be compiled as if the parent bundle had
 directly included the child bundle's contents.
 </p>
 
+<p>
+A <i>singleton bundle</i> is a bundle which contains exactly one
+atomic after flattening.  This distinction is important
+to <tt>s6-rc-update</tt>, which allows renaming of singleton bundles
+(but not other bundles), and which considers a singleton bundle to
+be of the same type (oneshot or longrun) as the atomic it contains
+for purposes of avoiding unnecessary restarts.
+</p>
+
 <h3> For atomic services </h3>
 
 <ul>
diff --git a/doc/s6-rc-update.html b/doc/s6-rc-update.html
index 0883a22..49aa16a 100644
--- a/doc/s6-rc-update.html
+++ b/doc/s6-rc-update.html
@@ -149,8 +149,10 @@ service to be restarted in the following cases:
  <li> The service has disappeared in the new compiled. In this case, the
 old service will simply be stopped. </li>
  <li> The service has changed types: a oneshot becomes a longrun, a longrun
-becomes a oneshot, or an atomic service becomes a bundle. In this case, the
-old service will be stopped, then the new service will be started. </li>
+becomes a oneshot, or an atomic service becomes a non-singleton bundle. In this case, the
+old service will be stopped, then the new service will be started.
+Note that singleton bundles are considered to be the same type
+as the single atomic they contain.</li>
  <li> The service has a dependency to a service that must restart, or to an
 old service that must stop, or to a new service that did not previously
 exist or that was previously down. </li>
@@ -202,8 +204,8 @@ can be quoted, that <tt>#</tt> comments are recognized, etc.
 </p>
 
 <p>
- The first word in a line must be the name of an "old" atomic service, i.e.
-an atomic service contained in the current live database. The remaining
+ The first word in a line must be the name of an "old" atomic service or singleton bundle, i.e.
+an atomic service (or bundle containing exactly one atomic service) contained in the current live database. The remaining
 words in the line are instructions telling s6-rc-update how to convert
 that service.
 </p>
@@ -216,7 +218,8 @@ line must be the new name of the service in the new database: s6-rc-update
 will then rename it. It is possible
 to rename an atomic service to another atomic service or a bundle, but no
 matter whether a service is renamed or not, changing its type will force a
-restart.
+restart.  Note that singleton bundles are considered to be the same type as
+the atomic they contain.
 </p>
 
 <h4> Restarting </h4>
-- 
2.41.0


^ permalink raw reply	[flat|nested] 2+ messages in thread

end of thread, other threads:[~2023-09-26  0:42 UTC | newest]

Thread overview: 2+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-09-26  0:41 [PATCH 1/2] doc/s6-rc-compile.html: document bundle flattening Adam Joseph
2023-09-26  0:41 ` [PATCH 2/2] doc: define "singleton bundle", document special rules Adam Joseph

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).