File: gen_server.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (724 lines) | stat: -rw-r--r-- 29,346 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>gen_server</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>gen_server</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
gen_server
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Generic Server Behaviour
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>A behaviour module for implementing the server of a client-server
relation. A generic server process (gen_server) implemented using this
module will have a standard set of interface functions and include
functionality for tracing and error reporting. It will also fit into
an OTP supervision tree. Refer to <STRONG>OTP Design Principles</STRONG> for
more information.
<P>A gen_server assumes all specific parts to be located in a callback
module exporting a pre-defined set of functions. The relationship
between the behaviour functions and the callback functions can be
illustrated as follows:
<PRE>
gen_server module            Callback module
-----------------            ---------------
gen_server:start_link -----&#62; Module:init/1

gen_server:call
gen_server:multi_call -----&#62; Module:handle_call/3

gen_server:cast
gen_server:abcast     -----&#62; Module:handle_cast/2

-                     -----&#62; Module:handle_info/2

-                     -----&#62; Module:terminate/2

-                     -----&#62; Module:code_change/3
</PRE>

<P>If a callback function fails or returns a bad value, the gen_server
will terminate.
<P>The <CODE>sys</CODE> module can be used for debugging a gen_server.
<P>Note that a gen_server does not trap exit signals automatically,
this must be explicitly initiated in the callback module.
<P>Unless otherwise stated, all functions in this module fail if
the specified gen_server does not exist or if bad arguments are given.

</DIV>

<H3>EXPORTS</H3>

<P><A NAME="start_link/3"><STRONG><CODE>start_link(Module, Args, Options) -&#62; Result</CODE></STRONG></A><BR>
<A NAME="start_link/4"><STRONG><CODE>start_link(ServerName, Module, Args, Options) -&#62; Result
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>ServerName = {local,Name} | {global,GlobalName}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = {debug,Dbgs} | {timeout,Time} |
         {spawn_opt,SOpts}</CODE></STRONG><BR>
<STRONG><CODE>Dbgs = [Dbg]</CODE></STRONG><BR>
<STRONG><CODE>Dbg = trace | log | statistics |
         {log_to_file,FileName} | {install,{Func,FuncState}}</CODE></STRONG><BR>
<STRONG><CODE>SOpts = [term()]</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Pid} | ignore | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>Error = {already_started,Pid} | term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Creates a gen_server process as part of a supervision tree.
         The function should be called, directly or indirectly, by
         the supervisor. It will, among other things, ensure that
         the gen_server is linked to the supervisor.
<P>The gen_server process calls <CODE>Module:init/1</CODE> to
         initialize. To ensure a synchronized start-up procedure,
         <CODE>start_link/3,4</CODE> does not return until
         <CODE>Module:init/1</CODE> has returned.
<P>If <CODE>ServerName={local,Name}</CODE> the gen_server is
         registered locally as <CODE>Name</CODE> using <CODE>register/2</CODE>.
         If <CODE>ServerName={global,GlobalName}</CODE> the gen_server is
         registered globally as <CODE>GlobalName</CODE> using
         <CODE>global:register_name/2</CODE>. If no name is provided,
         the gen_server is not registered.
<P><CODE>Module</CODE> is the name of the callback module.
<P><CODE>Args</CODE> is an arbitrary term which is passed as
         the argument to <CODE>Module:init/1</CODE>.
<P>If the option <CODE>{timeout,Time}</CODE> is present,
         the gen_server is allowed to spend <CODE>Time</CODE> milliseconds
         initializing or it will be terminated and the start function
         will return <CODE>{error,timeout}</CODE>.
<P>If the option <CODE>{debug,Dbgs}</CODE> is present,
         the corresponding <CODE>sys</CODE> function will be called for each
         item in <CODE>Dbgs</CODE>. Refer to <CODE>sys(3)</CODE> for more
         information.
<P>If the option <CODE>{spawn_opt,SOpts}</CODE> is present,
         <CODE>SOpts</CODE> will be passed as option list to
         the <CODE>spawn_opt</CODE> BIF which is used to spawn
         the gen_server. Refer to <CODE>erlang(3)</CODE> for information
         about the <CODE>spawn_opt</CODE> options.
