Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

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
       handlers which are added and deleted dynamically.

       An  event  manager  implemented  using  this  module will have a standard set of interface
       functions 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
       callback 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
       manager  will  not fail. It will delete the event handler by calling the callback function
       Module: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.

DATA TYPES

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

       handler_args() = term()

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

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

EXPORTS

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

              Types:

                 EventMgrName = {local,Name} | {global,GlobalName} | {via,Module,ViaName}
                  Name = atom()
                  GlobalName = ViaName = term()
                 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,GlobalName},  the event manager is registered
              globally as GlobalName using global:register_name/2. If no name  is  provided,  the
              event  manager  is  not registered. If EventMgrName={via,Module,ViaName}, the event
              manager will register with the registry represented by Module. The Module  callback
              should  export the functions register_name/2, unregister_name/1, whereis_name/1 and
              send/2, which should behave like  the  corresponding  functions  in  global.  Thus,
              {via,global,GlobalName} is a valid reference.

              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,GlobalName} | {via,Module,ViaName}
                  Name = atom()
                  GlobalName = ViaName = term()
                 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,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 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,GlobalName}, if the event manager is globally registered.

                * {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}  representation  makes  it  possible to identify a
              specific 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 indicating successful completion, the
              event manager adds the event handler and this function returns ok. If Module:init/1
              fails  with Reason or returns {error,Reason}, the event handler is ignored and this
              function returns {'EXIT',Reason} or {error,Reason}, respectively.

       add_sup_handler(EventMgrRef, Handler, Args) -> Result

              Types:

                 EventMgr = 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 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_handler/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,GlobalName} | {via,Module,ViaName}  |
                 pid()
                  Name = Node = atom()
                  GlobalName = ViaName = term()
                 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:handle_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,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 the  event  handler  Handler  installed  in  the  event
              manager  EventMgrRef  by  sending  a request and waiting until a reply arrives or a
              timeout 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:handle_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_module}. If the callback  function  fails  with  Reason  or  returns  an
              unexpected   value   Term,   this   function   returns  {error,{'EXIT',Reason}}  or
              {error,Term}, respectively.

       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 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:terminate/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,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  the  event  manager
              EventMgrRef.

              See add_handler/3 for a description of the arguments.

              First  the  old  event  handler  Handler1  is  deleted.  The  event  manager  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 callback module  of  Handler2  and
              Term  the  return  value of Module1:terminate/2. This makes it possible to transfer
              information 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
              Module2: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
              Module2:init/1  fails  with  Reason  or returns an unexpected value Term, this 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  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,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 the event manager EventMgrRef.

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

       stop(EventMgrRef) -> ok

              Types:

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

              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} | {error,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  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.

              If successful, 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
              hibernation (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
              handler     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:terminate/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
              message).

              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
              function 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
              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 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_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 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)