diff options
| author | Siri Hansen <siri@erlang.org> | 2018-09-07 12:16:00 +0200 |
|---|---|---|
| committer | Siri Hansen <siri@erlang.org> | 2018-09-07 12:16:00 +0200 |
| commit | 3b50bb697121de96d03deffcd65ed5859de86558 (patch) | |
| tree | f932ca5be98cdc5521ca48cf453bf51e273c893a | |
| parent | 5801fcb2b36e04c433dcf0b90a8c47b86e34fc07 (diff) | |
| download | erlang-3b50bb697121de96d03deffcd65ed5859de86558.tar.gz | |
[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.
| -rw-r--r-- | lib/stdlib/doc/src/supervisor.xml | 12 | ||||
| -rw-r--r-- | system/doc/design_principles/sup_princ.xml | 9 |
2 files changed, 17 insertions, 4 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 diff --git a/system/doc/design_principles/sup_princ.xml b/system/doc/design_principles/sup_princ.xml index 06ca44a9f6..a2e0d95408 100644 --- a/system/doc/design_principles/sup_princ.xml +++ b/system/doc/design_principles/sup_princ.xml @@ -312,12 +312,17 @@ child_spec() = #{id => child_id(), % mandatory signal back. If no exit signal is received within the specified time, the child process is unconditionally terminated using <c>exit(Child, kill)</c>.</item> - <item>If the child process is another supervisor, it is to be + <item>If the child process is another supervisor, it must be set to <c>infinity</c> to give the subtree enough time to shut down. It is also allowed to set it to <c>infinity</c>, - if the child process is a worker. See the warning below:</item> + if the child process is a worker. See the warning below:</item> </list> <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> <p>Be careful when setting the shutdown time to <c>infinity</c> when the child process is a worker. Because, in this situation, the termination of the supervision tree depends on the |