gen_event

gen_event(3)               ERLANG MODULE DEFINITION               gen_event(3)



MODULE
       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            ----->  -

       gen_event:add_handler
       gen_event:add_suphandler   ----->  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.

       The sys module can be used for debugging an event manager.

       Note that an event manager does trap exit signals automatically.

       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() -> Result
       start(EventMgrName) -> Result
       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.

              An event manager started using start_link is linked to the
              calling process. This function must be used if the event manager
              is included in a supervision tree. An event manager started
              using start is not linked to the calling process.

              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.

       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 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, 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_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, 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: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, 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 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, 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: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, 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 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, 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}

              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} where State is the
              initial internal state of the event handler.

       Module:handle_event(Event, State) -> Result

              Types  Event = term()
                     State = term()
                     Result = {ok, NewState}
                     Â | {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} the event handler will
              remain in the event manager with the possible updated internal
              state NewState.

              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}
                     Â | {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}
                     Â | {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.

              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 = undefined | term()
                     State = NewState = term()
                     Extra = term()

              This function is called for each installed event handler they
              should update the internal state due to code replacement, i.e.
              when the instruction {update, Module, Change, PrePurge,
              PostPurge, Modules where Change={advanced, Extra} has been given
              to the release handler. See SASL User's Guide for more
              information.

              OldVsn is the vsn attribute of the old version of the callback
              module Module, or undefined if no such attribute is defined.

              State is the internal state of the event handler.

              Extra is the same as in the {advanced, Extra} part of the update
              instruction.

              The function should return {ok, NewState}, where NewState is the
              updated internal state.

SEE ALSO
       supervisor(3), sys(3)

AUTHOR
       Gunilla Hugosson - support@erlang.ericsson.se



Ericsson Utvecklings AB         stdlib  1.10.1                    gen_event(3)