Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
gen_server(3)		   Erlang Module Definition		 gen_server(3)

NAME
       gen_server - Generic server behavior.

DESCRIPTION
       This behavior module provides the server	of a client-server relation. A
       generic server process (gen_server) implemented using this module has a
       standard	 set  of  interface  functions	and includes functionality for
       tracing and error reporting. It also fits into an OTP supervision tree.
       For  more  information, see section  gen_server Behaviour in OTP	Design
       Principles.

       A gen_server process assumes all	specific parts	to  be	located	 in  a
       callback	 module	exporting a predefined set of functions. The relation-
       ship between the	behavior functions and the callback  functions	is  as
       follows:

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

       gen_server:stop	     -----> Module:terminate/2

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

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

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

       -		     -----> Module:handle_continue/2

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

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

       If  a  callback	function  fails	or returns a bad value,	the gen_server
       process terminates.

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

       Notice  that  a gen_server process does not trap	exit signals automati-
       cally, this must	be explicitly initiated	in the callback	module.

       Unless otherwise	stated,	all functions in this module fail if the spec-
       ified  gen_server process does not exist	or if bad arguments are	speci-
       fied.

       The gen_server process can go into hibernation (see erlang:hibernate/3)
       if  a  callback	function  specifies  'hibernate' instead of a time-out
       value. This can be useful if the	server is expected to be  idle	for  a
       long  time. However, use	this feature with care,	as hibernation 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.

       If the gen_server process needs to perform an action immediately	 after
       initialization  or  to  break the execution of a	callback into multiple
       steps, it can return {continue,Continue}	in place of  the  time-out  or
       hibernation  value, which will immediately invoke the handle_continue/2
       callback.

       If the gen_server process terminates, e.g. as a result of a function in
       the  callback  module  returning	{stop,Reason,NewState},	an exit	signal
       with this Reason	is sent	to linked processes and	ports. See   Processes
       in the Reference	Manual for details regarding error handling using exit
       signals.

