diff options
Diffstat (limited to 'lib/stdlib/doc/src/gen_server.xml')
| -rw-r--r-- | lib/stdlib/doc/src/gen_server.xml | 114 |
1 files changed, 81 insertions, 33 deletions
diff --git a/lib/stdlib/doc/src/gen_server.xml b/lib/stdlib/doc/src/gen_server.xml index 7d137fc772..a4554d7657 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>2017</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>gen_server</module> + <module since="">gen_server</module> <modulesummary>Generic server behavior.</modulesummary> <description> <p>This behavior module provides the server of a client-server @@ -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,12 +90,19 @@ 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> <func> - <name>abcast(Name, Request) -> abcast</name> - <name>abcast(Nodes, Name, Request) -> abcast</name> + <name since="">abcast(Name, Request) -> abcast</name> + <name since="">abcast(Nodes, Name, Request) -> abcast</name> <fsummary>Send an asynchronous request to many generic servers.</fsummary> <type> <v>Nodes = [Node]</v> @@ -115,8 +124,8 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>call(ServerRef, Request) -> Reply</name> - <name>call(ServerRef, Request, Timeout) -> Reply</name> + <name since="">call(ServerRef, Request) -> Reply</name> + <name since="">call(ServerRef, Request, Timeout) -> Reply</name> <fsummary>Make a synchronous call to a generic server.</fsummary> <type> <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v> @@ -166,7 +175,7 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>cast(ServerRef, Request) -> ok</name> + <name since="">cast(ServerRef, Request) -> ok</name> <fsummary>Send an asynchronous request to a generic server.</fsummary> <type> <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v> @@ -191,10 +200,10 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>enter_loop(Module, Options, State)</name> - <name>enter_loop(Module, Options, State, ServerName)</name> - <name>enter_loop(Module, Options, State, Timeout)</name> - <name>enter_loop(Module, Options, State, ServerName, Timeout)</name> + <name since="">enter_loop(Module, Options, State)</name> + <name since="">enter_loop(Module, Options, State, ServerName)</name> + <name since="">enter_loop(Module, Options, State, Timeout)</name> + <name since="">enter_loop(Module, Options, State, ServerName, Timeout)</name> <fsummary>Enter the <c>gen_server</c> receive loop.</fsummary> <type> <v>Module = atom()</v> @@ -239,9 +248,9 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>multi_call(Name, Request) -> Result</name> - <name>multi_call(Nodes, Name, Request) -> Result</name> - <name>multi_call(Nodes, Name, Request, Timeout) -> Result</name> + <name since="">multi_call(Name, Request) -> Result</name> + <name since="">multi_call(Nodes, Name, Request) -> Result</name> + <name since="">multi_call(Nodes, Name, Request, Timeout) -> Result</name> <fsummary>Make a synchronous call to many generic servers.</fsummary> <type> <v>Nodes = [Node]</v> @@ -298,7 +307,7 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>reply(Client, Reply) -> Result</name> + <name since="">reply(Client, Reply) -> Result</name> <fsummary>Send a reply to a client.</fsummary> <type> <v>Client - see below</v> @@ -323,8 +332,8 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>start(Module, Args, Options) -> Result</name> - <name>start(ServerName, Module, Args, Options) -> Result</name> + <name since="">start(Module, Args, Options) -> Result</name> + <name since="">start(ServerName, Module, Args, Options) -> Result</name> <fsummary>Create a standalone <c>gen_server</c> process.</fsummary> <type> <v>ServerName = {local,Name} | {global,GlobalName}</v> @@ -352,8 +361,8 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>start_link(Module, Args, Options) -> Result</name> - <name>start_link(ServerName, Module, Args, Options) -> Result</name> + <name since="">start_link(Module, Args, Options) -> Result</name> + <name since="">start_link(ServerName, Module, Args, Options) -> Result</name> <fsummary>Create a <c>gen_server</c> process in a supervision tree. </fsummary> <type> @@ -457,8 +466,8 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>stop(ServerRef) -> ok</name> - <name>stop(ServerRef, Reason, Timeout) -> ok</name> + <name since="OTP 18.0">stop(ServerRef) -> ok</name> + <name since="OTP 18.0">stop(ServerRef, Reason, Timeout) -> ok</name> <fsummary>Synchronously stop a generic server.</fsummary> <type> <v>ServerRef = Name | {Name,Node} | {global,GlobalName}</v> @@ -477,8 +486,7 @@ gen_server:abcast -----> Module:handle_cast/2 with the expected reason. Any other reason than <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c> causes an error report to be issued using - <seealso marker="kernel:error_logger#format/2"> - <c>error_logger:format/2</c></seealso>. + <seealso marker="kernel:logger"><c>logger(3)</c></seealso>. The default <c>Reason</c> is <c>normal</c>.</p> <p><c>Timeout</c> is an integer greater than zero that specifies how many milliseconds to wait for the server to @@ -500,7 +508,7 @@ gen_server:abcast -----> Module:handle_cast/2 <funcs> <func> - <name>Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error, Reason}</name> + <name since="">Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error, Reason}</name> <fsummary>Update the internal state during upgrade/downgrade.</fsummary> <type> <v>OldVsn = Vsn | {down, Vsn}</v> @@ -542,7 +550,7 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:format_status(Opt, [PDict, State]) -> Status</name> + <name since="OTP R13B04">Module:format_status(Opt, [PDict, State]) -> Status</name> <fsummary>Optional function for providing a term describing the current <c>gen_server</c> status.</fsummary> <type> @@ -602,7 +610,7 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:handle_call(Request, From, State) -> Result</name> + <name since="">Module:handle_call(Request, From, State) -> Result</name> <fsummary>Handle a synchronous request.</fsummary> <type> <v>Request = term()</v> @@ -610,12 +618,15 @@ gen_server:abcast -----> Module:handle_cast/2 <v>State = term()</v> <v>Result = {reply,Reply,NewState} | {reply,Reply,NewState,Timeout}</v> <v> | {reply,Reply,NewState,hibernate}</v> + <v> | {reply,Reply,NewState,{continue,Continue}}</v> <v> | {noreply,NewState} | {noreply,NewState,Timeout}</v> <v> | {noreply,NewState,hibernate}</v> + <v> | {noreply,NewState,{continue,Continue}}</v> <v> | {stop,Reason,Reply,NewState} | {stop,Reason,NewState}</v> <v> Reply = term()</v> <v> NewState = term()</v> <v> Timeout = int()>=0 | infinity</v> + <v> Continue = term()</v> <v> Reason = term()</v> </type> <desc> @@ -666,16 +677,18 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:handle_cast(Request, State) -> Result</name> + <name since="">Module:handle_cast(Request, State) -> Result</name> <fsummary>Handle an asynchronous request.</fsummary> <type> <v>Request = term()</v> <v>State = term()</v> <v>Result = {noreply,NewState} | {noreply,NewState,Timeout}</v> <v> | {noreply,NewState,hibernate}</v> + <v> | {noreply,NewState,{continue,Continue}}</v> <v> | {stop,Reason,NewState}</v> <v> NewState = term()</v> <v> Timeout = int()>=0 | infinity</v> + <v> Continue = term()</v> <v> Reason = term()</v> </type> <desc> @@ -690,13 +703,49 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:handle_info(Info, State) -> Result</name> + <name since="OTP 21.0">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> | {noreply,NewState,hibernate}</v> + <v> | {noreply,NewState,{continue,Continue}}</v> + <v> | {stop,Reason,NewState}</v> + <v> NewState = term()</v> + <v> Timeout = int()>=0 | infinity</v> + <v> Continue = term()</v> + <v> 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 since="">Module:handle_info(Info, State) -> Result</name> <fsummary>Handle an incoming message.</fsummary> <type> <v>Info = timeout | term()</v> <v>State = term()</v> <v>Result = {noreply,NewState} | {noreply,NewState,Timeout}</v> <v> | {noreply,NewState,hibernate}</v> + <v> | {noreply,NewState,{continue,Continue}}</v> <v> | {stop,Reason,NewState}</v> <v> NewState = term()</v> <v> Timeout = int()>=0 | infinity</v> @@ -721,12 +770,12 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:init(Args) -> Result</name> + <name since="">Module:init(Args) -> Result</name> <fsummary>Initialize process and internal state.</fsummary> <type> <v>Args = term()</v> <v>Result = {ok,State} | {ok,State,Timeout} | {ok,State,hibernate}</v> - <v> | {stop,Reason} | ignore</v> + <v> | {ok,State,{continue,Continue}} | {stop,Reason} | ignore</v> <v> State = term()</v> <v> Timeout = int()>=0 | infinity</v> <v> Reason = term()</v> @@ -762,7 +811,7 @@ gen_server:abcast -----> Module:handle_cast/2 </func> <func> - <name>Module:terminate(Reason, State)</name> + <name since="">Module:terminate(Reason, State)</name> <fsummary>Clean up before termination.</fsummary> <type> <v>Reason = normal | shutdown | {shutdown,term()} | term()</v> @@ -811,8 +860,7 @@ gen_server:abcast -----> Module:handle_cast/2 <c>shutdown</c>, or <c>{shutdown,Term}</c>, the <c>gen_server</c> process is assumed to terminate because of an error and an error report is issued using - <seealso marker="kernel:error_logger#format/2"> - <c>error_logger:format/2</c></seealso>.</p> + <seealso marker="kernel:logger"><c>logger(3)</c></seealso>.</p> </desc> </func> </funcs> |