👤
Home Man
Search
Today's Posts
Register

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

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

gen_event(3erl) 		     Erlang Module Definition			  gen_event(3erl)

NAME
       gen_event - Generic Event Handling Behaviour

DESCRIPTION
       A  behaviour  module for implementing event handling functionality. The OTP event handling
       model consists of a generic event manager process with an arbitrary number of  event  han-
       dlers which are added and deleted dynamically.

       An event manager implemented using this module will have a standard set of interface func-
       tions and include functionality for tracing and error reporting. It will also fit into  an
       OTP supervision tree. Refer to OTP Design Principles for more information.

       Each  event  handler  is  implemented  as a callback module exporting a pre-defined set of
       functions. The relationship between the behaviour functions and the callback functions can
       be illustrated as follows:

       gen_event module 		  Callback module
       ---------------- 		  ---------------
       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: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

       Since  each event handler is one callback module, an event manager will have several call-
       back modules which are added and deleted dynamically. Therefore gen_event is more tolerant
       of  callback  module  errors  than  the	other  behaviours.  If a callback function for an
       installed event handler fails with Reason , or returns a bad value Term , the  event  man-
       ager will not fail. It will delete the event handler by calling the callback function Mod-
       ule:terminate/2 (see below), giving as argument {error,{'EXIT',Reason}} or {error,Term}	,
       respectively. No other event handler will be affected.

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

       Note that an event manager does trap exit signals automatically.

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

       It's also worth noting that when multiple event handlers are invoked, it's 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 specified event manager
       does not exist or if bad arguments are given.