EXPORTS
       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_server	processes  lo-
	      cally  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_server pro-
	      cesses call Module:handle_cast/2 to handle the request.

	      For a description	of the arguments, see multi_call/2,3,4.

       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	ServerRef  of  the  gen_server
	      process  by  sending a request and waiting until a reply arrives
	      or a time-out occurs. The	gen_server process  calls  Module:han-
	      dle_call/3 to handle the request.

	      ServerRef	can be any of the following:

		* The pid

		* Name,	if the gen_server process is locally registered

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

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

		* {via,Module,ViaName},	 if  the  gen_server process is	regis-
		  tered	through	an alternative process registry

	      Request is any term that is passed as the	first argument to Mod-
	      ule:handle_call/3.

	      Timeout  is an integer greater than zero that specifies how many
	      milliseconds to wait for a reply,	or the atom infinity  to  wait
	      indefinitely.  Defaults  to 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 can arrive at any time  later  into
	      the message queue	of the caller. 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 Mod-
	      ule:handle_call/3.

	      The call can fail	for many reasons, including time-out  and  the
	      called gen_server	process	dying before or	during the call.

       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 ServerRef of	the gen_server
	      process and returns ok immediately, ignoring if the  destination
	      node  or	gen_server  process  does  not	exist.	The gen_server
	      process calls Module:handle_cast/2 to handle the request.

	      For a description	of ServerRef, see call/2,3.

	      Request is any term that is passed as one	of  the	 arguments  to
	      Module:handle_cast/2.

       check_response(Msg, RequestId) -> Result

	      Types:

		 RequestId = term()
		 Result	= {reply, Reply} | no_reply | {error, {Reason, Server-
		 Ref}}
		 Msg = Reply = term()
		 Timeout = timeout()
		 Reason	= term()
		 ServerRef = Name | {Name,Node}	| {global,GlobalName}
		  | {via,Module,ViaName} | pid()
		  Node = atom()
		  GlobalName = ViaName = term()

	      This function is used to check if	a previously received message,
	      for  example  by	receive	or handle_info/2, is a result of a re-
	      quest made with send_request/2. If Msg is	a reply	to the	handle
	      RequestId	the result of the request is returned in Reply.	Other-
	      wise returns no_reply and	no cleanup is done, and	thus the func-
	      tion must	be invoked repeatedly until a reply is returned.

	      The  return  value  Reply	is defined in the return value of Mod-
	      ule:handle_call/3.

	      The function returns an error if the gen_server dies  before  or
	      during this request.

       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}	| {hibernate_after,HibernateAfterTime-
		 out}
		  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  process.  Does  not
	      return,  instead	the  calling  process  enters  the  gen_server
	      process receive loop  and	 becomes  a  gen_server	 process.  The
	      process  must have been started using one	of the start functions
	      in proc_lib(3). 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 pro-
	      cedure is	needed than the	gen_server process behavior provides.

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

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

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

       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_server processes locally
	      registered as Name at the	specified nodes	by first sending a re-
	      quest  to	 every	node  and  then	 waits	for  the  replies. The
	      gen_server process calls Module:handle_call/3 to handle the  re-
	      quest.

	      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  is	to  be
	      sent.   Default	value	is   the   list	 of  all  known	 nodes
	      [node()|nodes()].

	      Name is the locally registered name of each gen_server process.

	      Request is any term that is passed as the	first argument to Mod-
	      ule:handle_call/3.

	      Timeout  is an integer greater than zero that specifies how many
	      milliseconds to wait for each reply, or  the  atom  infinity  to
	      wait indefinitely. Defaults to 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 process 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 cannot process monitors, for example, C or
	      Java nodes, and the gen_server process 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 prevent late answers (after the time-out) from	polluting  the
	      message  queue  of the caller, a middleman process is used to do
	      the calls. Late answers are then discarded when they arrive to a
	      terminated process.

       receive_response(RequestId, Timeout) -> Result

	      Types:

		 RequestId = term()
		 Result	 = {reply, Reply} | timeout | {error, {Reason, Server-
		 Ref}}
		 Reply = term()
		 Timeout = timeout()
		 Reason	= term()
		 ServerRef = Name | {Name,Node}	| {global,GlobalName}
		  | {via,Module,ViaName} | pid()
		  Node = atom()
		  GlobalName = ViaName = term()

	      This function is used to receive a reply of a request made  with
	      send_request/2  to  a  gen_server	process. This function must be
	      called from the same process from	which send_request/2 was made.

	      Timeout is an integer greater then or equal to zero that	speci-
	      fies how many milliseconds to wait for an	reply, or the atom in-
	      finity to	wait indefinitely. If no reply is received within  the
	      specified	 time, the function returns timeout. Assuming that the
	      server executes on a node	supporting aliases (introduced in  OTP
	      24)  no  response	will be	received after a timeout. Otherwise, a
	      garbage response might be	received at a later time.

	      The return value Reply is	defined	in the return  value  of  Mod-
	      ule:handle_call/3.

	      The  function  returns an	error if the gen_server	dies before or
	      during this request.

	      The difference between wait_response() and receive_response() is
	      that  receive_response() abandons	the request at timeout so that
	      a	potential future response is  ignored,	while  wait_response()
	      does not.

       reply(Client, Reply) -> ok

	      Types:

		 Client	- see below
		 Reply = term()

	      This  function can be used by a gen_server process 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	 func-
	      tion.  Reply  is any term	given back to the client as the	return
	      value of call/2,3	or multi_call/2,3,4.

       send_request(ServerRef, Request)	-> RequestId

	      Types:

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

	      Sends a request to the ServerRef of the gen_server  process  and
	      returns  a  handle  RequestId.  The return value RequestId shall
	      later  be	 used  with  receive_response/2,  wait_response/2,  or
	      check_response/2 to fetch	the actual result of the request.

	      The	call	  gen_server:wait_response(gen_server:send_re-
	      quest(ServerRef,Request),	Timeout) can be	seen as	equivalent  to
	      gen_server:call(Server,Request,Timeout), ignoring	the error han-
	      dling.

	      The gen_server process calls Module:handle_call/3	to handle  the
	      request.

	      ServerRef	can be any of the following:

		* The pid

		* Name,	if the gen_server process is locally registered

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

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

		* {via,Module,ViaName},	 if  the  gen_server process is	regis-
		  tered	through	an alternative process registry

	      Request is any term that is passed as the	first argument to Mod-
	      ule:handle_call/3.

       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}  |	{hibernate_af-
		 ter,HibernateAfterTimeout} | {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  standalone gen_server	process, that is, a gen_server
	      process that is not part of a supervision	tree and thus  has  no
	      supervisor.

	      For   a	description   of  arguments  and  return  values,  see
	      start_link/3,4.

       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}  |	{hibernate_af-
		 ter,HibernateAfterTimeout} | {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. This
	      function	is to be called, directly or indirectly, by the	super-
	      visor. For example, it ensures that the  gen_server  process  is
	      linked to	the supervisor.

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

		* If ServerName={local,Name}, the gen_server process is	regis-
		  tered	locally	as Name	using register/2.

		* If ServerName={global,GlobalName}, the gen_server process id
		  registered   globally	  as  GlobalName  using	 global:regis-
		  ter_name/2 If	no name	is provided, the gen_server process is
		  not registered.

		* If  ServerName={via,Module,ViaName},	the gen_server process
		  registers with the registry represented by Module. The  Mod-
		  ule callback is to export the	functions register_name/2, un-
		  register_name/1, whereis_name/1, and send/2,	which  are  to
		  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 any  term	 that  is  passed  as  the  argument  to  Mod-
	      ule:init/1.

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

		* If	option	  {hibernate_after,HibernateAfterTimeout}   is
		  present, the gen_server process awaits any message  for  Hi-
		  bernateAfterTimeout  milliseconds  and  if no	message	is re-
		  ceived, the process goes into	hibernation automatically  (by
		  calling proc_lib:hibernate/3).

		* If  option  {debug,Dbgs}  is	present, the corresponding sys
		  function is called for each item in Dbgs; see	sys(3).

		* If option {spawn_opt,SOpts} is present, SOpts	is  passed  as
		  option list to the spawn_opt BIF, which is used to spawn the
		  gen_server process; see spawn_opt/2.

	  Note:
	      Using spawn option monitor is not	allowed, it causes  the	 func-
	      tion to fail with	reason badarg.

	      If  the  gen_server process is successfully created and initial-
	      ized, the	function returns {ok,Pid}, where Pid is	the pid	of the
	      gen_server  process.  If a process with the specified ServerName
	      exists	already,    the	   function    returns	   {error,{al-
	      ready_started,Pid}}, where Pid is	the pid	of that	process.

	      If  Module:init/1	 fails	with Reason, the function returns {er-
	      ror,Reason}. If Module:init/1 returns {stop,Reason}  or  ignore,
	      the  process  is terminated and the function returns {error,Rea-
	      son} or ignore, respectively. An exit signal with	the same  Rea-
	      son  (or	normal	if  Module:init/1  returns  ignore) is sent to
	      linked processes and ports.

       start_monitor(Module, Args, Options) -> Result
       start_monitor(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}  |	{hibernate_af-
		 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
		  Dbgs = [Dbg]
		  Dbg  =  trace	 | log | statistics | {log_to_file,FileName} |
		 {install,{Func,FuncState}}
		  SOpts	= [term()]
		 Result	= {ok,{Pid,Mon}} | ignore | {error,Error}
		  Pid =	pid()
		  Error	= {already_started,Pid}	| term()

	      Creates a	standalone gen_server process, that is,	 a  gen_server
	      process  that is not part	of a supervision tree (and thus	has no
	      supervisor) and atomically sets up a monitor to the  newly  cre-
	      ated server.

	      For   a	description   of  arguments  and  return  values,  see
	      start_link/3,4. Note that	the return value on  successful	 start
	      differs	from  start_link/3,4.  start_monitor/3,4  will	return
	      {ok,{Pid,Mon}} where  Pid	 is  the  process  identifier  of  the
	      server,  and Mon is a reference to the monitor set up to monitor
	      the server. If the start is not successful, the caller  will  be
	      blocked  until  the  DOWN	 message has been received and removed
	      from the message queue.

       stop(ServerRef) -> ok
       stop(ServerRef, Reason, Timeout)	-> ok

	      Types:

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

	      Orders a generic server to exit with the	specified  Reason  and
	      waits  for  it  to  terminate. The gen_server process calls Mod-
	      ule:terminate/2 before exiting.

	      The function returns ok if the server terminates	with  the  ex-
	      pected reason. Any other reason than normal, shutdown, or	{shut-
	      down,Term} causes	an error report	to be issued using  logger(3).
	      An  exit signal with the same reason is sent to linked processes
	      and ports. The default Reason is normal.

	      Timeout is an integer greater than zero that specifies how  many
	      milliseconds  to	wait  for the server to	terminate, or the atom
	      infinity to wait indefinitely.  Defaults	to  infinity.  If  the
	      server  has  not terminated within the specified time, a timeout
	      exception	is raised.

	      If the process does not exist, a noproc exception	is raised.

       wait_response(RequestId,	Timeout) -> Result

	      Types:

		 RequestId = term()
		 Result	= {reply, Reply} | timeout | {error, {Reason,  Server-
		 Ref}}
		 Reply = term()
		 Timeout = timeout()
		 Reason	= term()
		 ServerRef = Name | {Name,Node}	| {global,GlobalName}
		  | {via,Module,ViaName} | pid()
		  Node = atom()
		  GlobalName = ViaName = term()

	      This function is used to wait for	a reply	of a request made with
	      send_request/2 from the gen_server process. This	function  must
	      be  called  from	the same process from which send_request/2 was
	      made.

	      Timeout is an integer greater then or equal to zero that	speci-
	      fies how many milliseconds to wait for an	reply, or the atom in-
	      finity to	wait indefinitely. If no reply is received within  the
	      specified	 time,	the function returns timeout and no cleanup is
	      done, and	thus the function can be invoked  repeatedly  until  a
	      reply is returned.

	      The  return  value  Reply	is defined in the return value of Mod-
	      ule:handle_call/3.

	      The function returns an error if the gen_server dies  before  or
	      during this request.

	      The difference between receive_response()	and wait_response() is
	      that receive_response() abandons the request at timeout so  that
	      a	 potential  future  response is	ignored, while wait_response()
	      does not.

CALLBACK FUNCTIONS
       The following functions are to be exported from a  gen_server  callback
       module.

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

	      Types:

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

	  Note:
	      This callback is optional, so callback modules need  not	export
	      it.  If a	release	upgrade/downgrade with Change={advanced,Extra}
	      specified	in the appup file is made when code_change/3 isn't im-
	      plemented	the process will crash with an undef exit reason.

	      This  function  is  called by a gen_server process when it is to
	      update its internal state	during	a  release  upgrade/downgrade,
	      that  is,	when the instruction {update,Module,Change,...}, where
	      Change={advanced,Extra}, is specifed in the appup	file. For more
	      information,  see	 section  Release Handling Instructions	in OTP
	      Design Principles.

	      For an upgrade, OldVsn is	Vsn, and for 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 process.

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

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

	      If  the  function	 returns  {error,Reason},  the ongoing upgrade
	      fails and	rolls 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 in the following
	      situations:

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

		* The gen_server process terminates abnormally and logs	an er-
		  ror. Opt is set to the atom terminate.

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

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

	      State is the internal state of the gen_server process.

	      The  function  is	 to return Status, a term that changes the de-
	      tails of the current state and status of the gen_server process.
	      There  are  no restrictions on the form Status can take, but for
	      the sys:get_status/1,2 case (when	Opt  is	 normal),  the	recom-
	      mended form for the Status value is [{data, [{"State", Term}]}],
	      where Term provides relevant details of  the  gen_server	state.
	      Following	 this recommendation is	not required, but it makes 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 that large state	terms are  printed  in
	      log files.

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

	      Types:

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

	      Whenever a gen_server process  receives  a  request  sent	 using
	      call/2,3	or 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 process.

		* If  {reply,Reply,NewState}  is  returned,  {reply,Reply,New-
		  State,Timeout} or {reply,Reply,NewState,hibernate}, Reply is
		  given	 back  to  From	as the return value of call/2,3	or in-
		  cluded  in  the  return  value  of   multi_call/2,3,4.   The
		  gen_server  process then continues executing with the	possi-
		  bly updated internal state NewState.

		  For  a  description  of  Timeout  and	 hibernate,  see  Mod-
		  ule:init/1.

		* If  {noreply,NewState}  is returned, {noreply,NewState,Time-
		  out},	 or   {noreply,NewState,hibernate},   the   gen_server
		  process continues executing with NewState. Any reply to From
		  must be specified explicitly using reply/2.

		* If {stop,Reason,Reply,NewState} is returned, Reply is	 given
		  back to From.

		* If  {stop,Reason,NewState}  is  returned,  any reply to From
		  must be specified explicitly using reply/2.  The  gen_server
		  process  then	 calls	Module:terminate(Reason,NewState)  and
		  terminates.

       Module:handle_cast(Request, State) -> Result

	      Types:

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

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

	      For a description	of the arguments and possible  return  values,
	      see Module:handle_call/3.

       Module:handle_continue(Continue,	State) -> Result

	      Types:

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

	  Note:
	      This callback is optional, so callback modules need to export it
	      only if they return {continue,Continue} from  another  callback.
	      If  continue  is	used  and the callback is not implemented, the
	      process will exit	with undef error.

	      This function is called by a gen_server process whenever a  pre-
	      vious  callback  returns {continue, Continue}. handle_continue/2
	      is invoked immediately after the previous	callback, which	 makes
	      it useful	for performing work after initialization or for	split-
	      ting the work in a callback  in  multiple	 steps,	 updating  the
	      process state along the way.

	      For  a  description  of  the other arguments and possible	return
	      values, see Module:handle_call/3.

       Module:handle_info(Info,	State) -> Result

	      Types:

		 Info =	timeout	| term()
		 State = term()
		 Result	= {noreply,NewState} | {noreply,NewState,Timeout}
		  | {noreply,NewState,hibernate}
		  | {noreply,NewState,{continue,Continue}}
		  | {stop,Reason,NewState}
		  NewState = term()
		  Timeout = int()>=0 | infinity
		  Reason = normal | 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 logs about the	unexpected Info	message, drops
	      it and returns {noreply, State}.

	      This  function is	called by a gen_server process when a time-out
	      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 time-out has occurred, or
	      the received message.

	      For a description	of the other  arguments	 and  possible	return
	      values, see Module:handle_call/3.

       Module:init(Args) -> Result

	      Types:

		 Args =	term()
		 Result	 =  {ok,State} | {ok,State,Timeout} | {ok,State,hiber-
		 nate}
		  | {ok,State,{continue,Continue}} | {stop,Reason} | ignore
		  State	= term()
		  Timeout = int()>=0 | infinity
		  Reason = term()

	      Whenever	a  gen_server  process	is  started  using  start/3,4,
	      start_monitor/3,4, or 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	is  to	return
	      {ok,State},    {ok,State,Timeout},    {ok,State,hibernate},   or
	      {ok,State,{continue,Continue}} where State is the	internal state
	      of the gen_server	process.

	      If  an integer time-out value is provided, a time-out occurs un-
	      less a request or	a message is received within Timeout millisec-
	      onds. A time-out is represented by the atom timeout, which is to
	      be handled by the	Module:handle_info/2  callback	function.  The
	      atom  infinity can be used to wait indefinitely, this is the de-
	      fault value.

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

	      If {continue,Continue} is	specified, the	process	 will  execute
	      the Module:handle_continue/2 callback function, with Continue as
	      the first	argument.

	      If  the  initialization  fails,  the  function  is   to	return
	      {stop,Reason}, where Reason is any term, or ignore. An exit sig-
	      nal with this Reason (or with reason normal  if  ignore  is  re-
	      turned)  is  sent	 to linked processes and ports,	notably	to the
	      process starting the gen_server when start_link/3,4 is used.

       Module:terminate(Reason,	State)

	      Types:

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

	  Note:
	      This callback is optional, so callback modules need  not	export
	      it.  The	gen_server  module  provides  a	default	implementation
	      without cleanup.

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

	      Reason  is  a term denoting the stop reason and State is the in-
	      ternal state of the gen_server process.

	      Reason depends on	why the	gen_server process is terminating.  If
	      it  is because another callback function has returned a stop tu-
	      ple {stop,..}, Reason has	the value specified in that tuple.  If
	      it is because of a failure, Reason is the	error reason.

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

		* The gen_server process has been set to trap exit signals.

		* The  shutdown	strategy as defined in the child specification
		  of the supervisor is an integer  time-out  value,  not  bru-
		  tal_kill.

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

	      Otherwise, the gen_server	process	terminates immediately.

	      Notice  that  for	 any  other  reason  than normal, shutdown, or
	      {shutdown,Term}, the gen_server process is assumed to  terminate
	      because  of  an  error  and an error report is issued using log-
	      ger(3).

	      When the gen_server process exits, an exit signal	with the  same
	      reason is	sent to	linked processes and ports.

SEE ALSO
       gen_event(3), gen_statem(3), proc_lib(3), supervisor(3),	sys(3)

Ericsson AB			  stdlib 3.17			 gen_server(3)

NAME | DESCRIPTION | EXPORTS | CALLBACK FUNCTIONS | EXPORTS | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=gen_server&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help