[supervisor] Add warning about race condition

ERL-724: "During a 'gentle' shutdown, supervisors unlink from their
children before sending shutdown signals to them. This can lead to a
race condition in supervision trees, when the timeout for gentle
shutdown of a parent supervisor expires and it kills a child
supervisor that has just unlinked from a child of its own, leaving the
child supervisor's own child still running after its supervisor is
killed."

This commit adds a warning about this in the documentation.

1 files changed, 10 insertions, 2 deletions

diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml
index 6d5065ca02..0e8075a578 100644
--- a/lib/stdlib/doc/src/supervisor.xml
+++ b/lib/stdlib/doc/src/supervisor.xml
@@ -208,8 +208,16 @@ child_spec() = #{id => child_id(),       % mandatory
           the child process is unconditionally terminated using
           <c>exit(Child,kill)</c>.</p>
         <p>If the child process is another supervisor, the shutdown time
-          is to be set to <c>infinity</c> to give the subtree ample
-          time to shut down. It is also allowed to set it to <c>infinity</c>,
+          must be set to <c>infinity</c> to give the subtree ample
+          time to shut down.</p>
+	<warning>
+	  <p>Setting the shutdown time to anything other
+	    than <c>infinity</c> for a child of type <c>supervisor</c>
+	    can cause a race condition where the child in question
+	    unlinks its own children, but fails to terminate them
+	    before it is killed.</p>
+	</warning>
+	<p>It is also allowed to set it to <c>infinity</c>,
           if the child process is a worker.</p>
         <warning>
           <p>Be careful when setting the shutdown time to