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)