Merge pull request #1490 from josevalim/jv-gen-server-continue

Add {continue, Term} and handle_continue/2 to gen_server

5 files changed, 184 insertions, 26 deletions

diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml
index 7d137fc772..da74e793e6 100644
--- a/lib/stdlib/doc/src/gen_server.xml
+++ b/lib/stdlib/doc/src/gen_server.xml
@@ -60,6 +60,8 @@ gen_server:abcast     -----> Module:handle_cast/2
 
 -                     -----> Module:handle_info/2
 
+-                     -----> Module:handle_continue/2
+
 -                     -----> Module:terminate/2
 
 -                     -----> Module:code_change/3</pre>
@@ -88,6 +90,13 @@ gen_server:abcast     -----> Module:handle_cast/2
       implies at least two garbage collections (when hibernating and
       shortly after waking up) and is not something you want to do
       between each call to a busy server.</p>
+
+    <p>If the <c>gen_server</c> process needs to perform an action
+      immediately after initialization or to break the execution of a
+      callback into multiple steps, it can return <c>{continue,Continue}</c>
+      in place of the time-out or hibernation value, which will immediately
+      invoke the <c>handle_continue/2</c> callback.</p>
+
   </description>
 
   <funcs>
@@ -610,12 +619,15 @@ gen_server:abcast     -----> Module:handle_cast/2
         <v>State = term()</v>
         <v>Result = {reply,Reply,NewState} | {reply,Reply,NewState,Timeout}</v> 
         <v>&nbsp;&nbsp;| {reply,Reply,NewState,hibernate}</v>
+        <v>&nbsp;&nbsp;| {reply,Reply,NewState,{continue,Continue}}</v>
         <v>&nbsp;&nbsp;| {noreply,NewState} | {noreply,NewState,Timeout}</v> 
         <v>&nbsp;&nbsp;| {noreply,NewState,hibernate}</v>
+        <v>&nbsp;&nbsp;| {noreply,NewState,{continue,Continue}}</v>
         <v>&nbsp;&nbsp;| {stop,Reason,Reply,NewState} | {stop,Reason,NewState}</v>
         <v>&nbsp;Reply = term()</v>
         <v>&nbsp;NewState = term()</v>
         <v>&nbsp;Timeout = int()>=0 | infinity</v>
+        <v>&nbsp;Continue = term()</v>
         <v>&nbsp;Reason = term()</v>
       </type>
       <desc>
@@ -673,9 +685,11 @@ gen_server:abcast     -----> Module:handle_cast/2
         <v>State = term()</v>
         <v>Result = {noreply,NewState} | {noreply,NewState,Timeout}</v>
         <v>&nbsp;&nbsp;| {noreply,NewState,hibernate}</v>
+        <v>&nbsp;&nbsp;| {noreply,NewState,{continue,Continue}}</v>
         <v>&nbsp;&nbsp;| {stop,Reason,NewState}</v>
         <v>&nbsp;NewState = term()</v>
         <v>&nbsp;Timeout = int()>=0 | infinity</v>
+        <v>&nbsp;Continue = term()</v>
         <v>&nbsp;Reason = term()</v>
       </type>
       <desc>
@@ -690,6 +704,41 @@ gen_server:abcast     -----> Module:handle_cast/2
     </func>
 
     <func>
