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

FreeBSD Manual Pages

  
 
  

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

NAME
       gen_event - Generic event handling behavior.

DESCRIPTION
       This behavior module provides event handling functionality. It consists
       of a generic event manager process with any number  of  event  handlers
       that are	added and deleted dynamically.

       An  event  manager  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 informa-
       tion, see OTP Design Principles.

       Each event handler is implemented as a callback module exporting	a pre-
       defined	set  of	functions. The relationship between the	behavior func-
       tions and the callback functions	is as follows:

       gen_event module			  Callback module
       ----------------			  ---------------
       gen_event:start
       gen_event:start_monitor
       gen_event:start_link	  ----->  -

       gen_event:add_handler
       gen_event:add_sup_handler  ----->  Module:init/1

       gen_event:notify
       gen_event:sync_notify	  ----->  Module:handle_event/2

       gen_event:send_request
       gen_event:call		  ----->  Module:handle_call/2

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

       gen_event:delete_handler	  ----->  Module:terminate/2

       gen_event:swap_handler
       gen_event:swap_sup_handler ----->  Module1:terminate/2
					  Module2:init/1

       gen_event:which_handlers	  ----->  -

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

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

       As each event handler is	one callback module, an	event manager has many
       callback	 modules  that are added and deleted dynamically. gen_event is
       therefore more tolerant of callback module errors than the other	behav-
       iors.  If a callback function for an installed event handler fails with
       Reason, or returns a bad	value Term, the	event manager does  not	 fail.
       It deletes the event handler by calling callback	function Module:termi-
       nate/2, giving as argument {error,{'EXIT',Reason}} or {error,Term}, re-
       spectively. No other event handler is affected.

       A gen_event process handles system messages as described	in sys(3). The
       sys module can be used for debugging an event manager.

       Notice that an event manager does trap exit signals automatically.

       The gen_event process can go into hibernation (see  erlang:hibernate/3)
       if  a  callback function	in a handler module specifies hibernate	in its
       return 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 event
       handled by a busy event manager.

       Notice that when	multiple event handlers	are invoked, it	is  sufficient
       that one	single event handler returns a hibernate request for the whole
       event manager to	go into	hibernation.

       Unless otherwise	stated,	all functions in this module fail if the spec-
       ified event manager does	not exist or if	bad arguments are specified.

DATA TYPES
       handler() = atom() | {atom(), term()}

       handler_args() =	term()

       add_handler_ret() = ok |	term() | {'EXIT', term()}

       del_handler_ret() = ok |	term() | {'EXIT', term()}

       request_id() = term()

	      A	request	handle,	see send_request/3 for details.

