Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       gen_server - Generic Server Behaviour

DESCRIPTION

       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  OTP  Design  Principles  for  more
       information.

       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:

       gen_server module            Callback module
       -----------------            ---------------
       gen_server:start_link -----> Module:init/1

       gen_server:call
       gen_server:multi_call -----> Module:handle_call/3

       gen_server:cast
       gen_server:abcast     -----> Module:handle_cast/2

       -                     -----> Module:handle_info/2

       -                     -----> Module:terminate/2

       -                     -----> Module:code_change/3

       If a callback function fails or returns a bad value, the gen_server will terminate.

       A  gen_server  handles  system  messages as documented in sys(3erl). The sys module can be
       used for debugging a gen_server.

       Note that a gen_server does not trap exit signals automatically, this must  be  explicitly
       initiated in the callback module.

       Unless  otherwise  stated,  all  functions in this module fail if the specified gen_server
       does not exist or if bad arguments are given.

       The gen_server process can go into hibernation (see erlang(3erl)) if a  callback  function
       specifies  'hibernate'  instead  of a timeout value. This might be useful if the server is
       expected to be idle for a long time. However this feature should  be  used  with  care  as
       hibernation  implies  at least two garbage collections (when hibernating and shortly after
       waking up) and is not something you'd want to do between each call to a busy server.