+      <name>Module:handle_continue(Continue, State) -> Result</name>
+      <fsummary>Handle a continue instruction.</fsummary>
+      <type>
+        <v>Continue = term()</v>
+        <v>State = term()</v>
+        <v>Result = {noreply,NewState} | {noreply,NewState,Timeout}</v>
+        <v>&nbsp;&nbsp;| {noreply,NewState,hibernate}</v>
+        <v>&nbsp;&nbsp;| {noreply,NewState,{continue,Continue}}</v>
+        <v>&nbsp;&nbsp;| {stop,Reason,NewState}</v>
+        <v>&nbsp;NewState = term()</v>
+        <v>&nbsp;Timeout = int()>=0 | infinity</v>
+        <v>&nbsp;Continue = term()</v>
+        <v>&nbsp;Reason = normal | term()</v>
+      </type>
+      <desc>
+        <note>
+          <p>This callback is optional, so callback modules need to
+            export it only if they return <c>{continue,Continue}</c>
+            from another callback. If continue is used and the callback
+            is not implemented, the process will exit with <c>undef</c>
+            error.</p>
+        </note>
+        <p>This function is called by a <c>gen_server</c> process whenever
+          a previous callback returns <c>{continue, Continue}</c>.
+          <c>handle_continue/2</c> is invoked immediately after the previous
+          callback, which makes it useful for performing work after
+          initialization or for splitting the work in a callback in
+          multiple steps, updating the process state along the way.</p>
+        <p>For a description of the other arguments and possible return values,
+          see <seealso marker="#Module:handle_call/3">
+          <c>Module:handle_call/3</c></seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
       <name>Module:handle_info(Info, State) -> Result</name>
       <fsummary>Handle an incoming message.</fsummary>
       <type>
@@ -697,6 +746,7 @@ gen_server:abcast     -----> Module:handle_cast/2
         <v>State = term()</v>
         <v>Result = {noreply,NewState} | {noreply,NewState,Timeout}</v>
         <v>&nbsp;&nbsp;| {noreply,NewState,hibernate}</v>
+        <v>&nbsp;&nbsp;| {noreply,NewState,{continue,Continue}}</v>
         <v>&nbsp;&nbsp;| {stop,Reason,NewState}</v>
         <v>&nbsp;NewState = term()</v>
         <v>&nbsp;Timeout = int()>=0 | infinity</v>
@@ -726,7 +776,7 @@ gen_server:abcast     -----> Module:handle_cast/2
       <type>
         <v>Args = term()</v>
         <v>Result =  {ok,State} | {ok,State,Timeout} | {ok,State,hibernate}</v>
-        <v>&nbsp;| {stop,Reason} | ignore</v>
+        <v>&nbsp;| {ok,State,{continue,Continue}} | {stop,Reason} | ignore</v>
         <v>&nbsp;State = term()</v>
         <v>&nbsp;Timeout = int()>=0 | infinity</v>
         <v>&nbsp;Reason = term()</v>
diff --git a/lib/stdlib/src/gen_server.erl b/lib/stdlib/src/gen_server.erl
index a3d53efd0d..48ef1c987a 100644
--- a/lib/stdlib/src/gen_server.erl
+++ b/lib/stdlib/src/gen_server.erl
@@ -116,23 +116,27 @@
 %%%=========================================================================
 
 -callback init(Args :: term()) ->
-    {ok, State :: term()} | {ok, State :: term(), timeout() | hibernate} |
+    {ok, State :: term()} | {ok, State :: term(), timeout() | hibernate | {continue, term()}} |
     {stop, Reason :: term()} | ignore.
 -callback handle_call(Request :: term(), From :: {pid(), Tag :: term()},
                       State :: term()) ->
     {reply, Reply :: term(), NewState :: term()} |
-    {reply, Reply :: term(), NewState :: term(), timeout() | hibernate} |
+    {reply, Reply :: term(), NewState :: term(), timeout() | hibernate | {continue, term()}} |
     {noreply, NewState :: term()} |
-    {noreply, NewState :: term(), timeout() | hibernate} |
+    {noreply, NewState :: term(), timeout() | hibernate | {continue, term()}} |
     {stop, Reason :: term(), Reply :: term(), NewState :: term()} |
     {stop, Reason :: term(), NewState :: term()}.
 -callback handle_cast(Request :: term(), State :: term()) ->
     {noreply, NewState :: term()} |
-    {noreply, NewState :: term(), timeout() | hibernate} |
+    {noreply, NewState :: term(), timeout() | hibernate | {continue, term()}} |
     {stop, Reason :: term(), NewState :: term()}.
 -callback handle_info(Info :: timeout | term(), State :: term()) ->
     {noreply, NewState :: term()} |