EXPORTS
       add_handler(EventMgrRef,	Handler, Args) -> Result

	      Types:

		 EventMgrRef  =	 Name  |  {Name,Node}  | {global,GlobalName} |
		 {via,Module,ViaName} |	pid()
		  Name = Node =	atom()
		  GlobalName = ViaName = term()
		 Handler = Module | {Module,Id}
		  Module = atom()
		  Id = term()
		 Args =	term()
		 Result	= ok | {'EXIT',Reason} | term()
		  Reason = term()

	      Adds a new event handler to event	manager	EventMgrRef. The event
	      manager  calls  Module:init/1  to	initiate the event handler and
	      its internal state.

	      EventMgrRef can be any of	the following:

		* The pid

		* Name,	if the event manager is	locally	registered

		* {Name,Node}, if the event manager is locally	registered  at
		  another node

		* {global,GlobalName}, if the event manager is globally	regis-
		  tered

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

	      Handler  is  the	name  of the callback module Module or a tuple
	      {Module,Id}, where Id is any term. The  {Module,Id}  representa-
	      tion makes it possible to	identify a specific event handler when
	      many event handlers use the same callback	module.

	      Args is any  term	 that  is  passed  as  the  argument  to  Mod-
	      ule:init/1.

	      If  Module:init/1	 returns a correct value indicating successful
	      completion, the event manager adds the event  handler  and  this
	      function	returns	 ok. If	Module:init/1 fails with Reason	or re-
	      turns {error,Reason}, the	event  handler	is  ignored  and  this
	      function	returns	 {'EXIT',Reason}  or  {error,Reason},  respec-
	      tively.

       add_sup_handler(EventMgrRef, Handler, Args) -> Result

	      Types:

		 EventMgrRef = Name  |	{Name,Node}  |	{global,GlobalName}  |
		 {via,Module,ViaName} |	pid()
		  Name = Node =	atom()
		  GlobalName = ViaName = term()
		 Handler = Module | {Module,Id}
		  Module = atom()
		  Id = term()
		 Args =	term()
		 Result	= ok | {'EXIT',Reason} | term()
		  Reason = term()

	      Adds  a  new event handler in the	same way as add_handler/3, but
	      also supervises the connection between the event handler and the
	      calling process.

		* If  the  calling  process  later terminates with Reason, the
		  event	manager	deletes	the  event  handler  by	 calling  Mod-
		  ule:terminate/2 with {stop,Reason} as	argument.

		* If  the  event  handler  is deleted later, the event manager
		  sends	a message {gen_event_EXIT,Handler,Reason} to the call-
		  ing process. Reason is one of	the following:

		  * normal, if the event handler has been removed because of a
		    call to delete_handler/3, or remove_handler	has  been  re-
		    turned by a	callback function (see below).

		  * shutdown,  if  the	event handler has been removed because
		    the	event manager is terminating.

		  * {swapped,NewHandler,Pid}, if the process Pid has  replaced
		    the	 event	handler	 with another event handler NewHandler
		    using a call to swap_handler/3 or swap_sup_handler/3.

		  * A term, if the event handler is removed because of an  er-
		    ror. Which term depends on the error.

	      For  a  description  of  the  arguments  and  return values, see
	      add_handler/3.

       call(EventMgrRef, Handler, Request) -> Result
       call(EventMgrRef, Handler, Request, Timeout) -> Result

	      Types:

		 EventMgrRef = Name  |	{Name,Node}  |	{global,GlobalName}  |
		 {via,Module,ViaName} |	pid()
		  Name = Node =	atom()
		  GlobalName = ViaName = term()
		 Handler = Module | {Module,Id}
		  Module = atom()
		  Id = term()
		 Request = term()
		 Timeout = int()>0 | infinity
		 Result	= Reply	| {error,Error}
		  Reply	= term()
		  Error	= bad_module | {'EXIT',Reason} | term()
		  Reason = term()

	      Makes  a	synchronous call to event handler Handler installed in
	      event manager EventMgrRef	by sending a request and waiting until
	      a	 reply	arrives	 or a time-out occurs. The event manager calls
	      Module:handle_call/2 to handle the request.

	      For a description	of EventMgrRef and Handler, see	add_handler/3.

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

	      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.

	      The return value Reply is	defined	in the return  value  of  Mod-
	      ule:handle_call/2.  If  the  specified  event handler is not in-
	      stalled, the function returns {error,bad_module}.	If  the	 call-
	      back  function  fails with Reason	or returns an unexpected value
	      Term, this  function  returns  {error,{'EXIT',Reason}}  or  {er-
	      ror,Term}, respectively.

       check_response(Msg, RequestId) -> Result

	      Types:

		 Msg = term()
		 RequestId = request_id()
		 Result	= {reply, Reply} | no_reply | {error, Error}
		 Reply = Error = 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/3. 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 shall be invoked repeatedly until a reply is	returned.

	      If the specified event handler is	not  installed,	 the  function
	      returns  {error,bad_module}. If the callback function fails with
	      Reason or	returns	an unexpected value Term,  this	 function  re-
	      turns  {error,{'EXIT',Reason}} or	{error,Term}, respectively. If
	      the event	manager	dies before or during the request  this	 func-
	      tion returns {error,{Reason, EventMgrRef}}.

       delete_handler(EventMgrRef, Handler, Args) -> Result

	      Types:

		 EventMgrRef  =	 Name  |  {Name,Node}  | {global,GlobalName} |
		 {via,Module,ViaName} |	pid()
		  Name = Node =	atom()
		  GlobalName = ViaName = term()
		 Handler = Module | {Module,Id}
		  Module = atom()
		  Id = term()
		 Args =	term()
		 Result	= term() | {error,module_not_found} | {'EXIT',Reason}
		  Reason = term()

	      Deletes an event handler from  event  manager  EventMgrRef.  The
	      event  manager  calls  Module:terminate/2	to terminate the event
	      handler.

	      For a description	of EventMgrRef and Handler, see	add_handler/3.

	      Args is any term that is passed as one of	the arguments to  Mod-
	      ule:terminate/2.

	      The  return  value is the	return value of	Module:terminate/2. If
	      the specified event handler is not installed, the	 function  re-
	      turns  {error,module_not_found}.	If the callback	function fails
	      with Reason, the function	returns	{'EXIT',Reason}.

       notify(EventMgrRef, Event) -> ok
       sync_notify(EventMgrRef,	Event) -> ok

	      Types:

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

	      Sends  an	 event	notification to	event manager EventMgrRef. The
	      event manager calls  Module:handle_event/2  for  each  installed
	      event handler to handle the event.

	      notify/2 is asynchronous and returns immediately after the event
	      notification has been sent. sync_notify/2	is synchronous in  the
	      sense that it returns ok after the event has been	handled	by all
	      event handlers.

	      For a description	of EventMgrRef,	see add_handler/3.

	      Event is any term	that is	passed as one of the arguments to Mod-
	      ule:handle_event/2.

	      notify/1	does not fail even if the specified event manager does
	      not exist, unless	it is specified	as Name.

       receive_response(RequestId, Timeout) -> Result

	      Types:

		 RequestId = request_id()
		 Reply = term()
		 Timeout = timeout()
		 Result	= {reply, Reply} | timeout | {error, Error}
		 Reply = Error = term()

	      This function is used to receive for a reply of a	 request  made
	      with  send_request/3 to the event	manager. This function must be
	      called from the same process from	which send_request/3 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.

	      If  the  specified  event	handler	is not installed, the function
	      returns {error,bad_module}. If the callback function fails  with
	      Reason  or  returns  an unexpected value Term, this function re-
	      turns {error,{'EXIT',Reason}} or {error,Term}, respectively.  If
	      the  event  manager dies before or during	the request this func-
	      tion returns {error,{Reason, EventMgrRef}}.

	      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.

       send_request(EventMgrRef, Handler, Request) -> RequestId

	      Types:

		 EventMgrRef = Name | {Name,Node} | {global,GlobalName}
		  | {via,Module,ViaName} | pid()
		  Node = atom()
		  GlobalName = ViaName = term()
		 Handler = Module | {Module,Id}
		  Module = atom()
		  Id = term()
		 Request = term()
		 RequestId = request_id()

	      Sends a request to event handler Handler installed in event man-
	      ager EventMgrRef and returns  a  handle  RequestId.  The	return
	      value  RequestId	shall  later  be used with receive_response/2,
	      wait_response/2, or check_response/2  in	the  same  process  to
	      fetch the	actual result of the request.

	      The  call	gen_event:wait_response(gen_event:send_request(EventM-
	      grRef,Handler,Request), Timeout) can be seen  as	equivalent  to
	      gen_event:call(EventMgrRef,Handler,Request,Timeout),    ignoring
	      the error	handling.

	      The event	manager	calls Module:handle_call/2 to handle  the  re-
	      quest.

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

       start() -> Result
       start(EventMgrName | Options) ->	Result
       start(EventMgrName, Options) -> Result

	      Types:

		 EventMgrName =	{local,Name} | {global,GlobalName} | {via,Mod-
		 ule,ViaName}
		  Name = atom()
		  GlobalName = ViaName = 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} | {error,{already_started,Pid}}
		  Pid =	pid()

	      Creates  a  stand-alone event manager process, that is, an event
	      manager that is not part of a supervision	tree and thus  has  no
	      supervisor.

	      For  a  description  of  the  arguments  and  return values, see
	      start_link/0,1.

       start_link() -> Result
       start_link(EventMgrName | Options) -> Result
       start_link(EventMgrName,	Options) -> Result

	      Types:

		 EventMgrName =	{local,Name} | {global,GlobalName} | {via,Mod-
		 ule,ViaName}
		  Name = atom()
		  GlobalName = ViaName = 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} | {error,{already_started,Pid}}
		  Pid =	pid()

	      Creates  an event	manager	process	as part	of a supervision tree.
	      The function is to be called, directly or	indirectly, by the su-
	      pervisor.	 For  example,	it  ensures  that the event manager is
	      linked to	the supervisor.

		* If EventMgrName={local,Name},	the event  manager  is	regis-
		  tered	locally	as Name	using register/2.

		* If  EventMgrName={global,GlobalName},	 the  event manager is
		  registered  globally	as  GlobalName	 using	 global:regis-
		  ter_name/2. If no name is provided, the event	manager	is not
		  registered.

		* If EventMgrName={via,Module,ViaName},	the event manager reg-
		  isters  with	the registry represented by Module. The	Module
		  callback is to export	the functions register_name/2,	unreg-
		  ister_name/1,	 whereis_name/1,  and send/2, which are	to be-
		  have	as  the	 corresponding	functions  in  global.	 Thus,
		  {via,global,GlobalName} is a valid reference.

		* If	option	  {hibernate_after,HibernateAfterTimeout}   is
		  present, the gen_event process awaits	any message for	Hiber-
		  nateAfterTimeout milliseconds	and if no message is received,
		  the process goes into	hibernation automatically (by  calling
		  proc_lib:hibernate/3).

	      If  the  event manager is	successfully created, the function re-
	      turns {ok,Pid}, where Pid	is the pid of the event	manager. If  a
	      process  with  the  specified  EventMgrName  exists already, the
	      function returns {error,{already_started,Pid}}, where Pid	is the
	      pid of that process.

       start_monitor() -> Result
       start_monitor(EventMgrName | Options) ->	Result
       start_monitor(EventMgrName, Options) -> Result

	      Types:

		 EventMgrName =	{local,Name} | {global,GlobalName} | {via,Mod-
		 ule,ViaName}
		  Name = atom()
		  GlobalName = ViaName = 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}} | {error,{already_started,Pid}}
		  Pid =	pid()

	      Creates a	stand-alone event manager process, that	is,  an	 event
	      manager  that is not part	of a supervision tree (and thus	has no
	      supervisor) and atomically sets up a monitor to the  newly  cre-
	      ated process.

	      For  a  description  of  the  arguments  and  return values, see
	      start_link/0,1. 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
	      process, and Mon is a reference to the monitor set up to monitor
	      the process. 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(EventMgrRef) -> ok
       stop(EventMgrRef, Reason, Timeout) -> ok

	      Types:

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

	      Orders event manager EventMgrRef to exit with the	specifies Rea-
	      son and waits for	it to terminate. Before	terminating, gen_event
	      calls  Module:terminate(stop,...)	 for each installed event han-
	      dler.

	      The function returns ok if the event manager terminates with the
	      expected	reason.	 Any  other  reason  than normal, shutdown, or
	      {shutdown,Term} causes an	error report to	be issued  using  log-
	      ger(3). The default Reason is normal.

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

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

	      For a description	of EventMgrRef,	see add_handler/3.

       swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) ->	Result

	      Types:

		 EventMgrRef  =	 Name  |  {Name,Node}  | {global,GlobalName} |
		 {via,Module,ViaName} |	pid()
		  Name = Node =	atom()
		  GlobalName = ViaName = term()
		 Handler1 = Handler2 = Module |	{Module,Id}
		  Module = atom()
		  Id = term()
		 Args1 = Args2 = term()
		 Result	= ok | {error,Error}
		  Error	= {'EXIT',Reason} | term()
		  Reason = term()

	      Replaces an old event handler with a new event handler in	 event
	      manager EventMgrRef.

	      For a description	of the arguments, see add_handler/3.

	      First  the old event handler Handler1 is deleted.	The event man-
	      ager calls Module1:terminate(Args1, ...),	where Module1  is  the
	      callback module of Handler1, and collects	the return value.

	      Then  the	 new  event handler Handler2 is	added and initiated by
	      calling Module2:init({Args2,Term}), where	Module2	is  the	 call-
	      back  module  of	Handler2  and Term is the return value of Mod-
	      ule1:terminate/2.	This makes it possible to transfer information
	      from Handler1 to Handler2.

	      The  new	handler	 is  added even	if the the specified old event
	      handler is not installed,	in which case Term=error, or  if  Mod-
	      ule1:terminate/2	  fails	   with	   Reason,   in	  which	  case
	      Term={'EXIT',Reason}. The	old handler is deleted	even  if  Mod-
	      ule2:init/1 fails.

	      If  there	 was  a	 supervised  connection	between	Handler1 and a
	      process Pid, there is a supervised connection  between  Handler2
	      and Pid instead.

	      If Module2:init/1	returns	a correct value, this function returns
	      ok. If Module2:init/1 fails with Reason or returns an unexpected
	      value  Term,  this  function  returns {error,{'EXIT',Reason}} or
	      {error,Term}, respectively.

       swap_sup_handler(EventMgrRef,  {Handler1,Args1},	 {Handler2,Args2})  ->
       Result

	      Types:

		 EventMgrRef  =	 Name  |  {Name,Node}  | {global,GlobalName} |
		 {via,Module,ViaName} |	pid()
		  Name = Node =	atom()
		  GlobalName = ViaName = term()
		 Handler1 = Handler 2 =	Module | {Module,Id}
		  Module = atom()
		  Id = term()
		 Args1 = Args2 = term()
		 Result	= ok | {error,Error}
		  Error	= {'EXIT',Reason} | term()
		  Reason = term()

	      Replaces an event	handler	in event manager  EventMgrRef  in  the
	      same  way	 as swap_handler/3, but	also supervises	the connection
	      between Handler2 and the calling process.

	      For a description	 of  the  arguments  and  return  values,  see
	      swap_handler/3.

       wait_response(RequestId,	Timeout) -> Result

	      Types:

		 RequestId = request_id()
		 Reply = term()
		 Timeout = timeout()
		 Result	= {reply, Reply} | timeout | {error, Error}
		 Reply = Error = term()

	      This function is used to wait for	a reply	of a request made with
	      send_request/3 to	the  event  manager.  This  function  must  be
	      called from the same process from	which send_request/3 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 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.

	      If  the  specified  event	handler	is not installed, the function
	      returns {error,bad_module}. If the callback function fails  with
	      Reason  or  returns  an unexpected value Term, this function re-
	      turns {error,{'EXIT',Reason}} or {error,Term}, respectively.  If
	      the  event  manager dies before or during	the request this func-
	      tion returns {error,{Reason, EventMgrRef}}.

	      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.

       which_handlers(EventMgrRef) -> [Handler]

	      Types:

		 EventMgrRef  =	 Name  |  {Name,Node}  | {global,GlobalName} |
		 {via,Module,ViaName} |	pid()
		  Name = Node =	atom()
		  GlobalName = ViaName = term()
		 Handler = Module | {Module,Id}
		  Module = atom()
		  Id = term()

	      Returns a	list of	all event handlers installed in	event  manager
	      EventMgrRef.

	      For a description	of EventMgrRef and Handler, see	add_handler/3.

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

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

	      Types:

		 OldVsn	= Vsn |	{down, Vsn}
		  Vsn =	term()
		 State = NewState = term()
		 Extra = 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
	      implemented  the	event  handler	will crash with	an undef error
	      reason.

	      This function is called for an installed event handler  that  is
	      to update	its internal state during a release upgrade/downgrade,
	      that is, when the	instruction {update,Module,Change,...},	 where
	      Change={advanced,Extra},	is  specified  in the .appup file. For
	      more information,	see 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 event handler.

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

	      The function is to 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 event handler modules need not ex-
	      port  it.	 If  a	handler	 does  not  export  this function, the
	      gen_event	module uses the	handler	state directly	for  the  pur-
	      poses described below.

	      This  function is	called by a gen_event process in the following
	      situations:

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

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

	      This function is useful for changing the form and	appearance  of
	      the  event handler state for these cases.	An event handler call-
	      back module wishing to change the	the sys:get_status/1,2	return
	      value  as	 well  as  how	its state appears in termination error
	      logs, exports an instance	of format_status/2 that	returns	a term
	      describing the current state of the event	handler.

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

	      State is the internal state of the event handler.

	      The function is to return	Status,	a term that change the details
	      of  the  current state of	the event handler. Any term is allowed
	      for Status. The gen_event	module uses Status as follows:

		* When sys:get_status/1,2 is called,  gen_event	 ensures  that
		  its  return value contains Status in place of	the state term
		  of the event handler.

		* When an event	handler	terminates abnormally, gen_event  logs
		  Status in place of the state term of the event handler.

	      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, State) -> Result

	      Types:

		 Request = term()
		 State = term()
		 Result	= {ok,Reply,NewState} |	{ok,Reply,NewState,hibernate}
		  | {swap_handler,Reply,Args1,NewState,Handler2,Args2}
		  | {remove_handler, Reply}
		  Reply	= term()
		  NewState = term()
		  Args1	= Args2	= term()
		  Handler2 = Module2 | {Module2,Id}
		  Module2 = atom()
		  Id = term()

	      Whenever	 an  event  manager  receives  a  request  sent	 using
	      call/3,4,	this function is called	for the	specified  event  han-
	      dler to handle the request.

	      Request is the Request argument of call/3,4.

	      State is the internal state of the event handler.

	      The  return values are the same as for Module:handle_event/2 ex-
	      cept that	they also contain a term Reply,	which is the reply  to
	      the client as the	return value of	call/3,4.

       Module:handle_event(Event, State) -> Result

	      Types:

		 Event = term()
		 State = term()
		 Result	= {ok,NewState}	| {ok,NewState,hibernate}
		  | {swap_handler,Args1,NewState,Handler2,Args2} | remove_han-
		 dler
		  NewState = term()
		  Args1	= Args2	= term()
		  Handler2 = Module2 | {Module2,Id}
		  Module2 = atom()
		  Id = term()

	      Whenever an event	manager	receives an event sent using  notify/2
	      or  sync_notify/2,  this	function  is called for	each installed
	      event handler to handle the event.

	      Event is the Event argument of notify/2/sync_notify/2.

	      State is the internal state of the event handler.

		* If {ok,NewState} or {ok,NewState,hibernate} is returned, the
		  event	handler	remains	in the event manager with the possible
		  updated internal state NewState.

		* If {ok,NewState,hibernate} is	returned,  the	event  manager
		  also	goes  into  hibernation	 (by  calling  proc_lib:hiber-
		  nate/3), waiting for the next	event to occur.	It  is	suffi-
		  cient	that one of the	event handlers return {ok,NewState,hi-
		  bernate} for the whole event manager process to hibernate.

		* If {swap_handler,Args1,NewState,Handler2,Args2} is returned,
		  the  event  handler is replaced by Handler2 by first calling
		  Module:terminate(Args1,NewState)     and	then	  Mod-
		  ule2:init({Args2,Term}),  where  Term	is the return value of
		  Module:terminate/2.  For  more  information,	see  swap_han-
		  dler/3.

		* If  remove_handler is	returned, the event handler is deleted
		  by calling Module:terminate(remove_handler,State).

       Module:handle_info(Info,	State) -> Result

	      Types:

		 Info =	term()
		 State = term()
		 Result	= {ok,NewState}	| {ok,NewState,hibernate}
		  | {swap_handler,Args1,NewState,Handler2,Args2} | remove_han-
		 dler
		  NewState = term()
		  Args1	= Args2	= term()
		  Handler2 = Module2 | {Module2,Id}
		  Module2 = atom()
		  Id = term()

	  Note:
	      This  callback  is optional, so callback modules need not	export
	      it. The gen_event	module provides	a  default  implementation  of
	      this function that logs about the	unexpected Info	message, drops
	      it and returns {ok, State}.

	      This function is called for each installed event handler when an
	      event manager receives any other message than an event or	a syn-
	      chronous request (or a system message).

	      Info is the received message.

	      For a description	of State and possible return values, see  Mod-
	      ule:handle_event/2.

       Module:init(InitArgs)  ->  {ok,State}  |	 {ok,State,hibernate}  |  {er-
       ror,Reason}

	      Types:

		 InitArgs = Args | {Args,Term}
		  Args = Term =	term()
		 State = term()
		 Reason	= term()

	      Whenever a new event handler is added to an event	manager,  this
	      function is called to initialize the event handler.

	      If the event handler is added because of a call to add_handler/3
	      or add_sup_handler/3, InitArgs is	the  Args  argument  of	 these
	      functions.

	      If the event handler replaces another event handler because of a
	      call to swap_handler/3 or	swap_sup_handler/3, or	because	 of  a
	      swap return tuple	from one of the	other callback functions, Ini-
	      tArgs is a tuple {Args,Term}, where Args is  the	argument  pro-
	      vided  in	 the function call/return tuple	and Term is the	result
	      of terminating the old event handler, see	swap_handler/3.

	      If successful, the function returns {ok,State} or	 {ok,State,hi-
	      bernate},	where State is the initial internal state of the event
	      handler.

	      If {ok,State,hibernate} is returned, the event manager goes into
	      hibernation  (by	calling	proc_lib:hibernate/3), waiting for the
	      next event to occur.

       Module:terminate(Arg, State) -> term()

	      Types:

		 Arg = Args | {stop,Reason} | stop | remove_handler
		  | {error,{'EXIT',Reason}} | {error,Term}
		  Args = Reason	= Term = term()

	  Note:
	      This callback is optional, so callback modules need  not	export
	      it. The gen_event	module provides	a default implementation with-
	      out cleanup.

	      Whenever an event	handler	is deleted from	an event manager, this
	      function	is  called.  It	is to be the opposite of Module:init/1
	      and do any necessary cleaning up.

	      If the event handler is deleted because of a call	to delete_han-
	      dler/3,  swap_handler/3,	or swap_sup_handler/3, Arg is the Args
	      argument of this function	call.

	      Arg={stop,Reason}	if the event handler has a supervised  connec-
	      tion to a	process	that has terminated with reason	Reason.

	      Arg=stop	if the event handler is	deleted	because	the event man-
	      ager is terminating.

	      The event	manager	terminates if it is part of a supervision tree
	      and  it is ordered by its	supervisor to terminate. Even if it is
	      not part of a supervision	tree, it terminates if it receives  an
	      'EXIT' message from its parent.

	      Arg=remove_handler  if  the event	handler	is deleted because an-
	      other callback function  has  returned  remove_handler  or  {re-
	      move_handler,Reply}.

	      Arg={error,Term} if the event handler is deleted because a call-
	      back function returned an	unexpected  value  Term,  or  Arg={er-
	      ror,{'EXIT',Reason}} if a	callback function failed.

	      State is the internal state of the event handler.

	      The  function  can  return  any  term.  If  the event handler is
	      deleted because of a call	to gen_event:delete_handler/3, the re-
	      turn  value  of  that  function becomes the return value of this
	      function.	If the event handler is	to be  replaced	 with  another
	      event  handler  because of a swap, the return value is passed to
	      the init function	of the new event handler. Otherwise the	return
	      value is ignored.

SEE ALSO
       supervisor(3), sys(3)

Ericsson AB			  stdlib 3.17			  gen_event(3)

NAME | DESCRIPTION | DATA TYPES | 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_event&sektion=3&manpath=FreeBSD+13.1-RELEASE+and+Ports>

home | help