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_link -----> Module:init/1

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

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

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 one	of  the	 arguments  to
	      Module: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.

       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]/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.	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 one	of  the	 arguments  to
	      Module: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.

       reply(Client, Reply) -> Result

	      Types:

		 Client	- see below
		 Reply = term()
		 Result	= 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.

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

       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.

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

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 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}, or  {ok,State,hibernate},	 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  the  initialization  fails,  the  function  is   to	return
	      {stop,Reason}, where Reason is any term, or ignore.

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

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

Ericsson AB			  stdlib 3.8			 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+12.2-RELEASE+and+Ports>

home | help