From 6c3d24ccbc597e6d31db1f559470cc59585fdf52 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Wed, 7 May 2014 11:17:24 +0200 Subject: Add system message 'terminate' This is to be used when implementing synchronous stop of generic behaviours and other 'sys special processes'. --- lib/stdlib/doc/src/sys.xml | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) (limited to 'lib/stdlib/doc') 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 @@
- 19962013 + 19962014 Ericsson AB. All Rights Reserved. @@ -356,6 +356,17 @@ installed.

+ + + + Terminate the process + +

This function orders the process to terminate with the + given Reason. The termination is done + asynchronously, so there is no guarantee that the process is + actually terminated when the function returns.

+ +
-- cgit v1.2.3 From 9a0635c297503e2ce0ae394c9c44c72fc61a2a31 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Tue, 29 Apr 2014 11:29:51 +0200 Subject: Add synchronous stop function to proc_lib The new function utilizes sys:terminate. --- lib/stdlib/doc/src/proc_lib.xml | 35 ++++++++++++++++++++++++++++++++++- 1 file changed, 34 insertions(+), 1 deletion(-) (limited to 'lib/stdlib/doc') 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 @@
- 19962013 + 19962014 Ericsson AB. All Rights Reserved. @@ -298,6 +298,39 @@ init(Parent) -> proc_lib functions.

+ + + Terminate a process synchronously. + + Equivalent + to stop(Process, normal, infinity). + + + + + Terminate a process synchronously. + + + + +

Orders the process to exit with the given Reason and + waits for it to terminate.

+

The function returns ok if the process exits with + the given Reason within Timeout + milliseconds.

+

If the call times out, a timeout exception is + raised.

+

If the process does not exist, a noproc + exception is raised.

+

The implementation of this function is based on the + terminate system message, and requires that the + process handles system messages correctly. + See sys(3) + and OTP + Design Principles for information about system + messages.

+ +
-- cgit v1.2.3 From 9d7d1207ff1240b9711f192deb0893c3a044a3d8 Mon Sep 17 00:00:00 2001 From: Siri Hansen 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') 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 @@
- 19962013 + 19962014 Ericsson AB. All Rights Reserved. @@ -43,8 +43,11 @@ 
 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.

       
     
+    
+      stop(FsmRef) -> ok
+      stop(FsmRef, Reason, Timeout) -> ok
+      Synchronously stop a generic FSM.
+      
+        FsmRef = Name | {Name,Node} | {global,GlobalName}
+	| {via,Module,ViaName} | pid()
+         Node = atom()
+         GlobalName = ViaName = term()
+        Reason = term()
+        Timeout = int()>0 | infinity
+      
+      
+	
Orders a generic FSM to exit with the given Reason
+	  and waits for it to terminate. The gen_fsm will call
+          Module:terminate/3
+	  before exiting.

+	
The function returns ok if the generic FSM terminates
+	  with the expected reason. Any other reason than normal,
+          shutdown, or {shutdown,Term} will cause an
+          error report to be issued using
+          error_logger:format/2.
+	  The default Reason is normal.

+	
Timeout is an integer greater than zero which
+          specifies how many milliseconds to wait for the generic FSM
+          to terminate, or the atom infinity to wait
+          indefinitely. The default value is infinity. If the
+          generic FSM has not terminated within the specified time, a
+	  timeout exception is raised.

+	
If the process does not exist, a noproc exception
+	  is raised.

+      
+    
     
       send_event(FsmRef, Event) -> ok
       Send an event asynchronously to a generic FSM.
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 @@
 
   

     
-      19962013
+      19962014
       Ericsson AB. All Rights Reserved.
     
     
@@ -43,8 +43,11 @@
     
 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.

       
     
+    
+      stop(ServerRef) -> ok
+      stop(ServerRef, Reason, Timeout) -> ok
+      Synchronously stop a generic server.
+      
+        ServerRef = Name | {Name,Node} | {global,GlobalName}
+	| {via,Module,ViaName} | pid()
+         Node = atom()
+         GlobalName = ViaName = term()
+        Reason = term()
+        Timeout = int()>0 | infinity
+      
+      
+	
Orders a generic server to exit with the
+	  given Reason and waits for it to terminate. The
+	  gen_server will call
+          Module:terminate/2
+	  before exiting.

+	
The function returns ok if the server terminates
+	  with the expected reason. Any other reason than normal,
+          shutdown, or {shutdown,Term} will cause an
+          error report to be issued using
+          error_logger:format/2.
+	  The default Reason is normal.

+	
Timeout is an integer greater than zero which
+          specifies how many milliseconds to wait for the server to
+          terminate, or the atom infinity to wait
+          indefinitely. The default value is infinity. If the
+          server has not terminated within the specified time, a
+          timeout exception is raised.

+	
If the process does not exist, a noproc exception
+	  is raised.

+      
+    
     
       call(ServerRef, Request) -> Reply
       call(ServerRef, Request, Timeout) -> Reply
-- 
cgit v1.2.3


From f979493bfa777e61d4da1460982370c0cecc1ef3 Mon Sep 17 00:00:00 2001
From: Siri Hansen 
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')

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 @@
 
   

     
-      19962013
+      19962014
       Ericsson AB. All Rights Reserved.
     
     
@@ -44,6 +44,7 @@
     
 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
       add_handler(EventMgrRef, Handler, Args) -> Result
       Add an event handler to a generic event manager.
       
