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
information, see
Each event handler is implemented as a callback module exporting a predefined set of functions. The relationship between the behavior functions 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.
A
Notice that an event manager does trap exit signals automatically.
The
Notice that when multiple event handlers are
invoked, it is sufficient that one single event handler returns a
Unless otherwise stated, all functions in this module fail if the specified event manager does not exist or if bad arguments are specified.
For some important information about distributed signals, see the
An opaque request identifier. See
An opaque collection of request identifiers
(
Used to set a time limit on how long to wait for a response using
either
Timeout relative to current time in milliseconds.
Infinite timeout. That is, the operation will never time out.
An absolute
A map that describes the
New associations may be added into the status map without prior notice.
Adds a new event handler to event manager
If
Adds a new event handler in the same way as
If the event handler is deleted later, the event manager
sends a message
A term, if the event handler is removed because of an error. Which term depends on the error.
For a description of the arguments and return values, see
Makes a synchronous call to event handler
For a description of
The return value
When this call fails it
Check if
If
If the specified event handler is not
installed, the function returns
Check if
The
Compared to
If
If
Deletes an event handler from event manager
For a description of
The return value is the return value of
Sends an event notification to event manager
For a description of
Receive a response corresponding to the request identifier
The return value
If the specified event handler is not
installed, the function returns
The difference between
Receive a response corresponding to a request identifier saved
in
The
Compared to
If
The difference between
If
Saves
Returns a new empty request identifier collection. A request identifier collection can be utilized in order the handle multiple outstanding requests.
Request identifiers of requests made by
Returns the amount of request identifiers saved in
Returns a list of
Sends an asynchronous
The call
The event manager calls
Sends an asynchronous
The same as calling
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
Creates an event manager process as part of a supervision tree. The function is to be called, directly or indirectly, by the supervisor. For example, it ensures that the event manager is linked to the supervisor.
If
If
If
If option
If the event manager is successfully created, the function
returns
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 created process.
For a description of the arguments and return values, see
Orders event manager
The function returns
If the process does not exist, the call exits
the calling process with reason
For a description of
Replaces an old event handler with a new event handler in
event manager
For a description of the arguments, see
First the old event handler
Then the new event handler
The new handler is added even if the the specified old event
handler is not installed, in which case
If there was a supervised connection between
If
Replaces an event handler in event manager
For a description of the arguments and return values, see
Wait for a response corresponding to the request identifier
The return value
If the specified event handler is not
installed, the function returns
The difference between
Wait for a response corresponding to a request identifier saved
in
The
Compared to
If
The difference between
If
Returns a list of all event handlers installed in event
manager
For a description of
The following functions are to be exported from a
This callback is optional, so callback modules need not export it.
If a release upgrade/downgrade with
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
For an upgrade,
The function is to return the updated internal state.
This callback is optional, so event handler modules need
not export it. If a handler does not export this function,
the
If this callback is exported but fails, to hide possibly sensitive
data, the default function will instead return the fact that
This function is called by a
This callback is used to limit the status of the event handler
returned by
The callback gets a map
Two possible use cases for this callback is to remove sensitive information from the state to prevent it from being printed in log files, or to compact large irrelevant status items that would only clutter the logs.
maps:map(
fun(state,State) ->
maps:remove(private_key, State);
(message,{password, _Pass}) ->
{password, removed};
(_,Value) ->
Value
end, Status).
]]>
This callback is deprecated, in new code use
This callback is optional, so event handler modules need
not export it. If a handler does not export this function,
the
This function is called by a
This function is useful for changing the form and
appearance of the event handler state for these cases. An
event handler callback module wishing to change the
the
The function is to return
When
When an event handler terminates abnormally,
One use for this function is to return compact alternative state representations to avoid that large state terms are printed in log files.
Whenever an event manager receives a request sent using
The return values are the same as for
Whenever an event manager receives an event sent using
If
If
If
If
This callback is optional, so callback modules need not
export it. The
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).
In particular, this callback will be made when a process terminated
after calling
For a description of
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
If the event handler replaces another event handler because of
a call to
If successful, the function returns
If
This callback is optional, so callback modules need not
export it. The
Whenever an event handler is deleted from an event manager,
this function is called. It is to be the opposite of
If the event handler is deleted because of a call to
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
The function can return any term. If the event handler is
deleted because of a call to