EXPORTS
       start_link() -> Result
       start_link(EventMgrName) -> Result

	      Types  EventMgrName = {local,Name} | {global,Name}
		     Name = atom()
		     Result = {ok,Pid} | {error,{already_started,Pid}}
		     Pid = pid()

	      Creates an event manager process as part of a supervision tree. The function should
	      be  called, directly or indirectly, by the supervisor. It will, among other things,
	      ensure that the event manager is linked to the supervisor.

	      If EventMgrName={local,Name} , the event manager	is  registered	locally  as  Name
	      using  register/2 . If EventMgrName={global,Name} , the event manager is registered
	      globally as Name using global:register_name/2 . If no name is provided,  the  event
	      manager is not registered.

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

       start() -> Result
       start(EventMgrName) -> Result

	      Types  EventMgrName = {local,Name} | {global,Name}
		     Name = atom()
		     Result = {ok,Pid} | {error,{already_started,Pid}}
		     Pid = pid()

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

	      See start_link/0,1 for a description of arguments and return values.

       add_handler(EventMgrRef, Handler, Args) -> Result

	      Types  EventMgr = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     Handler = Module | {Module,Id}
		     Module = atom()
		     Id = term()
		     Args = term()
		     Result = ok | {'EXIT',Reason} | term()
		     Reason = term()

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

	      EventMgrRef can be:

		* the pid,

		* Name , if the event manager is locally registered,

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

		* {global,Name} , if the event manager is globally registered.

	      Handler is the name of the callback module Module or a tuple {Module,Id} , where Id
	      is  any  term.  The {Module,Id} representation makes it possible to identify a spe-
	      cific event handler when there are several event handlers using the  same  callback
	      module.

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

	      If  Module:init/1 returns a correct value, the event manager adds the event handler
	      and this function returns ok . If Module:init/1 fails with  Reason  or  returns  an
	      unexpected  value  Term  ,  the  event handler is ignored and this function returns
	      {'EXIT',Reason} or Term , respectively.

       add_sup_handler(EventMgrRef, Handler, Args) -> Result

	      Types  EventMgr = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     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 will  also	supervise
	      the connection between the event handler and the calling process.

		* If  the  calling  process later terminates with Reason , the event manager will
		  delete the event handler by calling Module:terminate/2  with	{stop,Reason}  as
		  argument.

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

		  * normal  ,  if the event handler has been removed due to a call to delete_han-
		    dler/3 , or remove_handler has been returned  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 due to an error. Which  term  depends
		    on the error.

	      See add_handler/3 for a description of the arguments and return values.

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

	      Types  EventMgrRef = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     Event = term()

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

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

	      See add_handler/3 for a description of EventMgrRef .

	      Event  is  an arbitrary term which is passed as one of the arguments to Module:han-
	      dle_event/2 .

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

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

	      Types  EventMgrRef = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     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 the event handler Handler installed in the event man-
	      ager EventMgrRef by sending a request and waiting until a reply arrives or a  time-
	      out occurs. The event manager will call Module:handle_call/2 to handle the request.

	      See add_handler/3 for a description of EventMgrRef and Handler .

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

	      Timeout is an integer greater than zero which specifies how  many  milliseconds  to
	      wait for a reply, or the atom infinity to wait indefinitely. Default value is 5000.
	      If no reply is received within the specified time, the function call fails.

	      The return value Reply is defined in the return value of Module:handle_call/2 .  If
	      the  specified event handler is not installed, the function returns {error,bad_mod-
	      ule} . If the callback function fails with Reason or returns  an	unexpected  value
	      Term  ,  this  function  returns	{error,{'EXIT',Reason}} or {error,Term} , respec-
	      tively.

       delete_handler(EventMgrRef, Handler, Args) -> Result

	      Types  EventMgrRef = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     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 the event manager EventMgrRef  .  The  event  manager
	      will call Module:terminate/2 to terminate the event handler.

	      See add_handler/3 for a description of EventMgrRef and Handler .

	      Args  is an arbitrary term which is passed as one of the arguments to Module:termi-
	      nate/2 .

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

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

	      Types  EventMgrRef = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     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 the event manager EventM-
	      grRef .

	      See add_handler/3 for a description of the arguments.

	      First  the  old  event  handler  Handler1  is deleted. The event manager calls Mod-
	      ule1: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 Mod-
	      ule2:init({Args2,Term}) , where Module2 is the callback module of Handler2 and Term
	      the return value of Module1:terminate/2 . This makes it possible to transfer infor-
	      mation from Handler1 to Handler2 .

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

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

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

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

	      Types  EventMgrRef = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()
		     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 the event manager  EventMgrRef  in  the  same  way  as
	      swap_handler/3  but  will  also  supervise  the connection between Handler2 and the
	      calling process.

	      See swap_handler/3 for a description of the arguments and return values.

       which_handlers(EventMgrRef) -> [Handler]

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

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

	      See add_handler/3 for a description of EventMgrRef and Handler .

       stop(EventMgrRef) -> ok

	      Types  EventMgrRef = Name | {Name,Node} | {global,Name} | pid()
		     Name = Node = atom()

	      Terminates the event manager EventMgrRef . Before terminating,  the  event  manager
	      will call Module:terminate(stop,...) for each installed event handler.

	      See add_handler/3 for a description of the argument.

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