-    {noreply, NewState :: term(), timeout() | hibernate} |
+    {noreply, NewState :: term(), timeout() | hibernate | {continue, term()}} |
+    {stop, Reason :: term(), NewState :: term()}.
+-callback handle_continue(Info :: term(), State :: term()) ->
+    {noreply, NewState :: term()} |
+    {noreply, NewState :: term(), timeout() | hibernate | {continue, term()}} |
     {stop, Reason :: term(), NewState :: term()}.
 -callback terminate(Reason :: (normal | shutdown | {shutdown, term()} |
                                term()),
@@ -149,7 +153,7 @@
       Status :: term().
 
 -optional_callbacks(
-    [handle_info/2, terminate/2, code_change/3, format_status/2]).
+    [handle_info/2, handle_continue/2, terminate/2, code_change/3, format_status/2]).
 
 %%%  -----------------------------------------------------------------
 %%% Starts a generic server.
@@ -309,7 +313,7 @@ enter_loop(Mod, Options, State, ServerName, Timeout) ->
     Name = gen:get_proc_name(ServerName),
     Parent = gen:get_parent(),
     Debug = gen:debug_options(Name, Options),
-	HibernateAfterTimeout = gen:hibernate_after(Options),
+    HibernateAfterTimeout = gen:hibernate_after(Options),
     loop(Parent, Name, State, Mod, Timeout, HibernateAfterTimeout, Debug).
 
 %%%========================================================================
@@ -374,6 +378,19 @@ init_it(Mod, Args) ->
 %%% ---------------------------------------------------
 %%% The MAIN loop.
 %%% ---------------------------------------------------
+
+loop(Parent, Name, State, Mod, {continue, Continue} = Msg, HibernateAfterTimeout, Debug) ->
+    Reply = try_dispatch(Mod, handle_continue, Continue, State),
+    case Debug of
+	[] ->
+	    handle_common_reply(Reply, Parent, Name, undefined, Msg, Mod,
+				HibernateAfterTimeout, State);
+	_ ->
+	    Debug1 = sys:handle_debug(Debug, fun print_event/3, Name, Msg),
+	    handle_common_reply(Reply, Parent, Name, undefined, Msg, Mod,
+				HibernateAfterTimeout, State, Debug1)
+    end;
+
 loop(Parent, Name, State, Mod, hibernate, HibernateAfterTimeout, Debug) ->
     proc_lib:hibernate(?MODULE,wake_hib,[Parent, Name, State, Mod, HibernateAfterTimeout, Debug]);
 