<P>If the gen_server is successfully created and initialized
         the function returns <CODE>{ok,Pid}</CODE>, where <CODE>Pid</CODE> is
         the pid of the gen_server. If there already exists a process
         with the specified <CODE>ServerName</CODE> the function returns
         <CODE>{error,{already_started,Pid}}</CODE>, where <CODE>Pid</CODE> is
         the pid of that process.
<P>If <CODE>Module:init/1</CODE> fails with <CODE>Reason</CODE>,
         the function returns <CODE>{error,Reason}</CODE>. If
         <CODE>Module:init/1</CODE> returns <CODE>{stop,Reason}</CODE> or
         <CODE>ignore</CODE>, the process is terminated and the function
         returns <CODE>{error,Reason}</CODE> or <CODE>ignore</CODE>, respectively.
        
</DIV>

<P><A NAME="start/3"><STRONG><CODE>start(Module, Args, Options) -&#62; Result</CODE></STRONG></A><BR>
<A NAME="start/4"><STRONG><CODE>start(ServerName, Module, Args, Options) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>ServerName = {local,Name} | {global,GlobalName}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = {debug,Dbgs} | {timeout,Time} |
         {spawn_opt,SOpts}</CODE></STRONG><BR>
<STRONG><CODE>Dbgs = [Dbg]</CODE></STRONG><BR>
<STRONG><CODE>Dbg = trace | log | statistics |
         {log_to_file,FileName} | {install,{Func,FuncState}}</CODE></STRONG><BR>
<STRONG><CODE>SOpts = [term()]</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Pid} | ignore | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>Error = {already_started,Pid} | term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Creates a stand-alone gen_server process, i.e. a gen_server
         which is not part of a supervision tree and thus has no
         supervisor.
<P>See <CODE>start_link/3,4</CODE> for a description of arguments and
         return values.
</DIV>

<P><A NAME="call/2"><STRONG><CODE>call(ServerRef, Request) -&#62; Reply</CODE></STRONG></A><BR>
<A NAME="call/3"><STRONG><CODE>call(ServerRef, Request, Timeout) -&#62; Reply</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Request = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Makes a synchronous call to the gen_server <CODE>ServerRef</CODE> by
         sending a request and waiting until a reply arrives or a timout
         occurs. The gen_server will call <CODE>Module:handle_call/3</CODE> to
         handle the request.
<P><CODE>ServerRef</CODE> can be:
<P>
<UL>

<LI>
the pid,
</LI>


<LI>
<CODE>Name</CODE>, if the gen_server is locally registered,
</LI>


<LI>
<CODE>{Name,Node}</CODE>, if the gen_server is locally
         registered at another node, or
</LI>


<LI>
<CODE>{global,GlobalName}</CODE>, if the gen_server is globally
         registered.
</LI>


</UL>

<P><CODE>Request</CODE> is an arbitrary term which is passed as one of
         the arguments to <CODE>Module:handle_call/3</CODE>.
<P><CODE>Timeout</CODE> is an integer greater than zero which specifies
         how many milliseconds to wait for a reply, or the atom
         <CODE>infinity</CODE> to wait indefinitely. Default value is 5000.
         If no reply is received within the specified time, the function
         call fails.
<P>The return value <CODE>Reply</CODE> is defined in the return value of
         <CODE>Module:handle_call/3</CODE>.
<P>The call may fail for several reasons, including timeout and the
         called gen_server dying before or during the call.
<P>There is a special case for backwards compatibility. If
<P>
<UL>

<LI>
the client is linked to the gen server, and
</LI>


<LI>
the client is trapping exits, and
</LI>


<LI>
the gen_server terminates while handling the
         request
</LI>


</UL>

<P>then the exit message is removed from the client's receive queue 
before the function call fails. This special-case behaviour may be
removed in the future because it is inconsistent with the behaviour
when a gen_server dies between calls and also because the exit 
message cannot be removed in some circumstances, for instance when
<CODE>ServerRef = {Name, Node}</CODE> and <CODE>Node</CODE> goes down.
</DIV>

