gen_event(3)



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

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(3erl).
       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.

       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  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(3erl). 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  from  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}}.

       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(3erl), sys(3erl)

Ericsson AB                       stdlib 3.13                  gen_event(3erl)

Man(1) output converted with man2html
list of all man pages