Add synchronous stop function to proc_lib

The new function utilizes sys:terminate.

3 files changed, 173 insertions, 7 deletions

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/src/proc_lib.erl b/lib/stdlib/src/proc_lib.erl
index 1eb6fc2e86..c925e70613 100644
--- a/lib/stdlib/src/proc_lib.erl
+++ b/lib/stdlib/src/proc_lib.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
@@ -30,7 +30,8 @@
 	 hibernate/3,
 	 init_ack/1, init_ack/2,
 	 init_p/3,init_p/5,format/1,format/2,initial_call/1,
-         translate_initial_call/1]).
+         translate_initial_call/1,
+	 stop/1, stop/3]).
 
 %% Internal exports.
 -export([wake_up/3]).
@@ -750,3 +751,50 @@ format_tag(Tag, Data) ->
 
 modifier(latin1) -> "";
 modifier(_) -> "t".
+
+
+%%% -----------------------------------------------------------
+%%% Stop a process and wait for it to terminate
+%%% -----------------------------------------------------------
+-spec stop(Process) -> 'ok' when
+      Process :: pid() | RegName | {RegName,node()},
+      RegName :: atom().
+stop(Process) ->
+    stop(Process, normal, infinity).
+
+-spec stop(Process, Reason, Timeout) -> 'ok' when
+      Process :: pid() | RegName | {RegName,node()},
+      RegName :: atom(),
+      Reason :: term(),
+      Timeout :: timeout().
+stop(Process, Reason, Timeout) ->
+    {Pid, Mref} = erlang:spawn_monitor(do_stop(Process, Reason)),
+    receive
+	{'DOWN', Mref, _, _, Reason} ->
+	    ok;
+	{'DOWN', Mref, _, _, {noproc,{sys,terminate,_}}} ->
+	    exit(noproc);
+	{'DOWN', Mref, _, _, CrashReason} ->
+	    exit(CrashReason)
+    after Timeout ->
+	    exit(Pid, kill),
+	    receive
+		{'DOWN', Mref, _, _, _} ->
+		    exit(timeout)
+	    end
+    end.
+
+-spec do_stop(Process, Reason) -> Fun when
+      Process :: pid() | RegName | {RegName,node()},
+      RegName :: atom(),
+      Reason :: term(),
+      Fun :: fun(() -> no_return()).
+do_stop(Process, Reason) ->
+    fun() ->
+	    Mref = erlang:monitor(process, Process),
+	    ok = sys:terminate(Process, Reason, infinity),
+	    receive
+		{'DOWN', Mref, _, _, ExitReason} ->
+		    exit(ExitReason)
+	    end
+    end.
diff --git a/lib/stdlib/test/proc_lib_SUITE.erl b/lib/stdlib/test/proc_lib_SUITE.erl
index 8dca69bac4..b6f1973a05 100644
--- a/lib/stdlib/test/proc_lib_SUITE.erl
+++ b/lib/stdlib/test/proc_lib_SUITE.erl
@@ -1,7 +1,7 @@
 %%
 %% %CopyrightBegin%
 %% 
-%% Copyright Ericsson AB 1996-2012. 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
@@ -27,7 +27,7 @@
 	 init_per_group/2,end_per_group/2, 
 	 crash/1, sync_start_nolink/1, sync_start_link/1,
          spawn_opt/1, sp1/0, sp2/0, sp3/1, sp4/2, sp5/1,
-	 hibernate/1]).
+	 hibernate/1, stop/1]).
 -export([ otp_6345/1, init_dont_hang/1]).
 
 -export([hib_loop/1, awaken/1]).
@@ -38,6 +38,7 @@
 
 -export([otp_6345_init/1, init_dont_hang_init/1]).
 
+-export([system_terminate/4]).
 
 -ifdef(STANDALONE).
 -define(line, noop, ).
