Merge branch 'siri/sync-stop-gen/OTP-11173'

* siri/sync-stop-gen/OTP-11173:
  Add synchronous stop function to wx_object
  Fix minor bugs in gen_server and gen_fsm documentation
  Update gen_event:stop to be synchronous
  Add synchronous stop functions to gen_server and gen_fsm
  Add synchronous stop function to proc_lib
  Add system message 'terminate'
  Remove old code from stdlib/test/sys_sp2.erl

5 files changed, 152 insertions, 14 deletions

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>
diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml
index 848d57f3e6..b1bba3eff0 100644
--- a/lib/stdlib/doc/src/gen_fsm.xml
+++ b/lib/stdlib/doc/src/gen_fsm.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>
@@ -43,8 +43,11 @@
     <pre>
 gen_fsm module                    Callback module
 --------------                    ---------------
+gen_fsm:start
 gen_fsm:start_link                -----> Module:init/1
 
+gen_fsm:stop                      -----> Module:terminate/3
+
 gen_fsm:send_event                -----> Module:StateName/2
 
 gen_fsm:send_all_state_event      -----> Module:handle_event/3
@@ -187,6 +190,39 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
       </desc>
     </func>
     <func>
+      <name>stop(FsmRef) -> ok</name>
+      <name>stop(FsmRef, Reason, Timeout) -> ok</name>
+      <fsummary>Synchronously stop a generic FSM.</fsummary>
+      <type>
+        <v>FsmRef = Name | {Name,Node} | {global,GlobalName}
+	| {via,Module,ViaName} | pid()</v>
+        <v>&nbsp;Node = atom()</v>
+        <v>&nbsp;GlobalName = ViaName = term()</v>
+        <v>Reason = term()</v>
+        <v>Timeout = int()>0 | infinity</v>
+      </type>
+      <desc>
+	<p>Orders a generic FSM to exit with the given <c>Reason</c>
+	  and waits for it to terminate. The gen_fsm will call
+          <seealso marker="#Module:terminate/3">Module:terminate/3</seealso>
+	  before exiting.</p>
+	<p>The function returns <c>ok</c> if the generic FSM 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 generic FSM
+          to terminate, or the atom <c>infinity</c> to wait
+          indefinitely. The default value is <c>infinity</c>. If the
+          generic FSM 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>
+      </desc>
+    </func>
+    <func>
       <name>send_event(FsmRef, Event) -> ok</name>
       <fsummary>Send an event asynchronously to a generic FSM.</fsummary>
       <type>
@@ -528,7 +564,8 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
           <c>Module:init/1</c> for a description of <c>Timeout</c> and <c>hibernate</c>.</p>
         <p>If the function returns <c>{stop,Reason,NewStateData}</c>,
           the gen_fsm will call
-          <c>Module:terminate(Reason,NewStateData)</c> and terminate.</p>
+          <c>Module:terminate(Reason,StateName,NewStateData)</c> and
+          terminate.</p>
       </desc>
     </func>
     <func>
@@ -614,7 +651,8 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
           <c>{stop,Reason,NewStateData}</c>, any reply to <c>From</c>
           must be given explicitly using <c>gen_fsm:reply/2</c>.
           The gen_fsm will then call
-          <c>Module:terminate(Reason,NewStateData)</c> and terminate.</p>
+          <c>Module:terminate(Reason,StateName,NewStateData)</c> and
+          terminate.</p>
       </desc>
     </func>
     <func>
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 62c0394479..a915e567a5 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.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>
@@ -43,8 +43,11 @@
     <pre>
 gen_server module            Callback module
 -----------------            ---------------
+gen_server:start
 gen_server:start_link -----> Module:init/1
 
+gen_server:stop       -----> Module:terminate/2
+
 gen_server:call
 gen_server:multi_call -----> Module:handle_call/3
 
@@ -184,6 +187,40 @@ gen_server:abcast     -----> Module:handle_cast/2
       </desc>
     </func>
     <func>
