File 4532-Improve-and-augment-documentation-for-automatic-supe.patch of Package erlang
From 2822067a6931c123fe14f7c634c72158fc7c039a Mon Sep 17 00:00:00 2001
From: Maria-12648430 <maria-12648430@hnc-agency.org>
Date: Tue, 20 Apr 2021 16:06:28 +0200
Subject: [PATCH 2/4] Improve and augment documentation for automatic
supervisor shutdown
---
system/doc/design_principles/sup_princ.xml | 86 +++++++++++++++++++++-
1 file changed, 84 insertions(+), 2 deletions(-)
diff --git a/system/doc/design_principles/sup_princ.xml b/system/doc/design_principles/sup_princ.xml
index f9fcaa6785..f03c317492 100644
--- a/system/doc/design_principles/sup_princ.xml
+++ b/system/doc/design_principles/sup_princ.xml
@@ -256,7 +256,7 @@ SupFlags = #{intensity => MaxR, period => MaxT, ...}</code>
terminate.</p>
<p>This is useful when a supervisor represents a work unit
of cooperating children, as opposed to independent workers. When
- the work unit has finished it's work, that is, when any or all
+ the work unit has finished its work, that is, when any or all
significant child processes have terminated, the supervisor
should then shut down by terminating all remaining child
processes in reverse start order according to the respective shutdown
@@ -271,7 +271,7 @@ SupFlags = #{auto_shutdown => AutoShutdown, ...}</code>
<p>The automatic shutdown facility only applies when significant children
terminate by themselves, that is, when their termination was not
caused by means of the supervisor. Specifically, neither the
- termination of a child as a consequence of a sibling's death in the
+ termination of a child as a consequence of a sibling's death in the
<c>one_for_all</c> or <c>rest_for_one</c> strategies nor the manual
termination of a child by means of <c>supervisor:terminate_child/2</c>
will trigger an automatic shutdown.</p>
@@ -316,6 +316,24 @@ SupFlags = #{auto_shutdown => AutoShutdown, ...}</code>
expect that their applications may be compiled with older OTP
versions.</p>
</warning>
+
+ <warning>
+ <p>Top supervisors of <seealso marker="applications">Applications</seealso>
+ should not be configured for automatic shutdown, because when the top
+ supervisor exits, the application terminates. If the application is
+ <c>permanent</c>, all other applications and the runtime system
+ are terminated, also.</p>
+ </warning>
+
+ <warning>
+ <p>Supervisors configured for automatic shutdown should not be
+ made <seealso marker="#restart">permanent</seealso> children
+ of their respective parent supervisors, as they would be restarted
+ immediately after having automatically shut down, only to shut down
+ automatically again after a while, and may thus exhaust the
+ <seealso marker="#max_intensity">Maximum Restart Intensity</seealso>
+ of the parent supervisor.</p>
+ </warning>
</section>
<section>
@@ -637,5 +655,69 @@ supervisor:terminate_child(Sup, Pid)</code>
the same procedure as described above, that is, the supervisor
terminates all remaining child processes in reversed start
order, and then terminates itself.</p>
+ <section>
+ <title>Manual stopping versus Automatic Shutdown</title>
+ <p>For several reasons, a supervisor should not be stopped
+ manually via <c>supervisor:terminate_child/2</c> from
+ a child located in its own tree.</p>
+ <list type="ordered">
+ <item>
+ <p>The child process will have to know the pids or registered
+ names not only of the supervisor it wants to stop, but also
+ that of the supervisor's parent supervisor, in order to tell
+ the parent supervisor to stop the supervisor it wants to stop.
+ This can make restructuring a supervision tree difficult.</p>
+ </item>
+ <item>
+ <p><c>supervisor:terminate_child/2</c> is a blocking call that
+ will only return after the parent supervisor has finished
+ the shutdown of the supervisor that should be stopped.
+ Unless the call is made from a spawned process, this will
+ result in a deadlock, as the supervisor waits for the child
+ to exit as part of its shutdown procedure, whereas the
+ child waits for the supervisor to shut down. If the child is
+ trapping exits, this deadlock will last until the
+ <seealso marker="#shutdown">shutdown</seealso>
+ timeout for the child expires.</p>
+ </item>
+ <item>
+ <p>When a supervisor is stopping a child, it will wait for the
+ shutdown to complete before accepting other calls, that is,
+ the supervisor will be unresponsive until then. If the
+ termination takes some time to complete, especially when
+ the considerations outlined in the previous point were not
+ taken into account carefully, said supervisor might become
+ unresponsive for a long time.</p>
+ </item>
+ </list>
+ <p>Instead, it is generally a better approach to rely on
+ <seealso marker="#automatic-shutdown">Automatic
+ Shutdown</seealso>.</p>
+ <list type="ordered">
+ <item>
+ <p>A child process does not need to know anything about its
+ supervisor and its respective parent, not even that it is
+ part of a supervision tree in the first place. It is instead
+ only the supervisor which hosts the child who must know
+ which of its children are
+ <seealso marker="#significant_child">significant</seealso>
+ ones, and when to shut itself down.</p>
+ </item>
+ <item>
+ <p>A child process does not need to do anything special to
+ shut down the work unit it is part of. All it needs to do
+ is terminate normally when it has finished the task it was
+ started for.</p>
+ </item>
+ <item>
+ <p>A supervisor that is automatically shutting itself down
+ will perform the required shutdown steps fully independent
+ of its parent supervisor. The parent supervisor will only
+ notice that its child supervisor has terminated in the end.
+ As the parent supervisor is not involved in the shutdown
+ process, it will not be blocked.</p>
+ </item>
+ </list>
+ </section>
</section>
</chapter>
--
2.26.2
