Merge branch 'cf/supervisor_shutdown_infinity'

* cf/supervisor_shutdown_infinity:
  Add a warning to docs about workers' shutdown strategy
  Allow an infinite timeout to shutdown worker processes

OTP-9648

4 files changed, 32 insertions, 16 deletions

diff --git a/lib/stdlib/doc/src/supervisor.xml b/lib/stdlib/doc/src/supervisor.xml
index ec607d6e4c..54e7cab884 100644
--- a/lib/stdlib/doc/src/supervisor.xml
+++ b/lib/stdlib/doc/src/supervisor.xml
@@ -169,7 +169,15 @@ child_spec() = {Id,StartFunc,Restart,Shutdown,Type,Modules}
           <c>exit(Child,kill)</c>.</p>
         <p>If the child process is another supervisor, <c>Shutdown</c>
           should be set to <c>infinity</c> to give the subtree ample
-          time to shutdown.</p>
+          time to shutdown. It is also allowed to set it to <c>infinity</c>,
+          if the child process is a worker.</p>
+        <warning>
+          <p>Be careful by setting the <c>Shutdown</c> strategy to
+          <c>infinity</c> when the child process is a worker. Because, in this
+          situation, the termination of the supervision tree depends on the
+          child process, it must be implemented in a safe way and its cleanup
+          procedure must always return.</p>
+        </warning>
         <p><em>Important note on simple-one-for-one supervisors:</em>
           The dynamically created child processes of a
           simple-one-for-one supervisor are not explicitly killed,
diff --git a/lib/stdlib/src/supervisor.erl b/lib/stdlib/src/supervisor.erl
index 9da0d52f8c..051dca462b 100644
--- a/lib/stdlib/src/supervisor.erl
+++ b/lib/stdlib/src/supervisor.erl
@@ -1053,7 +1053,7 @@ validRestartType(RestartType) -> throw({invalid_restart_type, RestartType}).
 
 validShutdown(Shutdown, _) 
   when is_integer(Shutdown), Shutdown > 0 -> true;
-validShutdown(infinity, supervisor)    -> true;
+validShutdown(infinity, _)             -> true;
 validShutdown(brutal_kill, _)          -> true;
 validShutdown(Shutdown, _)             -> throw({invalid_shutdown, Shutdown}).
 
diff --git a/lib/stdlib/test/supervisor_SUITE.erl b/lib/stdlib/test/supervisor_SUITE.erl
index 2aa3131aeb..9d47233422 100644
--- a/lib/stdlib/test/supervisor_SUITE.erl
+++ b/lib/stdlib/test/supervisor_SUITE.erl
@@ -209,8 +209,8 @@ sup_start_fail(Config) when is_list(Config) ->
 %%-------------------------------------------------------------------------
 
 sup_stop_infinity(doc) ->
-    ["See sup_stop/1 when Shutdown = infinity, this walue is only allowed "
-     "for children of type supervisor"];
+    ["See sup_stop/1 when Shutdown = infinity, this walue is allowed "
+     "for children of type supervisor _AND_ worker"];
 sup_stop_infinity(suite) -> [];
 
 sup_stop_infinity(Config) when is_list(Config) ->
@@ -221,12 +221,13 @@ sup_stop_infinity(Config) when is_list(Config) ->
     Child2 = {child2, {supervisor_1, start_child, []}, permanent,
 	      infinity, worker, []},
     {ok, CPid1} = supervisor:start_child(sup_test, Child1),
+    {ok, CPid2} = supervisor:start_child(sup_test, Child2),
     link(CPid1),
-    {error, {invalid_shutdown,infinity}} =
-	supervisor:start_child(sup_test, Child2),
+    link(CPid2),
 
     terminate(Pid, shutdown),
-    check_exit_reason(CPid1, shutdown).
+    check_exit_reason(CPid1, shutdown),
+    check_exit_reason(CPid2, shutdown).
 
 %%-------------------------------------------------------------------------
 