<P><A NAME="multi_call/2"><STRONG><CODE>multi_call(Name, Request) -&#62; Result</CODE></STRONG></A><BR>
<A NAME="multi_call/3"><STRONG><CODE>multi_call(Nodes, Name, Request) -&#62; Result</CODE></STRONG></A><BR>
<A NAME="multi_call/4"><STRONG><CODE>multi_call(Nodes, Name, Request, Timeout) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Nodes = [Node]</CODE></STRONG><BR>
<STRONG><CODE>Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>Request = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;=0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Result = {Replies,BadNodes}</CODE></STRONG><BR>
<STRONG><CODE>Replies = [{Node,Reply}]</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>
<STRONG><CODE>BadNodes = [Node]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Makes a synchronous call to all gen_servers locally registered as
         <CODE>Name</CODE> at the specified nodes by first sending a request to
         every node and then waiting for the replies. The gen_servers will
         call <CODE>Module:handle_call/3</CODE> to handle the request.
<P>The function returns a tuple <CODE>{Replies,BadNodes}</CODE> where
         <CODE>Replies</CODE> is a list of <CODE>{Node,Reply}</CODE> and <CODE>BadNodes</CODE>
         is a list of node that either did not exist, or where
         the gen_server <CODE>Name</CODE> did not exist or did not reply.
<P><CODE>Nodes</CODE> is a list of node names to which the request
         should be sent. Default value is the list of all known nodes
         <CODE>[node()|nodes()]</CODE>.
<P><CODE>Name</CODE> is the locally registered name of each gen_server.
<P><CODE>Request</CODE> is an arbitrary term which is passed as one of
         the arguments to <CODE>Module:handle_call/3</CODE>.
<P><CODE>Timeout</CODE> is an integer greater than zero which specifies
         how many milliseconds to wait for each reply, or the atom
         <CODE>infinity</CODE> to wait indefinitely. Default value is
         <CODE>infinity</CODE>. If no reply is received from a node within
         the specified time, the node is added to <CODE>BadNodes</CODE>.
<P>When a reply <CODE>Reply</CODE> is received from the gen_server at a
         node <CODE>Node</CODE>, <CODE>{Node,Reply}</CODE> is added to <CODE>Replies</CODE>.
         <CODE>Reply</CODE> is defined in the return value of
         <CODE>Module:handle_call/3</CODE>.
<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Warning!" SRC="warning.gif"></TD>
    <TD>

<P>If one of the nodes is running Erlang/OTP R6B or older, and
         the gen_server is not started when the requests are sent, but
         starts within 2 seconds, this function waits the whole
         <CODE>Timeout</CODE>, which may be infinity.
<P>This problem does not exist if all nodes are running Erlang/OTP
         R7B or later.    </TD>
  </TR>
</TABLE>

<P>This function does <STRONG>not</STRONG> read out any exit messages 
         like <CODE>call/2,3</CODE> does.
<P>The previously undocumented functions <CODE>safe_multi_call/2,3,4</CODE>
         were removed in OTP R7B/Erlang 5.0 since this function is now safe,
         except in the case mentioned above.
<P>To avoid that late answers (after the timeout) pollutes
         the caller's message queue, a middleman process is used to
         do the actual calls. Late answers will then be discarded
         when they arrive to a terminated process.
</DIV>

<P><A NAME="cast/2"><STRONG><CODE>cast(ServerRef, Request) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>ServerRef = Name | {Name,Node} | {global,GlobalName} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Request = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sends an asynchronous request to the gen_server <CODE>ServerRef</CODE>
         and returns <CODE>ok</CODE> immediately, ignoring if the destination
         node or gen_server does not exist. The gen_server will call
         <CODE>Module:handle_cast/2</CODE> to handle the request.
<P>See <CODE>call/2,3</CODE> for a description of <CODE>ServerRef</CODE>.
<P><CODE>Request</CODE> is an arbitrary term which is passed as one
         of the arguments to <CODE>Module:handle_cast/2</CODE>.
</DIV>

