File 1292-Clarify-gen_event-add_sup_handler-Re-EXIT-5257.patch of Package erlang

From 0ce4c73b18793266afee570a671d299c7e7a4997 Mon Sep 17 00:00:00 2001
From: David Buckley <davidbuckley@gambitresearch.com>
Date: Thu, 7 Oct 2021 14:23:24 +0100
Subject: [PATCH] Clarify gen_event:add_sup_handler Re 'EXIT' #5257

---
 lib/stdlib/doc/src/gen_event.xml        | 19 +++++++++++++++----
 system/doc/design_principles/events.xml |  3 ++-
 2 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml
index aaff07f0b1..188699999e 100644
--- a/lib/stdlib/doc/src/gen_event.xml
+++ b/lib/stdlib/doc/src/gen_event.xml
@@ -207,14 +207,17 @@ gen_event:stop             ----->  Module:terminate/2
       <desc>
         <p>Adds a new event handler in the same way as
           <seealso marker="#add_handler/3"><c>add_handler/3</c></seealso>,
-          but also supervises the connection between the event handler
+          but also supervises the connection by linking the event handler
           and the calling process.</p>
         <list type="bulleted">
           <item>If the calling process later terminates with <c>Reason</c>,
-           the event manager deletes the event handler by calling
+           the event manager deletes any supervised event handlers by calling
            <seealso marker="#Module:terminate/2">
-           <c>Module:terminate/2</c></seealso>
-           with <c>{stop,Reason}</c> as argument.
+           <c>Module:terminate/2</c></seealso>,
+           then calls
+           <seealso marker="#Module:handle_info/2">
+           <c>Module:handle_info/2</c></seealso>
+           for each remaining handler.
           </item>
           <item>
             <p>If the event handler is deleted later, the event manager
@@ -1005,6 +1008,14 @@ gen_event:stop             ----->  Module:terminate/2
           an event manager receives any other message than an event or
           a synchronous request (or a system message).</p>
         <p><c>Info</c> is the received message.</p>
+        <p>In particular, this callback will be made when a process terminated
+          after calling
+          <seealso marker="#add_sup_handler/3">
+          <c>add_sup_handler/3</c></seealso>. Any event handler
+          attached to an event manager which in turn has a supervised handler
+          should expect callbacks of the shape
+          <seealso marker="#Module:handle_info/2">
+          <c>Module:handle_info({'EXIT', Pid, Reason}, State)</c></seealso>.</p>
         <p>For a description of <c>State</c> and possible return values, see
           <seealso marker="#Module:handle_event/2">
           <c>Module:handle_event/2</c></seealso>.</p>
diff --git a/system/doc/design_principles/events.xml b/system/doc/design_principles/events.xml
index 3b13c6a0cd..9230ff1027 100644
--- a/system/doc/design_principles/events.xml
+++ b/system/doc/design_principles/events.xml
@@ -227,7 +227,8 @@ ok</pre>
       <c>handle_info(Info, State)</c>
       must be implemented to handle them. Examples of other
       messages are exit messages, if the <c>gen_event</c> is linked to
-      other processes (than the supervisor) and trapping exit signals.</p>
+      other processes (than the supervisor, for example via
+      <c>add_sup_handler</c>) and trapping exit signals.</p>
     <code type="none">
 handle_info({'EXIT', Pid, Reason}, State) ->
     ..code to handle exits here..
-- 
2.31.1