@@ -458,9 +459,8 @@ child_specs(Config) when is_list(Config) ->
     B2 = {child, {m,f,[a]}, prmanent, 1000, worker, []}, 
     B3 = {child, {m,f,[a]}, permanent, -10, worker, []},
     B4 = {child, {m,f,[a]}, permanent, 10, wrker, []},
-    B5 = {child, {m,f,[a]}, permanent, infinity, worker, []},
-    B6 = {child, {m,f,[a]}, permanent, 1000, worker, dy},
-    B7 = {child, {m,f,[a]}, permanent, 1000, worker, [1,2,3]},
+    B5 = {child, {m,f,[a]}, permanent, 1000, worker, dy},
+    B6 = {child, {m,f,[a]}, permanent, 1000, worker, [1,2,3]},
 
     %% Correct child specs!
     %% <Modules> (last parameter in a child spec) can be [] as we do 
@@ -469,6 +469,7 @@ child_specs(Config) when is_list(Config) ->
     C2 = {child, {m,f,[a]}, permanent, 1000, supervisor, []},
     C3 = {child, {m,f,[a]}, temporary, 1000, worker, dynamic},
     C4 = {child, {m,f,[a]}, transient, 1000, worker, [m]},
+    C5 = {child, {m,f,[a]}, permanent, infinity, worker, [m]},
 
     {error, {invalid_mfa,mfa}} = supervisor:start_child(sup_test, B1),
     {error, {invalid_restart_type, prmanent}} =
@@ -477,9 +478,8 @@ child_specs(Config) when is_list(Config) ->
 	= supervisor:start_child(sup_test, B3),
     {error, {invalid_child_type,wrker}}
 	= supervisor:start_child(sup_test, B4),
-    {error, _} = supervisor:start_child(sup_test, B5),
     {error, {invalid_modules,dy}}
-	= supervisor:start_child(sup_test, B6),
+	= supervisor:start_child(sup_test, B5),
 
     {error, {invalid_mfa,mfa}} = supervisor:check_childspecs([B1]),
     {error, {invalid_restart_type,prmanent}} =
@@ -487,15 +487,15 @@ child_specs(Config) when is_list(Config) ->
     {error, {invalid_shutdown,-10}} = supervisor:check_childspecs([B3]),
     {error, {invalid_child_type,wrker}}
 	= supervisor:check_childspecs([B4]),
-    {error, _} = supervisor:check_childspecs([B5]),
-    {error, {invalid_modules,dy}} = supervisor:check_childspecs([B6]),
+    {error, {invalid_modules,dy}} = supervisor:check_childspecs([B5]),
     {error, {invalid_module, 1}} =
-	supervisor:check_childspecs([B7]),
+	supervisor:check_childspecs([B6]),
 
     ok = supervisor:check_childspecs([C1]),
     ok = supervisor:check_childspecs([C2]),
     ok = supervisor:check_childspecs([C3]),
     ok = supervisor:check_childspecs([C4]),
+    ok = supervisor:check_childspecs([C5]),
     ok.
 
 %%-------------------------------------------------------------------------
diff --git a/system/doc/design_principles/sup_princ.xml b/system/doc/design_principles/sup_princ.xml
index 2748f21bbe..9e7cc2f543 100644
--- a/system/doc/design_principles/sup_princ.xml
+++ b/system/doc/design_principles/sup_princ.xml
@@ -181,8 +181,16 @@ init(...) ->
            terminated using <c>exit(Child, kill)</c>.</item>
           <item>If the child process is another supervisor, it should be
            set to <c>infinity</c> to give the subtree enough time to
-           shutdown.</item>
+           shutdown. It is also allowed to set it to <c>infinity</c>, if the
+           child process is a worker.</item>
         </list>
+        <warning>
+          <p>Be careful by setting the <c>Shutdown</c> strategy to
+          <c>infinity</c> when the child process is a worker. Because, in this
+          situation, the termination of the supervision tree depends on the
+          child process, it must be implemented in a safe way and its cleanup
+          procedure must always return.</p>
+        </warning>
       </item>
       <item>
         <p><c>Type</c> specifies if the child process is a supervisor or