File 0694-Clarify-gen_event-add_sup_handler-Re-EXIT-... of Package erlang

Overview Repositories Revisions Requests Users Attributes Meta

File 0694-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>
 Adds a new event handler in the same way as
 <seemfa marker="#add_handler/3"><c>add_handler/3</c></seemfa>,
- but also supervises the connection between the event handler
+ but also supervises the connection by linking the event handler
 and the calling process.
 <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
 <seemfa marker="#Module:terminate/2">
- <c>Module:terminate/2</c></seemfa>
- with <c>{stop,Reason}</c> as argument.
+ <c>Module:terminate/2</c></seemfa>,
+ then calls
+ <seemfa marker="#Module:handle_info/2">
+ <c>Module:handle_info/2</c></seemfa>
+ for each remaining handler.
 </item>
 <item>
 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).
 <c>Info</c> is the received message.
+ In particular, this callback will be made when a process terminated
+ after calling
+ <seemfa marker="#add_sup_handler/3">
+ <c>add_sup_handler/3</c></seemfa>. Any event handler
+ attached to an event manager which in turn has a supervised handler
+ should expect callbacks of the shape
+ <seemfa marker="#Module:handle_info/2">
+ <c>Module:handle_info({'EXIT', Pid, Reason}, State)</c></seemfa>.
 For a description of <c>State</c> and possible return values, see
 <seemfa marker="#Module:handle_event/2">
 <c>Module:handle_event/2</c></seemfa>.
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.
+ other processes (than the supervisor, for example via
+ <c>add_sup_handler</c>) and trapping exit signals.
 <code type="none">
 handle_info({'EXIT', Pid, Reason}, State) ->
 ..code to handle exits here..
-- 
2.31.1

Places

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

Places