<P><A NAME="abcast/2"><STRONG><CODE>abcast(Name, Request) -&#62; abcast</CODE></STRONG></A><BR>
<A NAME="abcast/3"><STRONG><CODE>abcast(Nodes, Name, Request) -&#62; abcast</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Nodes = [Node]</CODE></STRONG><BR>
<STRONG><CODE>Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>Request = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sends an asynchronous request to the gen_servers locally
         registered as <CODE>Name</CODE> at the specified nodes. The function
         returns immediately and ignores nodes that does not exist, or
         where the gen_server <CODE>Name</CODE> does not exist. The gen_servers
         will call <CODE>Module:handle_cast/2</CODE> to handle the request.
<P>See <CODE>multi_call/2,3,4</CODE> for a description of the arguments.
        
</DIV>

<P><A NAME="reply/2"><STRONG><CODE>reply(Client, Reply) -&#62; true</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Client - see below</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function can be used by a gen_server to explicitly send a
         reply to a client that called <CODE>call</CODE> or <CODE>multi_call</CODE>,
         when the reply cannot be defined in the return value of
         <CODE>Module:handle_call/3</CODE>.
<P><CODE>Client</CODE> must be the <CODE>From</CODE> argument provided to
         the callback function. <CODE>Reply</CODE> is an arbitrary term, which
         will be given back to the client as the return value of <CODE>call</CODE>
         or <CODE>multi_call</CODE>.
</DIV>

<P><A NAME="enter_loop/3"><STRONG><CODE>enter_loop(Module, Options, State)</CODE></STRONG></A><BR>
<A NAME="enter_loop/4"><STRONG><CODE>enter_loop(Module, Options, State, ServerName)</CODE></STRONG></A><BR>
<A NAME="enter_loop/4"><STRONG><CODE>enter_loop(Module, Options, State, Timeout)</CODE></STRONG></A><BR>
<A NAME="enter_loop/5"><STRONG><CODE>enter_loop(Module, Options, State, ServerName, Timeout)
</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Option]</CODE></STRONG><BR>
<STRONG><CODE>Option = {debug,Dbgs}</CODE></STRONG><BR>
<STRONG><CODE>Dbgs = [Dbg]</CODE></STRONG><BR>
<STRONG><CODE>Dbg = trace | log | statistics</CODE></STRONG><BR>
<STRONG><CODE>| {log_to_file,FileName}
         | {install,{Func,FuncState}}</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>ServerName = {local,Name} | {global,GlobalName}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>GlobalName = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int() | infinity</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Makes an existing process into a gen_server. Does not return,
         instead the calling process will enter the gen_server receive
         loop and become a gen_server process. The process
         <STRONG>must</STRONG> have been started using one of the start
         functions in <CODE>proc_lib</CODE>, see
         <A HREF="proc_lib.html">proc_lib(3)</A>. The user is
         responsible for any initialization of the process, including
         registering a name for it.
<P>This function is useful when a more complex initalization
         procedure is needed than the gen_server behaviour provides.
        
<P><CODE>Module</CODE>, <CODE>Options</CODE> and <CODE>ServerName</CODE> have
         the same meanings as when calling
         <A HREF="#start_link/3">gen_server:start[_link]/3,4</A>.
         However, if <CODE>ServerName</CODE> is specified, the process must
         have been registered accordingly <STRONG>before</STRONG> this function
         is called.
<P><CODE>State</CODE> and <CODE>Timeout</CODE> have the same meanings as in
         the return value of
         <A HREF="#Moduleinit">Module:init/1</A>.
         Also, the callback module <CODE>Module</CODE> does not need to
         export an <CODE>init/1</CODE> function. 
<P>Failure: If the calling process was not started by a
         <CODE>proc_lib</CODE> start function, or if it is not registered
         according to <CODE>ServerName</CODE>.
</DIV>

<H3>CALLBACK FUNCTIONS</H3>
<DIV CLASS=REFBODY>

<P>The following functions
should be exported from a <CODE>gen_server</CODE> callback module.
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="Module:init/1"><STRONG><CODE>Module:init(Args) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,State} | {ok,State,Timeout}</CODE></STRONG><BR>
<STRONG><CODE>| {stop,Reason} | ignore</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;=0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>
<A NAME="Moduleinit"><!-- Empty --></A>
<P>Whenever a gen_server is started using <CODE>gen_server:start/3,4</CODE>
         or <CODE>gen_server:start_link/3.4</CODE>, this function is called by
         the new process to initialize.