diff --git a/lib/stdlib/test/erl_internal_SUITE.erl b/lib/stdlib/test/erl_internal_SUITE.erl
index 789a9d4363..7d9df1f989 100644
--- a/lib/stdlib/test/erl_internal_SUITE.erl
+++ b/lib/stdlib/test/erl_internal_SUITE.erl
@@ -80,7 +80,7 @@ callbacks(application) ->
 callbacks(gen_server) ->
     [{init,1}, {handle_call,3}, {handle_cast,2},
      {handle_info,2}, {terminate,2}, {code_change,3},
-     {format_status,2}];
+     {format_status,2}, {handle_continue, 2}];
 callbacks(gen_fsm) ->
     [{init,1}, {handle_event,3}, {handle_sync_event,4},
      {handle_info,3}, {terminate,3}, {code_change,4},
@@ -101,7 +101,7 @@ callbacks(supervisor) ->
 optional_callbacks(application) ->
     [];
 optional_callbacks(gen_server) ->
-    [{handle_info, 2}, {terminate, 2}, {code_change, 3}, {format_status, 2}];
+    [{handle_info, 2}, {handle_continue, 2}, {terminate, 2}, {code_change, 3}, {format_status, 2}];
 optional_callbacks(gen_fsm) ->
     [{handle_info, 3}, {terminate, 3}, {code_change, 4}, {format_status, 2}];
 optional_callbacks(gen_event) ->
diff --git a/lib/stdlib/test/gen_server_SUITE.erl b/lib/stdlib/test/gen_server_SUITE.erl
index 2e9dc4d4fb..2bc220fef2 100644
--- a/lib/stdlib/test/gen_server_SUITE.erl
+++ b/lib/stdlib/test/gen_server_SUITE.erl
@@ -27,7 +27,7 @@
 -export([all/0, suite/0,groups/0,init_per_suite/1, end_per_suite/1, 
 	 init_per_group/2,end_per_group/2]).
 -export([start/1, crash/1, call/1, cast/1, cast_fast/1,
-	 info/1, abcast/1, multicall/1, multicall_down/1,
+	 continue/1, info/1, abcast/1, multicall/1, multicall_down/1,
 	 call_remote1/1, call_remote2/1, call_remote3/1,
 	 call_remote_n1/1, call_remote_n2/1, call_remote_n3/1, spec_init/1,
 	 spec_init_local_registered_parent/1, 
@@ -37,7 +37,8 @@
 	 get_state/1, replace_state/1, call_with_huge_message_queue/1,
 	 undef_handle_call/1, undef_handle_cast/1, undef_handle_info/1,
 	 undef_init/1, undef_code_change/1, undef_terminate1/1,
-	 undef_terminate2/1, undef_in_terminate/1, undef_in_handle_info/1
+	 undef_terminate2/1, undef_in_terminate/1, undef_in_handle_info/1,
+	 undef_handle_continue/1
 	]).
 
 -export([stop1/1, stop2/1, stop3/1, stop4/1, stop5/1, stop6/1, stop7/1,
@@ -52,7 +53,7 @@
 
 
 %% The gen_server behaviour
--export([init/1, handle_call/3, handle_cast/2,
+-export([init/1, handle_call/3, handle_cast/2, handle_continue/2,
 	 handle_info/2, code_change/3, terminate/2, format_status/2]).
 
 suite() ->
@@ -61,7 +62,7 @@ suite() ->
 
 all() -> 
     [start, {group,stop}, crash, call, cast, cast_fast, info, abcast,
-     multicall, multicall_down, call_remote1, call_remote2,
+     continue, multicall, multicall_down, call_remote1, call_remote2,
      call_remote3, call_remote_n1, call_remote_n2,
      call_remote_n3, spec_init,
      spec_init_local_registered_parent,
@@ -76,7 +77,7 @@ groups() ->
     [{stop, [],
       [stop1, stop2, stop3, stop4, stop5, stop6, stop7, stop8, stop9, stop10]},
      {undef_callbacks, [],
-      [undef_handle_call, undef_handle_cast, undef_handle_info,
+      [undef_handle_call, undef_handle_cast, undef_handle_info, undef_handle_continue,
        undef_init, undef_code_change, undef_terminate1, undef_terminate2]}].
 
 
@@ -458,6 +459,47 @@ call(Config) when is_list(Config) ->
     ok.
 
 %% --------------------------------------
+%% Test handle_continue.
+%% --------------------------------------
+
+continue(Config) when is_list(Config) ->
+    {ok, Pid} = gen_server:start_link(gen_server_SUITE, {continue, self()}, []),
+    [{Pid, continue}, {Pid, after_continue}] = read_replies(Pid),
+
+    gen_server:call(Pid, {continue_reply, self()}),
+    [{Pid, continue}, {Pid, after_continue}] = read_replies(Pid),
+
+    gen_server:call(Pid, {continue_noreply, self()}),
+    [{Pid, continue}, {Pid, after_continue}] = read_replies(Pid),
+
+    gen_server:cast(Pid, {continue_noreply, self()}),
+    [{Pid, continue}, {Pid, after_continue}] = read_replies(Pid),
+
+    Pid ! {continue_noreply, self()},
+    [{Pid, continue}, {Pid, after_continue}] = read_replies(Pid),
+
+    Pid ! {continue_continue, self()},
+    [{Pid, before_continue}, {Pid, continue}, {Pid, after_continue}] = read_replies(Pid),
+
+    Ref = monitor(process, Pid),
+    Pid ! continue_stop,
+    verify_down_reason(Ref, Pid, normal).
+
+read_replies(Pid) ->
+    receive
+	{Pid, ack} -> read_replies()
+    after
+	1000 -> ct:fail({continue, ack})
+    end.
+
+read_replies() ->
+    receive
+	Msg -> [Msg | read_replies()]
+    after
+	0 -> []
+    end.
+
+%% --------------------------------------
 %% Test call to nonexisting processes on remote nodes
 %% --------------------------------------
 
@@ -1346,7 +1388,7 @@ echo_loop() ->
 %% Test the default implementation of terminate if the callback module
 %% does not export it
 undef_terminate1(Config) when is_list(Config) ->
-    {ok, Server} = gen_server:start(oc_server, [], []),
+    {ok, Server} = oc_server:start(),
     MRef = monitor(process, Server),
     ok = gen_server:stop(Server),
     ok = verify_down_reason(MRef, Server, normal).
@@ -1354,7 +1396,7 @@ undef_terminate1(Config) when is_list(Config) ->
 %% Test the default implementation of terminate if the callback module
 %% does not export it
 undef_terminate2(Config) when is_list(Config) ->
-    {ok, Server} = gen_server:start(oc_server, [], []),
+    {ok, Server} = oc_server:start(),
     MRef = monitor(process, Server),
     ok = gen_server:stop(Server, {error, test}, infinity),
     ok = verify_down_reason(MRef, Server, {error, test}).
@@ -1377,7 +1419,7 @@ undef_init(_Config) ->
 %% The upgrade should fail if code_change is expected in the callback module
 %% but not exported, but the server should continue with the old code
 undef_code_change(Config) when is_list(Config) ->
-    {ok, Server} = gen_server:start(oc_server, [], []),
+    {ok, Server} = oc_server:start(),
     {error, {'EXIT', {undef, [{oc_server, code_change, [_, _, _], _}|_]}}}
         = fake_upgrade(Server, ?MODULE),
     true = is_process_alive(Server).
@@ -1385,7 +1427,7 @@ undef_code_change(Config) when is_list(Config) ->
 %% The server should crash if the handle_call callback is
 %% not exported in the callback module
 undef_handle_call(_Config) ->
-    {ok, Server} = gen_server:start(oc_server, [], []),
+    {ok, Server} = oc_server:start(),
     try
         gen_server:call(Server, call_msg),
         ct:fail(should_crash)
@@ -1397,17 +1439,25 @@ undef_handle_call(_Config) ->
 %% The server should crash if the handle_cast callback is
 %% not exported in the callback module
 undef_handle_cast(_Config) ->
-    {ok, Server} = gen_server:start(oc_server, [], []),
+    {ok, Server} = oc_server:start(),
     MRef = monitor(process, Server),
     gen_server:cast(Server, cast_msg),
     verify_undef_down(MRef, Server, oc_server, handle_cast),
     ok.
 
+%% The server should crash if the handle_continue callback is
+%% not exported in the callback module
+undef_handle_continue(_Config) ->
+    {ok, Server} = oc_server:start(continue),
+    MRef = monitor(process, Server),
+    verify_undef_down(MRef, Server, oc_server, handle_continue),
+    ok.
+
 %% The server should log but not crash if the handle_info callback is
 %% calling an undefined function
 undef_handle_info(Config) when is_list(Config) ->
     error_logger_forwarder:register(),
-    {ok, Server} = gen_server:start(oc_server, [], []),
+    {ok, Server} = oc_server:start(),
     Server ! hej,
     wait_until_processed(Server, hej, 10),
     true = is_process_alive(Server),
@@ -1570,8 +1620,11 @@ init(hibernate) ->
 init(sleep) ->
     ct:sleep(1000),
     {ok, []};
+init({continue, Pid}) ->
+    self() ! {after_continue, Pid},
+    {ok, [], {continue, {message, Pid}}};
 init({state,State}) ->
-    {ok, State}.
+    {ok,State}.
 
 handle_call(started_p, _From, State) ->
     io:format("FROZ"),
@@ -1604,6 +1657,12 @@ handle_call(shutdown_reason, _From, _State) ->
 handle_call({call_undef_fun, Mod, Fun}, _From, State) ->
     Mod:Fun(),
     {reply, ok, State};
+handle_call({continue_reply, Pid}, _From, State) ->
+    self() ! {after_continue, Pid},
+    {reply, ok, State, {continue, {message, Pid}}};
+handle_call({continue_noreply, Pid}, From, State) ->
+    self() ! {after_continue, Pid},
+    {noreply, State, {continue, {message, Pid, From}}};
 handle_call(stop_shutdown_reason, _From, State) ->
     {stop,{shutdown,stop_reason},State}.
 
@@ -1620,6 +1679,9 @@ handle_cast(hibernate_later, _State) ->
 handle_cast({call_undef_fun, Mod, Fun}, State) ->
     Mod:Fun(),
     {noreply, State};
+handle_cast({continue_noreply, Pid}, State) ->
+    self() ! {after_continue, Pid},
+    {noreply, State, {continue, {message, Pid}}};
 handle_cast({From, stop}, State) ->
     io:format("BAZ"),
     {stop, {From,stopped}, State}.
@@ -1657,9 +1719,34 @@ handle_info(continue, From) ->
     {noreply, []};
 handle_info({From, stop}, State) ->
     {stop, {From,stopped_info}, State};
+handle_info({after_continue, Pid}, State) ->
+    Pid ! {self(), after_continue},
+    Pid ! {self(), ack},
+    {noreply, State};
+handle_info({continue_noreply, Pid}, State) ->
+    self() ! {after_continue, Pid},
+    {noreply, State, {continue, {message, Pid}}};
+handle_info({continue_continue, Pid}, State) ->
+    {noreply, State, {continue, {continue, Pid}}};
+handle_info(continue_stop, State) ->
+    {noreply, State, {continue, stop}};
 handle_info(_Info, State) ->
     {noreply, State}.
 
+handle_continue({continue, Pid}, State) ->
+    Pid ! {self(), before_continue},
+    self() ! {after_continue, Pid},
+    {noreply, State, {continue, {message, Pid}}};
+handle_continue(stop, State) ->
+    {stop, normal, State};
+handle_continue({message, Pid}, State) ->
+    Pid ! {self(), continue},
+    {noreply, State};
+handle_continue({message, Pid, From}, State) ->
+    Pid ! {self(), continue},
+    gen_server:reply(From, ok),
+    {noreply, State}.
+
 code_change(_OldVsn,
             {new, {undef_in_code_change, {Mod, Fun}}} = State,
             _Extra) ->
diff --git a/lib/stdlib/test/gen_server_SUITE_data/oc_server.erl b/lib/stdlib/test/gen_server_SUITE_data/oc_server.erl
index 4ba37987f3..7b92a49bf6 100644
--- a/lib/stdlib/test/gen_server_SUITE_data/oc_server.erl
+++ b/lib/stdlib/test/gen_server_SUITE_data/oc_server.erl
@@ -22,7 +22,7 @@
 -behaviour(gen_server).
 
 %% API
--export([start/0]).
+-export([start/0, start/1]).
 
 %% gen_server callbacks
 -export([init/1]).
@@ -30,8 +30,12 @@
 -record(state, {}).
 
 start() ->
-    gen_server:start({local, ?MODULE}, ?MODULE, [], []).
+    gen_server:start(?MODULE, ok, []).
 
-init([]) ->
-    {ok, #state{}}.
+start(continue) ->
+    gen_server:start(?MODULE, continue, []).
 
+init(ok) ->
+    {ok, #state{}};
+init(continue) ->
+    {ok, #state{}, {continue, continue}}.