EXPORTS
       Module:init(InitArgs) -> {ok,State} | {ok,State,hibernate}

	      Types  InitArgs = Args | {Args,Term}
		     Args = Term = term()
		     State = 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	due  to  a  call  to  gen_event:add_handler/3  or
	      gen_event:add_sup_handler/3 , InitArgs is the Args argument of these functions.

	      If  the  event  handler  is  replacing  another  event  handler  due  to	a call to
	      gen_event:swap_handler/3 or gen_event:swap_sup_handler/3 , or due to a swap  return
	      tuple  from  one	of  the other callback functions, InitArgs is a tuple {Args,Term}
	      where Args is the argument provided in the function call/return tuple and  Term  is
	      the result of terminating the old event handler, see gen_event:swap_handler/3 .

	      The  function  should return {ok,State} or {ok,State, hibernate} where State is the
	      initial internal state of the event handler.

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

       Module:handle_event(Event, State) -> Result

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

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

	      Event is the Event argument of notify / sync_notify .

	      State is the internal state of the event handler.

	      If  the function returns {ok,NewState} or {ok,NewState,hibernate} the event handler
	      will remain in the event manager with the possible updated internal state  NewState
	      .

	      If  {ok,NewState,hibernate} is returned, the event manager will also go into hiber-
	      nation (by calling proc_lib:hibernate/3 ), waiting for the next event to occur.  It
	      is sufficient that one of the event handlers return {ok,NewState,hibernate} for the
	      whole event manager process to hibernate.

	      If the function returns {swap_handler,Args1,NewState,Handler2,Args2} the event han-
	      dler will be replaced by Handler2 by first calling Module:terminate(Args1,NewState)
	      and then Module2:init({Args2,Term}) where Term is the return value of Module:termi-
	      nate/2 . See gen_event:swap_handler/3 for more information.

	      If the function returns remove_handler the event handler will be deleted by calling
	      Module:terminate(remove_handler,State) .

       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 gen_event:call/3,4  ,  this
	      function is called for the specified event handler to handle the request.

	      Request is the Request argument of call .

	      State is the internal state of the event handler.

	      The  return  values  are	the same as for handle_event/2 except they also contain a
	      term Reply which is the reply given back to the client as the return value of  call
	      .

       Module:handle_info(Info, State) -> Result

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

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

	      Info is the received message.

	      See Module:handle_event/2 for a description of State and possible return values.

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

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

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

	      If  the  event  handler  is  deleted  due  to  a call to gen_event:delete_handler ,
	      gen_event:swap_handler/3 or gen_event:swap_sup_handler/3 , Arg is the Args argument
	      of this function call.

	      Arg={stop,Reason}  if  the  event  handler has a supervised connection to a process
	      which has terminated with reason Reason .

	      Arg=stop if the event handler is deleted because the event manager is terminating.

	      The event manager will terminate 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 will terminate if it receives an 'EXIT' message from its parent.

	      Arg=remove_handler if the event handler is deleted because another  callback  func-
	      tion has returned remove_handler or {remove_handler,Reply} .

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

	      State is the internal state of the event handler.

	      The  function may return any term. If the event handler is deleted due to a call to
	      gen_event:delete_handler , the return value of that function  will  be  the  return
	      value  of  this function. If the event handler is to be replaced with another event
	      handler due to a swap, the return value will be passed to the init function of  the
	      new event handler. Otherwise the return value is ignored.

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

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

	      This  function  is  called  for  an installed event handler which should update its
	      internal state during  a	release  upgrade/downgrade,  i.e.  when  the  instruction
	      {update,Module,Change,...}  where  Change={advanced,Extra}  is  given in the .appup
	      file. See OTP Design Principles for more information.

	      In the case of an upgrade, OldVsn is Vsn , and in the case of a  downgrade,  OldVsn
	      is  {down,Vsn}  .  Vsn is defined by the vsn attribute(s) of the old version of the
	      callback module Module . If no such attribute is defined, the version is the check-
	      sum 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 should return the updated internal state.

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

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

   Note:
       This  callback is optional, so event handler modules need not export it. If a handler does
       not export this function, the gen_event module uses the handler	state  directly  for  the
       purposes described below.

       This function is called by a gen_event process when:

	 * 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 customising the form and appearance of the event handler state
       for these cases. An event handler callback module wishing to  customise	the  sys:get_sta-
       tus/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 gen_event's process dictionary.

       State is the internal state of the event handler.

       The  function  should  return  Status  , a term that customises 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 event handler's actual state term.

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

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

SEE ALSO
       supervisor(3erl) , sys(3erl)

Ericsson AB				  stdlib 1.17.3 			  gen_event(3erl)


All times are GMT -4. The time now is 01:44 PM.

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





Not a Forum Member?
Forgot Password?