<P><CODE>Args</CODE> is the <CODE>Args</CODE> argument provided to the start
         function.
<P>If the initialization is successful, the function should return
         <CODE>{ok,State}</CODE> or <CODE>{ok,State,Timout}</CODE>, where <CODE>State</CODE>
         is the internal state of the gen_server.
<P>If an integer timout value is provided, a timout will occur
         unless a request or a message is received within <CODE>Timeout</CODE>
         milliseconds. A timout is represented by the atom <CODE>timeout</CODE>
         which should be handled by the <CODE>handle_info/2</CODE> callback
         function. The atom <CODE>inifinity</CODE> can be used to wait
         indefinitely, this is the default value.
<P>If something goes wrong during the initialization the function
         should return <CODE>{stop,Reason}</CODE> where <CODE>Reason</CODE> is any
         term, or <CODE>ignore</CODE>.
</DIV>

<P><A NAME="Module:handle_call/3"><STRONG><CODE>Module:handle_call(Request, From, State) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Request = term()</CODE></STRONG><BR>
<STRONG><CODE>From = {pid(),Tag}</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {reply,Reply,NewState} | {reply,Reply,NewState,Timeout}
        </CODE></STRONG><BR>
<STRONG><CODE>| {noreply,NewState} | {noreply,NewState,Timeout}</CODE></STRONG><BR>
<STRONG><CODE>| {stop,Reason,Reply,NewState} | {stop,Reason,NewState}
        </CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;=0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Whenever a gen_server receives a request sent using
         <CODE>gen_server:call/2,3</CODE> or <CODE>gen_server:multi_call/2,3,4</CODE>,
         this function is called to handle the request.
<P><CODE>Request</CODE> is the <CODE>Request</CODE> argument provided
         to <CODE>call</CODE> or <CODE>multi_call</CODE>.
<P><CODE>From</CODE> is a tuple <CODE>{Pid,Tag}</CODE> where <CODE>Pid</CODE> is
         the pid of the client and <CODE>Tag</CODE> is a unique tag.
<P><CODE>State</CODE> is the internal state of the gen_server.
<P>If the function returns <CODE>{reply,Reply,NewState}</CODE> or
         <CODE>{reply,Reply,NewState,Timout}</CODE>, <CODE>Reply</CODE> will be given
         back to <CODE>From</CODE> as the return value of <CODE>call</CODE> or included
         in the return value of <CODE>multi_call</CODE>. The gen_server then
         continues executing with the possibly updated internal state
         <CODE>NewState</CODE>.
         See <CODE>Module:init/1</CODE> for a description of <CODE>Timeout</CODE>.
<P>If the functions returns <CODE>{noreply,NewState}</CODE> or
         <CODE>{noreply,NewState,Timeout}</CODE>, the gen_server will continue
         executing with <CODE>NewState</CODE>. Any reply to <CODE>From</CODE> must
         be given explicitly using <CODE>gen_server:reply/2</CODE>.
<P>If the function returns <CODE>{stop,Reason,Reply,NewState}</CODE>,
         <CODE>Reply</CODE> will be given back to <CODE>From</CODE>. If the function
         returns <CODE>{stop,Reason,NewState}</CODE>, any reply to <CODE>From</CODE>
         must be given explicitly using <CODE>gen_server:reply/2</CODE>.
         The gen_server will then call
         <CODE>Module:terminate(Reason,NewState)</CODE> and terminate.
</DIV>

<P><A NAME="Module:handle_cast/2"><STRONG><CODE>Module:handle_cast(Request, State) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Request = term()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {noreply,NewState} | {noreply,NewState,Timeout}</CODE></STRONG><BR>
<STRONG><CODE>| {stop,Reason,NewState}</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;=0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Whenever a gen_server receives a request sent using
         <CODE>gen_server:cast/2</CODE> or <CODE>gen_server:abcast/2,3</CODE>, this
         function is called to handle the request.