EXPORTS

       start_link(Module, Args, Options) -> Result
       start_link(ServerName, Module, Args, Options) -> Result

              Types:

                 ServerName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}
                  Name = atom()
                  GlobalName = ViaName = term()
                 Module = atom()
                 Args = term()
                 Options = [Option]
                  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}
                  Dbgs = [Dbg]
                  Dbg   =   trace   |   log   |    statistics    |    {log_to_file,FileName}    |
                 {install,{Func,FuncState}}
                  SOpts = [term()]
                 Result = {ok,Pid} | ignore | {error,Error}
                  Pid = pid()
                  Error = {already_started,Pid} | term()

              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.

              The  gen_server process calls Module:init/1 to initialize. To ensure a synchronized
              start-up  procedure,  start_link/3,4  does  not  return  until  Module:init/1   has
              returned.

              If  ServerName={local,Name}  the  gen_server  is  registered  locally as Name using
              register/2. If ServerName={global,GlobalName} the gen_server is registered globally
              as  GlobalName using global:register_name/2. If no name is provided, the gen_server
              is not registered. If EventMgrName={via,Module,ViaName},  the  event  manager  will
              register with the registry represented by Module. The Module callback should export
              the functions register_name/2, unregister_name/1, whereis_name/1 and send/2,  which
              should    behave    like    the    corresponding   functions   in   global.   Thus,
              {via,global,GlobalName} is a valid reference.

              Module is the name of the callback module.

              Args is an arbitrary term which is passed as the argument to Module:init/1.

              If the option {timeout,Time} is present, the gen_server is allowed  to  spend  Time
              milliseconds  initializing  or  it  will  be terminated and the start function will
              return {error,timeout}.

              If the option {debug,Dbgs} is present,  the  corresponding  sys  function  will  be
              called for each item in Dbgs. See sys(3erl).

              If  the option {spawn_opt,SOpts} is present, SOpts will be passed as option list to
              the spawn_opt BIF which is used to spawn the gen_server. See erlang(3erl).

          Note:
              Using the spawn option monitor  is  currently  not  allowed,  but  will  cause  the
              function to fail with reason badarg.

              If  the  gen_server  is  successfully  created and initialized the function returns
              {ok,Pid}, where Pid is the pid of the gen_server. If there already exists a process
              with  the  specified ServerName the function returns {error,{already_started,Pid}},
              where Pid is the pid of that process.

              If Module:init/1  fails  with  Reason,  the  function  returns  {error,Reason}.  If
              Module:init/1  returns  {stop,Reason}  or ignore, the process is terminated and the
              function returns {error,Reason} or ignore, respectively.

       start(Module, Args, Options) -> Result
       start(ServerName, Module, Args, Options) -> Result

              Types:

                 ServerName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}
                  Name = atom()
                  GlobalName = ViaName = term()
                 Module = atom()
                 Args = term()
                 Options = [Option]
                  Option = {debug,Dbgs} | {timeout,Time} | {spawn_opt,SOpts}
                  Dbgs = [Dbg]
                  Dbg   =   trace   |   log   |    statistics    |    {log_to_file,FileName}    |
                 {install,{Func,FuncState}}
                  SOpts = [term()]
                 Result = {ok,Pid} | ignore | {error,Error}
                  Pid = pid()
                  Error = {already_started,Pid} | term()

              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.

              See start_link/3,4 for a description of arguments and return values.

       call(ServerRef, Request) -> Reply
       call(ServerRef, Request, Timeout) -> Reply

              Types:

                 ServerRef = Name | {Name,Node} | {global,GlobalName}  |  {via,Module,ViaName}  |
                 pid()
                  Node = atom()
                  GlobalName = ViaName = term()
                 Request = term()
                 Timeout = int()>0 | infinity
                 Reply = term()

              Makes  a  synchronous  call  to  the  gen_server ServerRef by sending a request and
              waiting until a reply arrives  or  a  timeout  occurs.  The  gen_server  will  call
              Module:handle_call/3 to handle the request.

              ServerRef can be:

                * the pid,

                * Name, if the gen_server is locally registered,

                * {Name,Node}, if the gen_server is locally registered at another node, or

                * {global,GlobalName}, if the gen_server is globally registered.

                * {via,Module,ViaName},  if  the  gen_server is registered through an alternative
                  process registry.

              Request is  an  arbitrary  term  which  is  passed  as  one  of  the  arguments  to
              Module:handle_call/3.

              Timeout  is  an  integer greater than zero which specifies how many milliseconds to
              wait for a reply, or the atom infinity to wait indefinitely. Default value is 5000.
              If  no reply is received within the specified time, the function call fails. If the
              caller catches the failure and continues running, and the server is just late  with
              the  reply,  it  may  arrive at any time later into the caller's message queue. The
              caller must in this case be prepared for this and discard any such garbage messages
              that are two element tuples with a reference as the first element.

              The return value Reply is defined in the return value of Module:handle_call/3.

              The  call may fail for several reasons, including timeout and the called gen_server
              dying before or during the call.

              The ancient behaviour of sometimes consuming the server exit message if the  server
              died during the call while linked to the client has been removed in OTP R12B/Erlang
              5.6.

       multi_call(Name, Request) -> Result
       multi_call(Nodes, Name, Request) -> Result
       multi_call(Nodes, Name, Request, Timeout) -> Result

              Types:

                 Nodes = [Node]
                  Node = atom()
                 Name = atom()
                 Request = term()
                 Timeout = int()>=0 | infinity
                 Result = {Replies,BadNodes}
                  Replies = [{Node,Reply}]
                  Reply = term()
                 BadNodes = [Node]

              Makes a synchronous call to all gen_servers  locally  registered  as  Name  at  the
              specified  nodes  by first sending a request to every node and then waiting for the
              replies. The gen_servers will call Module:handle_call/3 to handle the request.

              The function returns  a  tuple  {Replies,BadNodes}  where  Replies  is  a  list  of
              {Node,Reply} and BadNodes is a list of node that either did not exist, or where the
              gen_server Name did not exist or did not reply.

              Nodes is a list of node names to which the request should be sent. Default value is
              the list of all known nodes [node()|nodes()].

              Name is the locally registered name of each gen_server.

              Request  is  an  arbitrary  term  which  is  passed  as  one  of  the  arguments to
              Module:handle_call/3.

              Timeout is an integer greater than zero which specifies how  many  milliseconds  to
              wait  for  each  reply, or the atom infinity to wait indefinitely. Default value is
              infinity. If no reply is received from a node within the specified time,  the  node
              is added to BadNodes.

              When  a reply Reply is received from the gen_server at a node Node, {Node,Reply} is
              added to Replies. Reply is defined in the return value of Module:handle_call/3.

          Warning:
              If one of the nodes is not capable of process  monitors,  for  example  C  or  Java
              nodes,  and  the  gen_server  is not started when the requests are sent, but starts
              within 2 seconds, this function waits the whole Timeout, which may be infinity.

              This problem does not exist if all nodes are Erlang nodes.

              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.

       cast(ServerRef, Request) -> ok

              Types:

                 ServerRef = Name | {Name,Node} | {global,GlobalName}  |  {via,Module,ViaName}  |
                 pid()
                  Node = atom()
                  GlobalName = ViaName = term()
                 Request = term()

              Sends   an  asynchronous  request  to  the  gen_server  ServerRef  and  returns  ok
              immediately, ignoring if the destination node or gen_server  does  not  exist.  The
              gen_server will call Module:handle_cast/2 to handle the request.

              See call/2,3 for a description of ServerRef.

              Request  is  an  arbitrary  term  which  is  passed  as  one  of  the  arguments to
              Module:handle_cast/2.

       abcast(Name, Request) -> abcast
       abcast(Nodes, Name, Request) -> abcast

              Types:

                 Nodes = [Node]
                  Node = atom()
                 Name = atom()
                 Request = term()

              Sends an asynchronous request to the gen_servers locally registered as Name at  the
              specified  nodes.  The  function  returns immediately and ignores nodes that do not
              exist, or where the gen_server Name does  not  exist.  The  gen_servers  will  call
              Module:handle_cast/2 to handle the request.

              See multi_call/2,3,4 for a description of the arguments.

       reply(Client, Reply) -> Result

              Types:

                 Client - see below
                 Reply = term()
                 Result = term()

              This  function  can  be used by a gen_server to explicitly send a reply to a client
              that called call/2,3 or multi_call/2,3,4, when the reply cannot be defined  in  the
              return value of Module:handle_call/3.

              Client  must  be  the  From argument provided to the callback function. Reply is an
              arbitrary term, which will be given back to the  client  as  the  return  value  of
              call/2,3 or multi_call/2,3,4.

              The return value Result is not further defined, and should always be ignored.

       enter_loop(Module, Options, State)
       enter_loop(Module, Options, State, ServerName)
       enter_loop(Module, Options, State, Timeout)
       enter_loop(Module, Options, State, ServerName, Timeout)

              Types:

                 Module = atom()
                 Options = [Option]
                  Option = {debug,Dbgs}
                  Dbgs = [Dbg]
                  Dbg = trace | log | statistics
                  | {log_to_file,FileName} | {install,{Func,FuncState}}
                 State = term()
                 ServerName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}
                  Name = atom()
                  GlobalName = ViaName = term()
                 Timeout = int() | infinity

              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  must  have  been started using one of the start functions in proc_lib, see
              proc_lib(3erl). The user is responsible for  any  initialization  of  the  process,
              including registering a name for it.

              This function is useful when a more complex initialization procedure is needed than
              the gen_server behaviour provides.

              Module,  Options  and  ServerName  have  the  same   meanings   as   when   calling
              gen_server:start[_link]/3,4.  However, if ServerName is specified, the process must
              have been registered accordingly before this function is called.

              State and Timeout have the same meanings as in the return value  of  Module:init/1.
              Also, the callback module Module does not need to export an init/1 function.

              Failure: If the calling process was not started by a proc_lib start function, or if
              it is not registered according to ServerName.

