From f979493bfa777e61d4da1460982370c0cecc1ef3 Mon Sep 17 00:00:00 2001
From: Siri Hansen <siri@erlang.org>
Date: Tue, 6 May 2014 11:50:45 +0200
Subject: Update gen_event:stop to be synchronous

This function now uses proc_lib:stop, which guarantees that the
process is terminated before the function return.
---
 lib/stdlib/doc/src/gen_event.xml | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

(limited to 'lib/stdlib/doc/src')

diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml
index b9dfff833e..5c96d6e576 100644
--- a/lib/stdlib/doc/src/gen_event.xml
+++ b/lib/stdlib/doc/src/gen_event.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1996</year><year>2013</year>
+      <year>1996</year><year>2014</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -44,6 +44,7 @@
     <pre>
 gen_event module                   Callback module
 ----------------                   ---------------
+gen_event:start
 gen_event:start_link       ----->  -
 
 gen_event:add_handler
@@ -177,7 +178,7 @@ gen_event:stop             ----->  Module:terminate/2
       <name>add_handler(EventMgrRef, Handler, Args) -> Result</name>
       <fsummary>Add an event handler to a generic event manager.</fsummary>
       <type>
-        <v>EventMgr = Name | {Name,Node} | {global,GlobalName}
+        <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
 	| {via,Module,ViaName} | pid()</v>
         <v>&nbsp;Name = Node = atom()</v>
         <v>&nbsp;GlobalName = ViaName = term()</v>
@@ -223,7 +224,7 @@ gen_event:stop             ----->  Module:terminate/2
       <name>add_sup_handler(EventMgrRef, Handler, Args) -> Result</name>
       <fsummary>Add a supervised event handler to a generic event manager.</fsummary>
       <type>
-        <v>EventMgr = Name | {Name,Node} | {global,GlobalName}
+        <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
 	| {via,Module,ViaName} | pid()</v>
         <v>&nbsp;Name = Node = atom()</v>
         <v>&nbsp;GlobalName = ViaName = term()</v>
@@ -456,19 +457,37 @@ gen_event:stop             ----->  Module:terminate/2
     </func>
     <func>
       <name>stop(EventMgrRef) -> ok</name>
+      <name>stop(EventMgrRef, Reason, Timeout) -> ok</name>
       <fsummary>Terminate a generic event manager.</fsummary>
       <type>
         <v>EventMgrRef = Name | {Name,Node} | {global,GlobalName}
 	| {via,Module,ViaName} | pid()</v>
         <v>Name = Node = atom()</v>
         <v>GlobalName = ViaName = term()</v>
+        <v>Reason = term()</v>
+        <v>Timeout = int()>0 | infinity</v>
       </type>
       <desc>
-        <p>Terminates the event manager <c>EventMgrRef</c>. Before
-          terminating, the event manager will call
-          <c>Module:terminate(stop,...)</c> for each installed event
-          handler.</p>
-        <p>See <c>add_handler/3</c> for a description of the argument.</p>
+        <p>Orders the event manager <c>EventMgrRef</c> to exit with
+          the given <c>Reason</c> and waits for it to
+          terminate. Before terminating, the gen_event will call
+          <seealso marker="#Module:terminate/2">Module:terminate(stop,...)</seealso>
+	  for each installed event handler.</p>
+	<p>The function returns <c>ok</c> if the event manager terminates
+	  with the expected reason. Any other reason than <c>normal</c>,
+          <c>shutdown</c>, or <c>{shutdown,Term}</c> will cause an
+          error report to be issued using
+          <seealso marker="kernel:error_logger#format/2">error_logger:format/2</seealso>.
+	  The default <c>Reason</c> is <c>normal</c>.</p>
+	<p><c>Timeout</c> is an integer greater than zero which
+          specifies how many milliseconds to wait for the event manager to
+          terminate, or the atom <c>infinity</c> to wait
+          indefinitely. The default value is <c>infinity</c>. If the
+          event manager has not terminated within the specified time, a
+          <c>timeout</c> exception is raised.</p>
+	<p>If the process does not exist, a <c>noproc</c> exception
+	  is raised.</p>
+        <p>See <c>add_handler/3</c> for a description of <c>EventMgrRef</c>.</p>
       </desc>
     </func>
   </funcs>
-- 
cgit v1.2.3