@@ -49,7 +50,7 @@ suite() -> [{ct_hooks,[ts_install_cth]}].
 
 all() -> 
     [crash, {group, sync_start}, spawn_opt, hibernate,
-     {group, tickets}].
+     {group, tickets}, stop].
 
 groups() -> 
     [{tickets, [], [otp_6345, init_dont_hang]},
@@ -361,10 +362,94 @@ init_dont_hang(Config) when is_list(Config) ->
 	    exit(Error)
     end.
 
-init_dont_hang_init(Parent) ->
+init_dont_hang_init(_Parent) ->
     1 = 2.
 
+%% Test proc_lib:stop/1,3
+stop(_Config) ->
+    Parent = self(),
+    SysMsgProc =
+	fun() ->
+		receive
+		    {system,From,Request} ->
+			sys:handle_system_msg(Request,From,Parent,?MODULE,[],[])
+		end
+	end,
+
+    %% Normal case:
+    %% Process handles system message and terminated with given reason
+    Pid1 = proc_lib:spawn(SysMsgProc),
+    ok = proc_lib:stop(Pid1),
+    false = erlang:is_process_alive(Pid1),
+
+    %% Process does not exit
+    {'EXIT',noproc} = (catch proc_lib:stop(Pid1)),
+
+    %% Badly handled system message
+    DieProc =
+	fun() ->
+		receive
+		    {system,_From,_Request} ->
+			exit(die)
+		end
+	end,
+    Pid2 = proc_lib:spawn(DieProc),
+    {'EXIT',{die,_}} = (catch proc_lib:stop(Pid2)),
+
+    %% Hanging process => timeout
+    HangProc =
+	fun() ->
+		receive
+		    {system,_From,_Request} ->
+			timer:sleep(5000)
+		end
+	end,
+    Pid3 = proc_lib:spawn(HangProc),
+    {'EXIT',timeout} = (catch proc_lib:stop(Pid3,normal,1000)),
+
+    %% Success case with other reason than 'normal'
+    Pid4 = proc_lib:spawn(SysMsgProc),
+    ok = proc_lib:stop(Pid4,other_reason,infinity),
+    false = erlang:is_process_alive(Pid4),
+
+    %% System message is handled, but process dies with other reason
+    %% than the given (in system_terminate/4 below)
+    Pid5 = proc_lib:spawn(SysMsgProc),
+    {'EXIT',{badmatch,2}} = (catch proc_lib:stop(Pid5,crash,infinity)),
+    false = erlang:is_process_alive(Pid5),
+
+    %% Local registered name
+    Pid6 = proc_lib:spawn(SysMsgProc),
+    register(to_stop,Pid6),
+    ok = proc_lib:stop(to_stop),
+    undefined = whereis(to_stop),
+    false = erlang:is_process_alive(Pid6),
+
+    %% Remote registered name
+    {ok,Node} = test_server:start_node(proc_lib_SUITE_stop,slave,[]),
+    Dir = filename:dirname(code:which(?MODULE)),
+    rpc:call(Node,code,add_path,[Dir]),
+    Pid7 = spawn(Node,SysMsgProc),
+    true = rpc:call(Node,erlang,register,[to_stop,Pid7]),
+    Pid7 = rpc:call(Node,erlang,whereis,[to_stop]),
+    ok = proc_lib:stop({to_stop,Node}),
+    undefined = rpc:call(Node,erlang,whereis,[to_stop]),
+    false = rpc:call(Node,erlang,is_process_alive,[Pid7]),
+
+    %% Local and remote registered name, but non-existing
+    {'EXIT',noproc} = (catch proc_lib:stop(to_stop)),
+    {'EXIT',noproc} = (catch proc_lib:stop({to_stop,Node})),
+
+    true = test_server:stop_node(Node),
+    
+    %% Remote registered name, but non-existing node
+    {'EXIT',{{nodedown,Node},_}} = (catch proc_lib:stop({to_stop,Node})),
+    ok.
 
+system_terminate(crash,_Parent,_Deb,_State) ->
+    1 = 2;
+system_terminate(Reason,_Parent,_Deb,_State) ->
+    exit(Reason).
 
 %%-----------------------------------------------------------------
 %% The error_logger handler used.