CALLBACK FUNCTIONS

       The following functions should be exported from a gen_server callback module.

EXPORTS

       Module:init(Args) -> Result

              Types:

                 Args = term()
                 Result = {ok,State} | {ok,State,Timeout} | {ok,State,hibernate}
                  | {stop,Reason} | ignore
                  State = term()
                  Timeout = int()>=0 | infinity
                  Reason = term()

              Whenever    a    gen_server    is    started    using    gen_server:start/3,4    or
              gen_server:start_link/3,4,   this   function  is  called  by  the  new  process  to
              initialize.

              Args is the Args argument provided to the start function.

              If the  initialization  is  successful,  the  function  should  return  {ok,State},
              {ok,State,Timeout}  or  {ok,State,hibernate},  where State is the internal state of
              the gen_server.

              If an integer timeout value is provided, a timeout will occur unless a request or a
              message  is  received  within Timeout milliseconds. A timeout is represented by the
              atom timeout which should be handled by the handle_info/2  callback  function.  The
              atom infinity can be used to wait indefinitely, this is the default value.

              If  hibernate  is  specified  instead  of a timeout value, the process will go into
              hibernation  when  waiting  for  the   next   message   to   arrive   (by   calling
              proc_lib:hibernate/3).

              If  something  goes  wrong  during  the  initialization  the function should return
              {stop,Reason} where Reason is any term, or ignore.

       Module:handle_call(Request, From, State) -> Result

              Types:

                 Request = term()
                 From = {pid(),Tag}
                 State = term()
                 Result = {reply,Reply,NewState} | {reply,Reply,NewState,Timeout}
                  | {reply,Reply,NewState,hibernate}
                  | {noreply,NewState} | {noreply,NewState,Timeout}
                  | {noreply,NewState,hibernate}
                  | {stop,Reason,Reply,NewState} | {stop,Reason,NewState}
                  Reply = term()
                  NewState = term()
                  Timeout = int()>=0 | infinity
                  Reason = term()

              Whenever  a  gen_server  receives  a  request  sent  using  gen_server:call/2,3  or
              gen_server:multi_call/2,3,4, this function is called to handle the request.

              Request is the Request argument provided to call or multi_call.

              From  is  a  tuple {Pid,Tag} where Pid is the pid of the client and Tag is a unique
              tag.

              State is the internal state of the gen_server.

              If the function returns {reply,Reply,NewState},  {reply,Reply,NewState,Timeout}  or
              {reply,Reply,NewState,hibernate},  Reply  will  be given back to From as the return
              value of call/2,3  or  included  in  the  return  value  of  multi_call/2,3,4.  The
              gen_server  then  continues  executing  with  the  possibly  updated internal state
              NewState. See Module:init/1 for a description of Timeout and hibernate.

              If  the  functions  returns   {noreply,NewState},   {noreply,NewState,Timeout}   or
              {noreply,NewState,hibernate}, the gen_server will continue executing with NewState.
              Any reply to From must be given explicitly using gen_server:reply/2.

              If the function returns {stop,Reason,Reply,NewState}, Reply will be given  back  to
              From.  If  the  function  returns {stop,Reason,NewState}, any reply to From must be
              given  explicitly  using  gen_server:reply/2.  The  gen_server   will   then   call
              Module:terminate(Reason,NewState) and terminate.

       Module:handle_cast(Request, State) -> Result

              Types:

                 Request = term()
                 State = term()
                 Result = {noreply,NewState} | {noreply,NewState,Timeout}
                  | {noreply,NewState,hibernate}
                  | {stop,Reason,NewState}
                  NewState = term()
                  Timeout = int()>=0 | infinity
                  Reason = term()

              Whenever   a   gen_server  receives  a  request  sent  using  gen_server:cast/2  or
              gen_server:abcast/2,3, this function is called to handle the request.

              See Module:handle_call/3 for a description of the  arguments  and  possible  return
              values.

       Module:handle_info(Info, State) -> Result

              Types:

                 Info = timeout | term()
                 State = term()
                 Result = {noreply,NewState} | {noreply,NewState,Timeout}
                  | {noreply,NewState,hibernate}
                  | {stop,Reason,NewState}
                  NewState = term()
                  Timeout = int()>=0 | infinity
                  Reason = normal | term()

              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).

              Info is either the atom timeout,  if  a  timeout  has  occurred,  or  the  received
              message.

              See  Module:handle_call/3  for  a  description  of the other arguments and possible
              return values.

       Module:terminate(Reason, State)

              Types:

                 Reason = normal | shutdown | {shutdown,term()} | term()
                 State = term()

              This function is called by a gen_server when it is about to terminate. It should be
              the  opposite  of  Module:init/1 and do any necessary cleaning up. When it returns,
              the gen_server terminates with Reason. The return value is ignored.

              Reason is a term denoting the stop reason and State is the internal  state  of  the
              gen_server.

              Reason  depends  on  why  the  gen_server  is terminating. If it is because another
              callback function has returned a stop tuple {stop,..}, Reason will have  the  value
              specified in that tuple. If it is due to a failure, Reason is the error reason.

              If the gen_server is part of a supervision tree and is ordered by its supervisor to
              terminate, this function will be  called  with  Reason=shutdown  if  the  following
              conditions apply:

                * the gen_server has been set to trap exit signals, and

                * the  shutdown strategy as defined in the supervisor's child specification is an
                  integer timeout value, not brutal_kill.

              Even if the gen_server is not part of a supervision tree,  this  function  will  be
              called if it receives an 'EXIT' message from its parent. Reason will be the same as
              in the 'EXIT' message.

              Otherwise, the gen_server will be immediately terminated.

              Note that for any other  reason  than  normal,  shutdown,  or  {shutdown,Term}  the
              gen_server  is  assumed  to terminate due to an error and an error report is issued
              using error_logger:format/2.

       Module:code_change(OldVsn, State, Extra) -> {ok, NewState} | {error, Reason}

              Types:

                 OldVsn = Vsn | {down, Vsn}
                  Vsn = term()
                 State = NewState = term()
                 Extra = term()
                 Reason = term()

              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
              {update,Module,Change,...} where Change={advanced,Extra}  is  given  in  the  appup
              file. See OTP Design Principles for more information.

              In the case of an upgrade, OldVsn is Vsn, and in the case of a downgrade, OldVsn is
              {down,Vsn}. Vsn is defined by the vsn  attribute(s)  of  the  old  version  of  the
              callback  module  Module.  If  no  such  attribute  is  defined, the version is the
              checksum of the BEAM file.

              State is the internal state of the gen_server.

              Extra is passed as-is from the {advanced,Extra} part of the update instruction.

              If successful, the function shall return the updated internal state.

              If the function returns {error,Reason}, the ongoing upgrade will fail and roll back
              to the old release.

       Module:format_status(Opt, [PDict, State]) -> Status

              Types:

                 Opt = normal | terminate
                 PDict = [{Key, Value}]
                 State = term()
                 Status = term()

          Note:
              This  callback  is optional, so callback modules need not export it. The gen_server
              module provides a default implementation of this function that returns the callback
              module state.

              This function is called by a gen_server process when:

                * One  of  sys:get_status/1,2 is invoked to get the gen_server status. Opt is set
                  to the atom normal for this case.

                * The gen_server terminates abnormally and logs an error. Opt is set to the  atom
                  terminate for this case.

              This  function  is useful for customising the form and appearance of the gen_server
              status  for  these  cases.   A   callback   module   wishing   to   customise   the
              sys:get_status/1,2  return  value  as well as how its status appears in termination
              error logs exports an instance of format_status/2 that returns  a  term  describing
              the current status of the gen_server.

              PDict is the current value of the gen_server's process dictionary.

              State is the internal state of the gen_server.

              The  function  should  return  Status,  a  term  that customises the details of the
              current state and status of the gen_server. There are no restrictions on  the  form
              Status  can  take,  but  for  the sys:get_status/1,2 case (when Opt is normal), the
              recommended form for the Status value is [{data,  [{"State",  Term}]}]  where  Term
              provides  relevant  details  of the gen_server state. Following this recommendation
              isn't required, but doing so will make the callback module status  consistent  with
              the rest of the sys:get_status/1,2 return value.

              One use for this function is to return compact alternative state representations to
              avoid having large state terms printed in logfiles.

SEE ALSO

       gen_event(3erl), gen_fsm(3erl), supervisor(3erl), proc_lib(3erl), sys(3erl)