👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for gen_server (linux section 3erl)

gen_server(3erl)		     Erlang Module Definition			 gen_server(3erl)

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  informa-
       tion.

       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}
		     Name = atom()
		     GlobalName = 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 reg-
	      ister/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.

	      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  speci-
       fied  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  Mod-
       ule: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}
		     Name = atom()
		     GlobalName = 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} | pid()
		     Node = atom()
		     GlobalName = term()
		     Request = term()
		     Timeout = int()>0 | infinity
		     Reply = term()

	      Makes a synchronous call to the gen_server ServerRef by sending a request and wait-
	      ing until a reply arrives or a timeout occurs. The gen_server will call Module:han-
	      dle_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.

	      Request is an arbitrary term which is passed as one of the arguments to Module:han-
	      dle_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 spec-
	      ified  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:han-
	      dle_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 mid-
       dleman  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} | pid()
		     Node = atom()
		     GlobalName = term()
		     Request = term()

	      Sends an asynchronous request to the gen_server ServerRef and  returns  ok  immedi-
	      ately,  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:han-
	      dle_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 Mod-
	      ule: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}
		     Name = atom()
		     GlobalName = 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  initial-
	      ize.

	      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:hiber-
	      nate/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  New-
	      State . See Module:init/1 for a description of Timeout and hibernate .

	      If  the functions returns {noreply,NewState} , {noreply,NewState,Timeout} or {nore-
	      ply,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 Mod-
	      ule: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 mes-
	      sage.

	      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 call-
	      back  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 con-
	      ditions 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}

	      Types  OldVsn = Vsn | {down, Vsn}
		     Vsn = term()
		     State = NewState = term()
		     Extra = 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,Mod-
	      ule,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 check-
	      sum 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.

	      The function should return the updated internal state.

       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 termi-
	   nate 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)

Ericsson AB				  stdlib 1.17.3 			 gen_server(3erl)


All times are GMT -4. The time now is 08:27 PM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password