<P>See <CODE>Module:handle_call/3</CODE> for a description of
         the arguments and possible return values.
</DIV>

<P><A NAME="Module:handle_info/2"><STRONG><CODE>Module:handle_info(Info, State) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Info = timeout | term()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {noreply,NewState} | {noreply,NewState,Timeout}</CODE></STRONG><BR>
<STRONG><CODE>| {stop,Reason,NewState}</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;=0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Reason = normal | term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function is called by a gen_server when a timeout occurs or
         when it receives any other message than a synchronous or
         asynchronous request (or a system message).
<P><CODE>Info</CODE> is either the atom <CODE>timeout</CODE>, if a timeout has
         occured, or the received message.
<P>See <CODE>Module:handle_call/3</CODE> for a description of the other
         arguments and possible return values.
</DIV>

<P><A NAME="Module:terminate/2"><STRONG><CODE>Module:terminate(Reason, State)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Reason = normal | shutdown | term()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function is called by a gen_server when it is about to
         terminate. It should be the opposite of <CODE>Module:init/1</CODE> and
         do any necessary cleaning up. When it returns, the gen_server
         terminates with <CODE>Reason</CODE>. The return value is ignored.
<P><CODE>Reason</CODE> is a term denoting the stop reason and <CODE>State</CODE>
         is the internal state of the gen_server.
<P><CODE>Reason</CODE> depends on why the gen_server is terminating. If it
         is because another callback function has returned a stop tuple
         <CODE>{stop,..}</CODE>, <CODE>Reason</CODE> will have the value specified in
         that tuple. If it is due to a failure, <CODE>Reason</CODE> is the error
         reason.
<P>If the gen_server is part of a supervision tree and is ordered
         by its supervisor to terminate, this function will be called with
         <CODE>Reason=shutdown</CODE> if the following conditions apply:
<P>
<UL>

<LI>
the gen_server has been set to trap exit signals, and
</LI>


<LI>
the shutdown strategy as defined in the supervisor's child
         specification is an integer timeout value, not
         <CODE>brutal_kill</CODE>.
         
</LI>


</UL>

<P>Otherwise, the gen_server will be immediately terminated.
<P>Note that for any other reason than <CODE>normal</CODE> or
         <CODE>shutdown</CODE>, the gen_server is assumed to terminate due to an
         error and an error report is issued using
         <CODE>error_logger:format/2</CODE>.
</DIV>

<P><A NAME="Module:code_change/3"><STRONG><CODE>Module:code_change(OldVsn, State, Extra) -&#62; {ok, NewState}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>OldVsn = Vsn | {down, Vsn}</CODE></STRONG><BR>
<STRONG><CODE>Vsn = term()</CODE></STRONG><BR>
<STRONG><CODE>State = NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Extra = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function is called by a gen_server when it should
         update its internal state during a release upgrade/downgrade,
         i.e. when the instruction <CODE>{update,Module,Change,...}</CODE>
         where <CODE>Change={advanced,Extra}</CODE> is given in
         the <CODE>appup</CODE> file. See <STRONG>OTP Design Principles</STRONG> for
         more information.
<P>In the case of an upgrade, <CODE>OldVsn</CODE> is <CODE>Vsn</CODE>, and
         in the case of a downgrade, <CODE>OldVsn</CODE> is
         <CODE>{down,Vsn}</CODE>. <CODE>Vsn</CODE> is defined by the <CODE>vsn</CODE>
         attribute(s) of the old version of the callback module
         <CODE>Module</CODE>. If no such attribute is defined, the version
         is the checksum of the BEAM file.
<P><CODE>State</CODE> is the internal state of the gen_server.
<P><CODE>Extra</CODE> is passed as-is from the <CODE>{advanced,Extra}</CODE>
         part of the update instruction.
<P>The function should return the updated internal state.
</DIV>

<H3>SEE ALSO</H3>
<DIV CLASS=REFBODY>

<P><A HREF="supervisor.html">supervisor(3)</A>, 
<A HREF="sys.html">sys(3)</A>
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Gunilla Arendt - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.14.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>