-        EventMgr = Name | {Name,Node} | {global,GlobalName}
+        EventMgrRef = Name | {Name,Node} | {global,GlobalName}
 	| {via,Module,ViaName} | pid()
          Name = Node = atom()
          GlobalName = ViaName = term()
@@ -223,7 +224,7 @@ gen_event:stop             ----->  Module:terminate/2
       add_sup_handler(EventMgrRef, Handler, Args) -> Result
       Add a supervised event handler to a generic event manager.
       
-        EventMgr = Name | {Name,Node} | {global,GlobalName}
+        EventMgrRef = Name | {Name,Node} | {global,GlobalName}
 	| {via,Module,ViaName} | pid()
          Name = Node = atom()
          GlobalName = ViaName = term()
@@ -456,19 +457,37 @@ gen_event:stop             ----->  Module:terminate/2
     
     
       stop(EventMgrRef) -> ok
+      stop(EventMgrRef, Reason, Timeout) -> ok
       Terminate a generic event manager.
       
         EventMgrRef = Name | {Name,Node} | {global,GlobalName}
 	| {via,Module,ViaName} | pid()
         Name = Node = atom()
         GlobalName = ViaName = term()
+        Reason = term()
+        Timeout = int()>0 | infinity
       
       
-        
Terminates the event manager EventMgrRef. Before
-          terminating, the event manager will call
-          Module:terminate(stop,...) for each installed event
-          handler.

-        
See add_handler/3 for a description of the argument.

+        
Orders the event manager EventMgrRef to exit with
+          the given Reason and waits for it to
+          terminate. Before terminating, the gen_event will call
+          Module:terminate(stop,...)
+	  for each installed event handler.

+	
The function returns ok if the event manager terminates
+	  with the expected reason. Any other reason than normal,
+          shutdown, or {shutdown,Term} will cause an
+          error report to be issued using
+          error_logger:format/2.
+	  The default Reason is normal.

+	
Timeout is an integer greater than zero which
+          specifies how many milliseconds to wait for the event manager to
+          terminate, or the atom infinity to wait
+          indefinitely. The default value is infinity. If the
+          event manager has not terminated within the specified time, a
+          timeout exception is raised.

+	
If the process does not exist, a noproc exception
+	  is raised.

+        
See add_handler/3 for a description of EventMgrRef.

       
     
   
-- 
cgit v1.2.3


From 90b779ed59c734b31d26f0b18571a531923ce9f5 Mon Sep 17 00:00:00 2001
From: Siri Hansen 
Date: Wed, 7 May 2014 11:47:40 +0200
Subject: Fix minor bugs in gen_server and gen_fsm documentation

These are probably old copy-and-paste bugs from initial version of
this document.
---
 lib/stdlib/doc/src/gen_fsm.xml    | 10 ++++++----
 lib/stdlib/doc/src/gen_server.xml |  2 +-
 2 files changed, 7 insertions(+), 5 deletions(-)

(limited to 'lib/stdlib/doc')

diff --git a/lib/stdlib/doc/src/gen_fsm.xml b/lib/stdlib/doc/src/gen_fsm.xml
index 24468b0e8e..b1bba3eff0 100644
--- a/lib/stdlib/doc/src/gen_fsm.xml
+++ b/lib/stdlib/doc/src/gen_fsm.xml
@@ -118,7 +118,7 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
           If FsmName={global,GlobalName}, the gen_fsm is
           registered globally as GlobalName using
           global:register_name/2.
-	  If EventMgrName={via,Module,ViaName}, the event manager will
+	  If FsmName={via,Module,ViaName}, the gen_fsm will
 	  register with the registry represented by Module.
 	  The Module callback should export the functions
 	  register_name/2, unregister_name/1,
@@ -246,7 +246,7 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
 	  registered at another node, or
 	  {global,GlobalName}, if the gen_fsm is globally
 	  registered.
-	  {via,Module,ViaName}, if the event manager is registered
+	  {via,Module,ViaName}, if the gen_fsm is registered
 	  through an alternative process registry.
         
         
Event is an arbitrary term which is passed as one of
@@ -564,7 +564,8 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
           Module:init/1 for a description of Timeout and hibernate.

         
If the function returns {stop,Reason,NewStateData},
           the gen_fsm will call
-          Module:terminate(Reason,NewStateData) and terminate.

+          Module:terminate(Reason,StateName,NewStateData) and
+          terminate.

       
     
     
@@ -650,7 +651,8 @@ gen_fsm:sync_send_all_state_event -----> Module:handle_sync_event/4
           {stop,Reason,NewStateData}, any reply to From
           must be given explicitly using gen_fsm:reply/2.
           The gen_fsm will then call
-          Module:terminate(Reason,NewStateData) and terminate.

+          Module:terminate(Reason,StateName,NewStateData) and
+          terminate.

       
     
     
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 4bef50245d..a915e567a5 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -116,7 +116,7 @@ gen_server:abcast     -----> Module:handle_cast/2
           registered globally as GlobalName using
           global:register_name/2. If no name is provided,
           the gen_server is not registered.
-	  If EventMgrName={via,Module,ViaName}, the event manager will
+	  If ServerName={via,Module,ViaName}, the gen_server will
 	  register with the registry represented by Module.
 	  The Module callback should export the functions
 	  register_name/2, unregister_name/1,
-- 
cgit v1.2.3