View Source gen_event behaviour (stdlib v6.0)
Generic event handling behavior.
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 OTP Design Principles.
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/3As 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 behaviors. 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:terminate/2, giving as
argument {error,{'EXIT',Reason}} or {error,Term}, respectively. No other
event handler is affected.
A gen_event process handles system messages as described in sys. 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 specified event manager does not exist or if bad arguments are specified.
Note
For some important information about distributed signals, see the Blocking Signaling Over Distribution section in the Processes chapter of the Erlang Reference Manual. Blocking signaling can, for example, cause call timeouts in
gen_eventto be significantly delayed.
See Also
Summary
Types
The name given to an event manager when starting it.
A reference used to locate an event manager.
A map that describes the gen_event process status.
Options that can be used to configure an event handler when it is started.
An opaque request identifier. See send_request/3 for details.
An opaque collection of request identifiers (request_id/0) where each
request identifier can be associated with a label chosen by the user. For more
information see reqids_new/0.
Used to set a time limit on how long to wait for a response using either
receive_response/2, receive_response/3, wait_response/2, or
wait_response/3. The time unit used is millisecond. Currently valid values
Callbacks
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,...}, is specified in the appup file.
This function is called by a gen_event process in in order to format/limit the
server state for debugging and logging purposes.
This function is called by a gen_event process in in order to format/limit the
server state for debugging and logging purposes.
Whenever an event manager receives a request sent using call/3,4,
this function is called for the specified event handler to handle the request.
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.
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).
Whenever a new event handler is added to an event manager, this function is called to initialize the event handler.
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.
Functions
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.
Adds a new event handler in the same way as add_handler/3, but also supervises
the connection by linking the event handler and the calling process.
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.
Check if Msg is a response corresponding to the request identifier ReqId.
The request must have been made by send_request/3.
Check if Msg is a response corresponding to a request identifier saved in
ReqIdCollection. All request identifiers of ReqIdCollection must correspond
to requests that have been made using send_request/3 or send_request/5, and
all requests must have been made by the process calling this function.
Deletes an event handler from event manager EventMgrRef. The event manager
calls Module:terminate/2 to terminate the event handler.
Sends an asynchronous event notification to event manager EventMgrRef. The event
manager calls Module:handle_event/2 for each installed
event handler to handle the event.
Receive a response corresponding to the request identifier ReqId. The request
must have been made by send_request/3 to the gen_statem process. This
function must be called from the same process from which send_request/3 was
made.
Receive a response corresponding to a request identifier saved in
ReqIdCollection. All request identifiers of ReqIdCollection must correspond
to requests that have been made using send_request/3 or send_request/5, and
all requests must have been made by the process calling this function.
Saves ReqId and associates a Label with the request identifier by adding
this information to ReqIdCollection and returning the resulting request
identifier collection.
Returns a new empty request identifier collection. A request identifier collection can be utilized in order the handle multiple outstanding requests.
Returns the amount of request identifiers saved in ReqIdCollection.
Returns a list of {ReqId, Label} tuples which corresponds to all request
identifiers with their associated labels present in the ReqIdCollection
collection.
Sends an asynchronous call request Request to event handler Handler
installed in the event manager identified by EventMgrRef and returns a request
identifier ReqId. The return value ReqId shall later be used with
receive_response/2, wait_response/2, or check_response/2 to fetch the
actual result of the request.
Sends an asynchronous call request Request to event handler Handler
installed in the event manager identified by EventMgrRef. The Label will be
associated with the request identifier of the operation and added to the returned
request identifier collection NewReqIdCollection.
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.
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.
Equivalent to start_link([]).
Creates an event manager process as part of a supervision tree.
Creates an event manager process as part of a supervision tree.
Equivalent to start_monitor([]).
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.
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.
Equivalent to stop(EventMgrRef, normal, infinity).
Orders event manager EventMgrRef to exit with the specifies Reason and waits
for it to terminate. Before terminating, gen_event calls
Module:terminate(stop,...) for each installed event
handler.
Replaces an old event handler with a new event handler in event manager
EventMgrRef.
Replaces an event handler in event manager EventMgrRef in the same way as
swap_handler/3, but also supervises the connection between
NewHandler and the calling process.
Sends a synchronous event notification to event manager EventMgrRef. The event
manager calls Module:handle_event/2 for each installed event
handler to handle the event. This function will return ok after the event has
been handled by all event handlers.
Wait for a response corresponding to the request identifier ReqId. The request
must have been made by send_request/3 to the gen_statem process. This
function must be called from the same process from which send_request/3 was
made.
Wait for a response corresponding to a request identifier saved in
ReqIdCollection. All request identifiers of ReqIdCollection must correspond
to requests that have been made using send_request/3 or send_request/5, and
all requests must have been made by the process calling this function.
Returns a list of all event handlers installed in event manager EventMgrRef.
Types
-type debug_flag() :: trace | log | statistics | debug | {logfile, string()}.
The name given to an event manager when starting it.
{local,Name}- the event manager is registered locally asNameusingregister/2.{global,GlobalName}- The event manager is registered globally asGlobalNameusingglobal:register_name/2. If no name is provided, the event manager is not registered.{via,Module,ViaName}, the event manager registers with the registry represented byModule. TheModulecallback is to export the functionsregister_name/2,unregister_name/1,whereis_name/1, andsend/2, which are to behave as the corresponding functions inglobal. Thus,{via,global,GlobalName}is a valid reference.
A reference used to locate an event manager.
The reference can be any of the following:
- The pid of the event manager
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 registered{via,Module,ViaName}, if the event manager is registered through an alternative process registry
-type format_status() :: #{state => term(), message => term(), reason => term(), log => [sys:system_event()]}.
A map that describes the gen_event process status.
The keys are:
state- The internal state of the event handler.message- The message that caused the event handler to terminate.reason- The reason that caused the event handler to terminate.log- The sys log of the server.
New associations may be added into the status map without prior notice.
-type handler_args() :: term().
-type options() :: [{timeout, timeout()} | {debug, [debug_flag()]} | {spawn_opt, [proc_lib:start_spawn_option()]} | {hibernate_after, timeout()}].
Options that can be used to configure an event handler when it is started.
-opaque request_id()
An opaque request identifier. See send_request/3 for details.
-opaque request_id_collection()
An opaque collection of request identifiers (request_id/0) where each
request identifier can be associated with a label chosen by the user. For more
information see reqids_new/0.
Used to set a time limit on how long to wait for a response using either
receive_response/2, receive_response/3, wait_response/2, or
wait_response/3. The time unit used is millisecond. Currently valid values:
0..4294967295- Timeout relative to current time in milliseconds.infinity- Infinite timeout. That is, the operation will never time out.{abs, Timeout}- An absolute Erlang monotonic time timeout in milliseconds. That is, the operation will time out whenerlang:monotonic_time(millisecond)returns a value larger than or equal toTimeout.Timeoutis not allowed to identify a time further into the future than4294967295milliseconds. Identifying the timeout using an absolute timeout value is especially handy when you have a deadline for responses corresponding to a complete collection of requests (request_id_collection/0) , since you do not have to recalculate the relative time until the deadline over and over again.
Callbacks
-callback code_change(OldVsn :: term() | {down, term()}, State :: term(), Extra :: term()) -> {ok, NewState :: term()}.
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,...}, 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.
Note
If a release upgrade/downgrade with
Change={advanced,Extra}specified in the.appupfile is made whencode_change/3isn't implemented the event handler will crash with anundeferror reason.
-callback format_status(Status) -> NewStatus when Status :: format_status(), NewStatus :: format_status().
This function is called by a gen_event process in in order to format/limit the
server state for debugging and logging purposes.
It is called in the following situations:
- One of
sys:get_status/1,2is invoked to get thegen_eventstatus. - The event handler terminates abnormally and
gen_eventlogs an error.
This callback is used to limit the status of the event handler returned by
sys:get_status/1,2 or sent to logger.
The callback gets a map Status describing the current status and shall return
a map NewStatus with the same keys, but it may transform some values.
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.
Example:
format_status(Status) ->
maps:map(
fun(state,State) ->
maps:remove(private_key, State);
(message,{password, _Pass}) ->
{password, removed};
(_,Value) ->
Value
end, Status).Note
This callback is optional, so event handler modules need not export it. If a handler does not export this function, the
gen_eventmodule uses the handler state directly for the purposes described below.If this callback is exported but fails, to hide possibly sensitive data, the default function will instead return the fact that
format_status/1has crashed.
-callback format_status(Opt, StatusData) -> Status when Opt :: normal | terminate, StatusData :: [PDict | State], PDict :: [{Key :: term(), Value :: term()}], State :: term(), Status :: term().
This function is called by a gen_event process in in order to format/limit the
server state for debugging and logging purposes.
It is called in the following situations:
- One of
sys:get_status/1,2is invoked to get thegen_eventstatus.Optis set to the atomnormalfor this case. - The event handler terminates abnormally and
gen_eventlogs an error.Optis set to the atomterminatefor this case.
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 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,2is called,gen_eventensures that its return value containsStatusin place of the state term of the event handler. - When an event handler terminates abnormally,
gen_eventlogsStatusin 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.
Note
This callback is optional, so event handler modules need not export it. If a handler does not export this function, the
gen_eventmodule uses the handler state directly for the purposes described below.
-callback handle_call(Request :: term(), State :: term()) -> {ok, Reply :: term(), NewState :: term()} | {ok, Reply :: term(), NewState :: term(), hibernate} | {swap_handler, Reply :: term(), Args1 :: term(), NewState :: term(), Handler2 :: atom() | {atom(), Id :: term()}, Args2 :: term()} | {remove_handler, Reply :: term()}.
Whenever an event manager receives a request sent using call/3,4,
this function is called for the specified event handler 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 except that they also contain a
term Reply, which is the reply to the client as the return value of
call/3,4.
-callback handle_event(Event :: term(), State :: term()) -> {ok, NewState :: term()} | {ok, NewState :: term(), hibernate} | {swap_handler, Args1 :: term(), NewState :: term(), Handler2 :: atom() | {atom(), Id :: term()}, Args2 :: term()} | remove_handler.
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 stateNewState. - If
{ok,NewState,hibernate}is returned, the event manager also goes into hibernation (by callingproc_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
{swap_handler,Args1,NewState,Handler2,Args2}is returned, the event handler is replaced byHandler2by first callingModule:terminate(Args1,NewState)and thenModule2:init({Args2,Term}), whereTermis the return value ofModule:terminate/2. For more information, seeswap_handler/3. - If
remove_handleris returned, the event handler is deleted by callingModule:terminate(remove_handler,State).
-callback handle_info(Info :: term(), State :: term()) -> {ok, NewState :: term()} | {ok, NewState :: term(), hibernate} | {swap_handler, Args1 :: term(), NewState :: term(), Handler2 :: atom() | {atom(), Id :: term()}, Args2 :: term()} | remove_handler.
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.
In particular, this callback will be made when a process terminated after
calling add_sup_handler/3. Any event handler attached to an event manager
which in turn has a supervised handler should expect callbacks of the shape
Module:handle_info({'EXIT', Pid, Reason}, State).
For a description of State and possible return values, see
Module:handle_event/2.
Note
This callback is optional, so callback modules need not export it. The
gen_eventmodule provides a default implementation of this function that logs about the unexpectedInfomessage, drops it and returns{ok, State}.
-callback init(InitArgs :: term()) -> {ok, State :: term()} | {ok, State :: term(), hibernate} | {error, 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, 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 swap_handler/3.
If successful, the function returns {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 goes into hibernation
(by calling proc_lib:hibernate/3), waiting for the next event to occur.
-callback terminate(Args :: term() | {stop, Reason :: term()} | stop | remove_handler | {error, {'EXIT', Reason :: term()}} | {error, term()}, State :: term()) -> term().
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_handler/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 connection to a
process that has terminated with reason Reason.
Arg=stop if the event handler is deleted because the event manager 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 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 can return any term. If the event handler is deleted because of a
call to gen_event:delete_handler/3, the return 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.
Note
This callback is optional, so callback modules need not export it. The
gen_eventmodule provides a default implementation without cleanup.
Functions
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.
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 many event handlers use the same callback
module.
Args is any term that 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.
Adds a new event handler in the same way as add_handler/3, but also supervises
the connection by linking the event handler and the calling process.
- If the calling process later terminates with
Reason, the event manager deletes any supervised event handlers by callingModule:terminate/2, then callsModule:handle_info/2for each remaining handler. - If the event handler is deleted later, the event manager sends a message
{gen_event_EXIT,Handler,Reason}to the calling process.Reasonis one of the following:normal, if the event handler has been removed because of a call todelete_handler/3, orremove_handlerhas 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 processPidhas replaced the event handler with another event handlerNewHandlerusing a call toswap_handler/3orswap_sup_handler/3.- 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 add_handler/3.
Equivalent to call(EventMgrRef, Handler, Request, 5000).
-spec call(EventMgrRef :: emgr_ref(), Handler :: handler(), Request :: term(), Timeout :: timeout()) -> 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.
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
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.
When this call fails it exits the calling process. The exit
term is on the form {Reason, Location} where
Location = {gen_event,call,ArgList}. See
gen_server:call/3 that has a description of relevant
values for the Reason in the exit term.
-spec check_response(Msg, ReqId) -> Result when Msg :: term(), ReqId :: request_id(), Response :: {reply, Reply :: term()} | {error, {Reason :: term(), emgr_ref()}}, Result :: Response | no_reply.
Check if Msg is a response corresponding to the request identifier ReqId.
The request must have been made by send_request/3.
If Msg is a response corresponding to ReqId the response is returned;
otherwise, no_reply is returned and no cleanup is done, and thus the function
must be invoked repeatedly until a response 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 returns {error,{'EXIT',Reason}} or
{error,Term}, respectively. If the event manager dies before or during the
request this function returns {error,{Reason, EventMgrRef}}.
-spec check_response(Msg, ReqIdCollection, Delete) -> Result when Msg :: term(), ReqIdCollection :: request_id_collection(), Delete :: boolean(), Response :: {reply, Reply :: term()} | {error, {Reason :: term(), emgr_ref()}}, Result :: {Response, Label :: term(), NewReqIdCollection :: request_id_collection()} | no_request | no_reply.
Check if Msg is a response corresponding to a request identifier saved in
ReqIdCollection. All request identifiers of ReqIdCollection must correspond
to requests that have been made using send_request/3 or send_request/5, and
all requests must have been made by the process calling this function.
The Label in the response equals the Label associated with the request
identifier that the response corresponds to. The Label of a request identifier
is associated when saving the request id in a request
identifier collection, or when sending the request using send_request/5.
Compared to check_response/2, the returned result associated with a specific
request identifier or an exception associated with a specific request identifier
will be wrapped in a 3-tuple. The first element of this tuple equals the value
that would have been produced by check_response/2, the
second element equals the Label associated with the specific request
identifier, and the third element NewReqIdCollection is a possibly modified
request identifier collection.
If ReqIdCollection is empty, the atom no_request will be returned. If Msg
does not correspond to any of the request identifiers in ReqIdCollection, the
atom no_reply is returned.
If Delete equals true, the association with Label will have been deleted
from ReqIdCollection in the resulting NewReqIdCollection. If Delete equals
false, NewReqIdCollection will equal ReqIdCollection. Note that deleting
an association is not for free and that a collection containing already handled
requests can still be used by subsequent calls to
check_response/3, receive_response/3, and
wait_response/3. However, without deleting handled associations, the above
calls will not be able to detect when there are no more outstanding requests to
handle, so you will have to keep track of this some other way than relying on a
no_request return. Note that if you pass a collection only containing
associations of already handled or abandoned requests to
check_response/3, it will always return no_reply.
Deletes an event handler from event manager EventMgrRef. The event manager
calls Module:terminate/2 to terminate the event handler.
Args is any term that 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}.
Sends an asynchronous event notification to event manager EventMgrRef. The event
manager calls Module:handle_event/2 for each installed
event handler to handle the event.
Event is any term that is passed as one of the arguments to
Module:handle_event/2.
notify/1 does not fail even if the specified event manager does not exist,
unless it is specified as Name.
-spec receive_response(ReqId, Timeout) -> Result when ReqId :: request_id(), Timeout :: response_timeout(), Response :: {reply, Reply :: term()} | {error, {Reason :: term(), emgr_ref()}}, Result :: Response | timeout.
Receive a response corresponding to the request identifier ReqId. The request
must have been made by send_request/3 to the gen_statem process. This
function must be called from the same process from which send_request/3 was
made.
Timeout specifies how long to wait for a response. If no response is received
within the specified time, the function returns timeout. Assuming that the
server executes on a node supporting aliases (introduced in OTP 24) the request
will also be abandoned. That is, no response will be received after a timeout.
Otherwise, a stray response might be received at a later time.
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. If the event manager dies before or during the
request this function returns {error,{Reason, EventMgrRef}}.
The difference between wait_response/2 and
receive_response/2 is that
receive_response/2 abandons the request at timeout so
that a potential future response is ignored, while
wait_response/2 does not.
receive_response(ReqIdCollection, Timeout, Delete)
View Source (since OTP 25.0)-spec receive_response(ReqIdCollection, Timeout, Delete) -> Result when ReqIdCollection :: request_id_collection(), Timeout :: response_timeout(), Delete :: boolean(), Response :: {reply, Reply :: term()} | {error, {Reason :: term(), emgr_ref()}}, Result :: {Response, Label :: term(), NewReqIdCollection :: request_id_collection()} | no_request | timeout.
Receive a response corresponding to a request identifier saved in
ReqIdCollection. All request identifiers of ReqIdCollection must correspond
to requests that have been made using send_request/3 or send_request/5, and
all requests must have been made by the process calling this function.
The Label in the response equals the Label associated with the request
identifier that the response corresponds to. The Label of a request identifier
is associated when adding the request id in a request
identifier collection, or when sending the request using send_request/5.
Compared to receive_response/2, the returned result associated with a specific
request identifier will be wrapped in a 3-tuple. The first element of this tuple
equals the value that would have been produced by
receive_response/2, the second element equals the
Label associated with the specific request identifier, and the third element
NewReqIdCollection is a possibly modified request identifier collection.
If ReqIdCollection is empty, the atom no_request will be returned.
Timeout specifies how long to wait for a response. If no response is received
within the specified time, the function returns timeout. Assuming that the
server executes on a node supporting aliases (introduced in OTP 24) all requests
identified by ReqIdCollection will also be abandoned. That is, no responses
will be received after a timeout. Otherwise, stray responses might be received
at a later time.
The difference between receive_response/3 and
wait_response/3 is that receive_response/3 abandons
the requests at timeout so that potential future responses are ignored, while
wait_response/3 does not.
If Delete equals true, the association with Label will have been deleted
from ReqIdCollection in the resulting NewReqIdCollection. If Delete equals
false, NewReqIdCollection will equal ReqIdCollection. Note that deleting
an association is not for free and that a collection containing already handled
requests can still be used by subsequent calls to
receive_response/3, check_response/3, and
wait_response/3. However, without deleting handled associations, the above
calls will not be able to detect when there are no more outstanding requests to
handle, so you will have to keep track of this some other way than relying on a
no_request return. Note that if you pass a collection only containing
associations of already handled or abandoned requests to
receive_response/3, it will always block until a
timeout determined by Timeout is triggered.
-spec reqids_add(ReqId :: request_id(), Label :: term(), ReqIdCollection :: request_id_collection()) -> NewReqIdCollection :: request_id_collection().
Saves ReqId and associates a Label with the request identifier by adding
this information to ReqIdCollection and returning the resulting request
identifier collection.
-spec reqids_new() -> NewReqIdCollection :: request_id_collection().
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 send_request/3 can be saved in a
request identifier collection using reqids_add/3. Such a collection of request
identifiers can later be used in order to get one response corresponding to a
request in the collection by passing the collection as argument to
receive_response/3, wait_response/3, or, check_response/3.
reqids_size/1 can be used to determine the amount of request identifiers in a
request identifier collection.
-spec reqids_size(ReqIdCollection :: request_id_collection()) -> non_neg_integer().
Returns the amount of request identifiers saved in ReqIdCollection.
-spec reqids_to_list(ReqIdCollection :: request_id_collection()) -> [{ReqId :: request_id(), Label :: term()}].
Returns a list of {ReqId, Label} tuples which corresponds to all request
identifiers with their associated labels present in the ReqIdCollection
collection.
-spec send_request(EventMgrRef :: emgr_ref(), Handler :: handler(), Request :: term()) -> ReqId :: request_id().
Sends an asynchronous call request Request to event handler Handler
installed in the event manager identified by EventMgrRef and returns a request
identifier ReqId. The return value ReqId shall later be used with
receive_response/2, wait_response/2, or check_response/2 to fetch the
actual result of the request.
Besides passing the request identifier directly to these functions, it can also
be saved in a request identifier collection using reqids_add/3. Such a
collection of request identifiers can later be used in
order to get one response corresponding to a request in the collection by
passing the collection as argument to receive_response/3, wait_response/3,
or check_response/3. If you are about to save the request identifier in a
request identifier collection, you may want to consider using send_request/5
instead.
The call
gen_event:receive_response(gen_event:send_request(EventMgrRef, 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 request.
Request is any term that is passed as one of the arguments to
Module:handle_call/2.
send_request(EventMgrRef, Handler, Request, Label, ReqIdCollection)
View Source (since OTP 25.0)-spec send_request(EventMgrRef :: emgr_ref(), Handler :: handler(), Request :: term(), Label :: term(), ReqIdCollection :: request_id_collection()) -> NewReqIdCollection :: request_id_collection().
Sends an asynchronous call request Request to event handler Handler
installed in the event manager identified by EventMgrRef. The Label will be
associated with the request identifier of the operation and added to the returned
request identifier collection NewReqIdCollection.
The collection can later be used in order to get one response corresponding to a
request in the collection by passing the collection as argument to receive_response/3,
wait_response/3, or check_response/3.
The same as calling
gen_event:reqids_add(gen_event:send_request(EventMgrRef, Handler, Request), Label, ReqIdCollection),
but calling send_request/5 is slightly more efficient.
-spec start() -> start_ret().
Equivalent to start([]).
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/1.
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/2.
-spec start_link() -> start_ret().
Equivalent to start_link([]).
Creates an event manager process as part of a supervision tree.
If called with emgr_name/0, then it is equivalent to start(EventMgrName, []).
If called with options/0, then a nameless event manager is created using Options.
For a description of the arguments and return values, see
start_link/2.
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 caller (supervisor).
- If option
{hibernate_after,HibernateAfterTimeout}is present, thegen_eventprocess awaits any message forHibernateAfterTimeoutmilliseconds and if no message is received, the process goes into hibernation automatically (by callingproc_lib:hibernate/3).
If the event manager is successfully created, the function returns {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,OtherPid}}, where OtherPid is the pid of
that process, and the event manager process exits with reason normal.
If the event manager fails to start within the specified start timeout
{timeout,Time}, which is very unlikely since the start does not interact with
other processes, the function returns {error,timeout} and the failed event
manager is killed with exit(_, kill).
If start_link/1,2 returns {error,_}, the started event manager process has
terminated. If an 'EXIT' message was delivered to the calling process (due to
the process link), that message has been consumed.
Warning
Before OTP 26.0, if the started event manager failed to register its name, this founction could return
{error,{already_started,OtherPid}}before the started event manager process had terminated so starting again might fail because the registered name was not yet unregistered, and an'EXIT'message could arrive later to the process calling this function.But if the start timed out, this function killed the started event manager process and returned
{error,timeout}, and then the process link{'EXIT',Pid,killed}message was consumed.The start was made synchronous in OTP 26.0 and the guarantee was implemented that no process link
'EXIT'message from a failed start will linger in the caller's inbox.
-spec start_monitor() -> start_mon_ret().
Equivalent to start_monitor([]).
-spec start_monitor(EventMgrNameOrOptions :: emgr_name() | options()) -> start_mon_ret().
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 start_monitor/2 and
start_link/1.
-spec start_monitor(EventMgtName :: emgr_name(), Options :: options()) -> start_mon_ret().
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
start_link/2. Note that the return value on successful
start differs from start_link/2. start_monitor/0,1,2 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.
-spec stop(EventMgrRef :: emgr_ref()) -> ok.
Equivalent to stop(EventMgrRef, normal, infinity).
Orders event manager EventMgrRef to exit with the specifies Reason and waits
for it to terminate. Before terminating, gen_event calls
Module:terminate(stop,...) for each installed event
handler.
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 logger.
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. If the event manager has not terminated
within the specified time, the call exits the calling process with reason
timeout.
If the process does not exist, the call exits the calling process with reason
noproc, and with reason {nodedown,Node} if the connection fails to the
remote Node where the server runs.
-spec swap_handler(EventMgrRef :: emgr_ref(), OldHandler :: {handler(), term()}, NewHandler :: {handler(), term()}) -> ok | {error, term()}.
Replaces an old event handler with a new event handler in event manager
EventMgrRef.
For a description of OldHandler and NewHandler, see add_handler/3.
First the old event handler OldHandler is deleted. The event manager calls
OldModule:terminate(Args1, ...), where OldModule is the callback module of
OldHandler, and collects the return value.
Then the new event handler NewHandler is added and initiated by calling
NewModule:init({Args2,Term}), where NewModule is the callback
module of OldHandler and Term is the return value of
OldModule:terminate/2. This makes it possible to transfer
information from OldHandler to NewHandler.
The new handler is added even if the the specified old event handler is not
installed, in which case Term=error, or if
OldModule:terminate/2 fails with Reason, in which case
Term={'EXIT',Reason}. The old handler is deleted even if
NewModule:init/1 fails.
If there was a supervised connection between OldHandler and a process Pid,
there is a supervised connection between NewHandler and Pid instead.
If NewModule:init/1 returns a correct value, this function returns
ok. If NewModule:init/1 fails with Reason or returns an
unexpected value Term, this function returns {error,{'EXIT',Reason}} or
{error,Term}, respectively.
-spec swap_sup_handler(EventMgrRef :: emgr_ref(), OldHandler :: {handler(), term()}, NewHandler :: {handler(), term()}) -> ok | {error, term()}.
Replaces an event handler in event manager EventMgrRef in the same way as
swap_handler/3, but also supervises the connection between
NewHandler and the calling process.
For a description of the arguments and return values, see swap_handler/3.
Sends a synchronous event notification to event manager EventMgrRef. The event
manager calls Module:handle_event/2 for each installed event
handler to handle the event. This function will return ok after the event has
been handled by all event handlers.
Event is any term that is passed as one of the arguments to
Module:handle_event/2.
-spec wait_response(ReqId, WaitTime) -> Result when ReqId :: request_id(), WaitTime :: response_timeout(), Response :: {reply, Reply :: term()} | {error, {Reason :: term(), emgr_ref()}}, Result :: Response | timeout.
Wait for a response corresponding to the request identifier ReqId. The request
must have been made by send_request/3 to the gen_statem process. This
function must be called from the same process from which send_request/3 was
made.
WaitTime specifies how long to wait for a response. If no response is received
within the specified time, the function returns timeout and no cleanup is
done, and thus the function can be invoked repeatedly until a reply is returned.
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. If the event manager dies before or during the
request this function returns {error,{Reason, EventMgrRef}}.
The difference between receive_response/2 and
wait_response/2 is that
receive_response/2 abandons the request at timeout so
that a potential future response is ignored, while
wait_response/2 does not.
-spec wait_response(ReqIdCollection, WaitTime, Delete) -> Result when ReqIdCollection :: request_id_collection(), WaitTime :: response_timeout(), Delete :: boolean(), Response :: {reply, Reply :: term()} | {error, {Reason :: term(), emgr_ref()}}, Result :: {Response, Label :: term(), NewReqIdCollection :: request_id_collection()} | no_request | timeout.
Wait for a response corresponding to a request identifier saved in
ReqIdCollection. All request identifiers of ReqIdCollection must correspond
to requests that have been made using send_request/3 or send_request/5, and
all requests must have been made by the process calling this function.
The Label in the response equals the Label associated with the request
identifier that the response corresponds to. The Label of a request identifier
is associated when saving the request id in a request
identifier collection, or when sending the request using send_request/5.
Compared to wait_response/2, the returned result associated with a specific
request identifier or an exception associated with a specific request identifier
will be wrapped in a 3-tuple. The first element of this tuple equals the value
that would have been produced by wait_response/2, the
second element equals the Label associated with the specific request
identifier, and the third element NewReqIdCollection is a possibly modified
request identifier collection.
If ReqIdCollection is empty, no_request will be returned. If no response is
received before the WaitTime timeout has triggered, the atom timeout is
returned. It is valid to continue waiting for a response as many times as needed
up until a response has been received and completed by check_response(),
receive_response(), or wait_response().
The difference between receive_response/3 and
wait_response/3 is that
receive_response/3 abandons requests at timeout so
that potential future responses are ignored, while
wait_response/3 does not.
If Delete equals true, the association with Label will have been deleted
from ReqIdCollection in the resulting NewReqIdCollection. If Delete equals
false, NewReqIdCollection will equal ReqIdCollection. Note that deleting
an association is not for free and that a collection containing already handled
requests can still be used by subsequent calls to
wait_response/3, check_response/3, and
receive_response/3. However, without deleting handled associations, the above
calls will not be able to detect when there are no more outstanding requests to
handle, so you will have to keep track of this some other way than relying on a
no_request return. Note that if you pass a collection only containing
associations of already handled or abandoned requests to
wait_response/3, it will always block until a timeout
determined by WaitTime is triggered and then return no_reply.
Returns a list of all event handlers installed in event manager EventMgrRef.
For a description of Handler, see add_handler/3.