Add system message 'terminate'

This is to be used when implementing synchronous stop of generic
behaviours and other 'sys special processes'.

5 files changed, 45 insertions, 37 deletions

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>
diff --git a/lib/stdlib/src/sys.erl b/lib/stdlib/src/sys.erl
index e25cc25f57..ec6813a28a 100644
--- a/lib/stdlib/src/sys.erl
+++ b/lib/stdlib/src/sys.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %% 
-%% Copyright Ericsson AB 1996-2013. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2014. All Rights Reserved.
 %% 
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
@@ -24,6 +24,7 @@
 	 get_state/1, get_state/2,
 	 replace_state/2, replace_state/3,
 	 change_code/4, change_code/5,
+	 terminate/2, terminate/3,
 	 log/2, log/3, trace/2, trace/3, statistics/2, statistics/3,
 	 log_to_file/2, log_to_file/3, no_debug/1, no_debug/2,
 	 install/2, install/3, remove/2, remove/3]).
@@ -159,6 +160,19 @@ change_code(Name, Mod, Vsn, Extra) ->
 change_code(Name, Mod, Vsn, Extra, Timeout) ->
     send_system_msg(Name, {change_code, Mod, Vsn, Extra}, Timeout).
 
+-spec terminate(Name, Reason) -> 'ok' when
+      Name :: name(),
+      Reason :: term().
+terminate(Name, Reason) ->
+    send_system_msg(Name, {terminate, Reason}).
+
+-spec terminate(Name, Reason, Timeout) -> 'ok' when
+      Name :: name(),
+      Reason :: term(),
+      Timeout :: timeout().
+terminate(Name, Reason, Timeout) ->
+    send_system_msg(Name, {terminate, Reason}, Timeout).
+
 %%-----------------------------------------------------------------
 %% Debug commands
 %%-----------------------------------------------------------------
@@ -294,6 +308,8 @@ mfa(Name, {debug, {Func, Arg2}}) ->
     {sys, Func, [Name, Arg2]};
 mfa(Name, {change_code, Mod, Vsn, Extra}) ->
     {sys, change_code, [Name, Mod, Vsn, Extra]};
+mfa(Name, {terminate, Reason}) ->
+    {sys, terminate, [Name, Reason]};
 mfa(Name, Atom) ->
     {sys, Atom, [Name]}.
 
@@ -309,7 +325,7 @@ mfa(Name, Req, Timeout) ->
 %% Returns: This function *never* returns! It calls the function
 %%          Module:system_continue(Parent, NDebug, Misc)
 %%          there the process continues the execution or
-%%          Module:system_terminate(Raeson, Parent, Debug, Misc) if
+%%          Module:system_terminate(Reason, Parent, Debug, Misc) if
 %%          the process should terminate.
 %%          The Module must export system_continue/3, system_terminate/4
 %%          and format_status/2 for status information.
@@ -335,7 +351,10 @@ handle_system_msg(SysState, Msg, From, Parent, Mod, Debug, Misc, Hib) ->
 	    suspend_loop(suspended, Parent, Mod, NDebug, NMisc, Hib);
 	{running, Reply, NDebug, NMisc} ->
 	    _ = gen:reply(From, Reply),
-            Mod:system_continue(Parent, NDebug, NMisc)
+            Mod:system_continue(Parent, NDebug, NMisc);
+	{{terminating, Reason}, Reply, NDebug, NMisc} ->
+	    _ = gen:reply(From, Reply),
+	    Mod:system_terminate(Reason, Parent, NDebug, NMisc)
     end.
 
 %%-----------------------------------------------------------------
@@ -415,6 +434,8 @@ do_cmd(SysState, get_status, Parent, Mod, Debug, Misc) ->
 do_cmd(SysState, {debug, What}, _Parent, _Mod, Debug, Misc) ->
     {Res, NDebug} = debug_cmd(What, Debug),
     {SysState, Res, NDebug, Misc};
+do_cmd(_, {terminate, Reason}, _Parent, _Mod, Debug, Misc) ->
+    {{terminating, Reason}, ok, Debug, Misc};
 do_cmd(suspended, {change_code, Module, Vsn, Extra}, _Parent,
        Mod, Debug, Misc) ->
     {Res, NMisc} = do_change_code(Mod, Module, Vsn, Extra, Misc),
diff --git a/lib/stdlib/test/sys_SUITE.erl b/lib/stdlib/test/sys_SUITE.erl
index f38bc87ae5..047ee9f1fa 100644
--- a/lib/stdlib/test/sys_SUITE.erl
+++ b/lib/stdlib/test/sys_SUITE.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %% 
-%% Copyright Ericsson AB 1996-2013. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2014. All Rights Reserved.
 %% 
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
@@ -202,14 +202,7 @@ spec_proc(Mod) ->
 		       {Mod,system_get_state},{throw,fail}},_}} ->
 		 ok
 	 end,