+      <name>stop(ServerRef) -> ok</name>
+      <name>stop(ServerRef, Reason, Timeout) -> ok</name>
+      <fsummary>Synchronously stop a generic server.</fsummary>
+      <type>
+        <v>ServerRef = Name | {Name,Node} | {global,GlobalName}
+	| {via,Module,ViaName} | pid()</v>
+        <v>&nbsp;Node = atom()</v>
+        <v>&nbsp;GlobalName = ViaName = term()</v>
+        <v>Reason = term()</v>
+        <v>Timeout = int()>0 | infinity</v>
+      </type>
+      <desc>
+	<p>Orders a generic server to exit with the
+	  given <c>Reason</c> and waits for it to terminate. The
+	  gen_server will call
+          <seealso marker="#Module:terminate/2">Module:terminate/2</seealso>
+	  before exiting.</p>
+	<p>The function returns <c>ok</c> if the server 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 server to
+          terminate, or the atom <c>infinity</c> to wait
+          indefinitely. The default value is <c>infinity</c>. If the
+          server 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>
+      </desc>
+    </func>
+    <func>
       <name>call(ServerRef, Request) -> Reply</name>
       <name>call(ServerRef, Request, Timeout) -> Reply</name>
       <fsummary>Make a synchronous call to a generic server.</fsummary>
diff --git a/lib/stdlib/doc/src/proc_lib.xml b/lib/stdlib/doc/src/proc_lib.xml
index 5bf5744622..88630b1fdb 100644
--- a/lib/stdlib/doc/src/proc_lib.xml
+++ b/lib/stdlib/doc/src/proc_lib.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>
@@ -298,6 +298,39 @@ init(Parent) ->
           <c>proc_lib</c> functions.</p>
       </desc>
     </func>
+    <func>
+      <name name="stop" arity="1"/>
+      <fsummary>Terminate a process synchronously.</fsummary>
+      <type variable="Process"/>
+      <desc>Equivalent
+	to <seealso marker="#stop/3">stop(Process, normal, infinity)</seealso>.
+      </desc>
+    </func>
+    <func>
+      <name name="stop" arity="3"/>
+      <fsummary>Terminate a process synchronously.</fsummary>
+      <type variable="Process"/>
+      <type variable="Reason"/>
+      <type variable="Timeout"/>
+      <desc>
+        <p>Orders the process to exit with the given <c>Reason</c> and
+          waits for it to terminate.</p>
+	<p>The function returns <c>ok</c> if the process exits with
+	  the given <c>Reason</c> within <c>Timeout</c>
+	  milliseconds.</p>
+	<p>If the call times out, a <c>timeout</c> exception is
+	  raised.</p>
+	<p>If the process does not exist, a <c>noproc</c>
+	  exception is raised.</p>
+	<p>The implementation of this function is based on the
+	  <c>terminate</c> system message, and requires that the
+	  process handles system messages  correctly.
+	  See <seealso marker="sys">sys(3)</seealso>
+	  and <seealso marker="doc/design_principles:spec_proc">OTP
+	  Design Principles</seealso> for information about system
+	  messages.</p>
+      </desc>
+    </func>
   </funcs>
 
   <section>
diff --git a/lib/stdlib/doc/src/sys.xml b/lib/stdlib/doc/src/sys.xml
index a46fa1289f..7fb82e0e7e 100644
--- a/lib/stdlib/doc/src/sys.xml
+++ b/lib/stdlib/doc/src/sys.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>
@@ -356,6 +356,17 @@
           installed.</p>
       </desc>
     </func>
+    <func>
+      <name name="terminate" arity="2"/>
+      <name name="terminate" arity="3"/>
+      <fsummary>Terminate the process</fsummary>
+      <desc>
+        <p>This function orders the process to terminate with the
+        given <c><anno>Reason</anno></c>. The termination is done
+        asynchronously, so there is no guarantee that the process is
+        actually terminated when the function returns.</p>
+      </desc>
+    </func>
   </funcs>
 
   <section>