From 9d7d1207ff1240b9711f192deb0893c3a044a3d8 Mon Sep 17 00:00:00 2001
From: Siri Hansen <siri@erlang.org>
Date: Wed, 30 Apr 2014 09:35:06 +0200
Subject: Add synchronous stop functions to gen_server and gen_fsm

The functions utilize proc_lib:stop, which in turn utilizes
sys:terminate.
---
 lib/stdlib/doc/src/gen_fsm.xml    | 38 +++++++++++++++++++++++++++++++++++++-
 lib/stdlib/doc/src/gen_server.xml | 39 ++++++++++++++++++++++++++++++++++++++-
 2 files changed, 75 insertions(+), 2 deletions(-)

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

diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml
index 1713367bd8..24468b0e8e 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
@@ -186,6 +189,39 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
           for a description of arguments and return values.</p>
       </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>
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 4c83fde237..4bef50245d 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
 
@@ -183,6 +186,40 @@ gen_server:abcast     -----> Module:handle_cast/2
           for a description of arguments and return values.</p>
       </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>
-- 
cgit v1.2.3