-    Mod:stop(),
-    WaitForUnregister = fun W() ->
-		       case whereis(Mod) of
-			   undefined -> ok;
-			   _ -> timer:sleep(10), W()
-		       end
-	       end,
-    WaitForUnregister(),
+    ok = sys:terminate(Mod, normal),
     {ok,_} = Mod:start_link(4),
     ok = case catch sys:replace_state(Mod, fun(_) -> {} end) of
 	     {} ->
@@ -218,8 +211,7 @@ spec_proc(Mod) ->
 		       {Mod,system_replace_state},{throw,fail}},_}} ->
 		 ok
 	 end,
-    Mod:stop(),
-    WaitForUnregister(),
+    ok = sys:terminate(Mod, normal),
     {ok,_} = Mod:start_link(4),
     StateFun = fun(_) -> error(fail) end,
     ok = case catch sys:replace_state(Mod, StateFun) of
@@ -231,7 +223,7 @@ spec_proc(Mod) ->
 	     {'EXIT',{{callback_failed,StateFun,{error,fail}},_}} ->
 		 ok
 	 end,
-    Mod:stop().
+    ok = sys:terminate(Mod, normal).
 
 %%%%%%%%%%%%%%%%%%%%
 %% Dummy server
diff --git a/lib/stdlib/test/sys_sp1.erl b/lib/stdlib/test/sys_sp1.erl
index e84ffcfa12..0fb288991f 100644
--- a/lib/stdlib/test/sys_sp1.erl
+++ b/lib/stdlib/test/sys_sp1.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %%
-%% Copyright Ericsson AB 1996-2013. All Rights Reserved.
+%% Copyright Ericsson AB 1996-2014. All Rights Reserved.
 %%
 %% The contents of this file are subject to the Erlang Public License,
 %% Version 1.1, (the "License"); you may not use this file except in
@@ -17,7 +17,7 @@
 %% %CopyrightEnd%
 %%
 -module(sys_sp1).
--export([start_link/1, stop/0]).
+-export([start_link/1]).
 -export([alloc/0, free/1]).
 -export([init/1]).
 -export([system_continue/3, system_terminate/4,
@@ -31,10 +31,6 @@
 start_link(NumCh) ->
     proc_lib:start_link(?MODULE, init, [[self(),NumCh]]).
 
-stop() ->
-    ?MODULE ! stop,
-    ok.
-
 alloc() ->
     ?MODULE ! {self(), alloc},
     receive
@@ -70,11 +66,7 @@ loop(Chs, Parent, Deb) ->
             loop(Chs2, Parent, Deb2);
         {system, From, Request} ->
             sys:handle_system_msg(Request, From, Parent,
-                                  ?MODULE, Deb, Chs);
-        stop ->
-            sys:handle_debug(Deb, fun write_debug/3,
-                             ?MODULE, {in, stop}),
-            ok
+                                  ?MODULE, Deb, Chs)
     end.
 
 system_continue(Parent, Deb, Chs) ->
diff --git a/lib/stdlib/test/sys_sp2.erl b/lib/stdlib/test/sys_sp2.erl
index f1188461f1..a0847b5838 100644
--- a/lib/stdlib/test/sys_sp2.erl
+++ b/lib/stdlib/test/sys_sp2.erl
@@ -17,7 +17,7 @@
 %% %CopyrightEnd%
 %%
 -module(sys_sp2).
--export([start_link/1, stop/0]).
+-export([start_link/1]).
 -export([alloc/0, free/1]).
 -export([init/1]).
 -export([system_continue/3, system_terminate/4,
@@ -30,10 +30,6 @@
 start_link(NumCh) ->
     proc_lib:start_link(?MODULE, init, [[self(),NumCh]]).
 
-stop() ->
-    ?MODULE ! stop,
-    ok.
-
 alloc() ->
     ?MODULE ! {self(), alloc},
     receive
@@ -69,11 +65,7 @@ loop(Chs, Parent, Deb) ->
             loop(Chs2, Parent, Deb2);
         {system, From, Request} ->
             sys:handle_system_msg(Request, From, Parent,
-                                  ?MODULE, Deb, Chs);
-        stop ->
-            sys:handle_debug(Deb, fun write_debug/3,
-                             ?MODULE, {in, stop}),
-            ok
+                                  ?MODULE, Deb, Chs)
     end.
 
 system_continue(Parent, Deb, Chs) ->