1gen_event(3) Erlang Module Definition gen_event(3)
2
6 gen_event - Generic event handling behavior.
7
9 This behavior module provides event handling functionality. It consists
10 of a generic event manager process with any number of event handlers
11 that are added and deleted dynamically.
12 An event manager implemented using this module has a standard set of
14 interface functions and includes functionality for tracing and error
15 reporting. It also fits into an OTP supervision tree. For more informa‐
16 tion, see OTP Design Principles.
17 Each event handler is implemented as a callback module exporting a pre‐
19 defined set of functions. The relationship between the behavior func‐
20 tions and the callback functions is as follows:
21 gen_event module Callback module
23 ---------------- ---------------
24 gen_event:start
25 gen_event:start_monitor
26 gen_event:start_link -----> -
27 gen_event:add_handler
29 gen_event:add_sup_handler -----> Module:init/1
30 gen_event:notify
32 gen_event:sync_notify -----> Module:handle_event/2
33 gen_event:send_request
35 gen_event:call -----> Module:handle_call/2
36 - -----> Module:handle_info/2
38 gen_event:delete_handler -----> Module:terminate/2
40 gen_event:swap_handler
42 gen_event:swap_sup_handler -----> Module1:terminate/2
43 Module2:init/1
44 gen_event:which_handlers -----> -
46 gen_event:stop -----> Module:terminate/2
48 - -----> Module:code_change/3
50 As each event handler is one callback module, an event manager has many
52 callback modules that are added and deleted dynamically. gen_event is
53 therefore more tolerant of callback module errors than the other behav‐
54 iors. If a callback function for an installed event handler fails with
55 Reason, or returns a bad value Term, the event manager does not fail.
56 It deletes the event handler by calling callback function Module:termi‐
57 nate/2, giving as argument {error,{'EXIT',Reason}} or {error,Term}, re‐
58 spectively. No other event handler is affected.
59 A gen_event process handles system messages as described in sys(3). The
61 sys module can be used for debugging an event manager.
62 Notice that an event manager does trap exit signals automatically.
64 The gen_event process can go into hibernation (see erlang:hibernate/3)
66 if a callback function in a handler module specifies hibernate in its
67 return value. This can be useful if the server is expected to be idle
68 for a long time. However, use this feature with care, as hibernation
69 implies at least two garbage collections (when hibernating and shortly
70 after waking up) and is not something you want to do between each event
71 handled by a busy event manager.
72 Notice that when multiple event handlers are invoked, it is sufficient
74 that one single event handler returns a hibernate request for the whole
75 event manager to go into hibernation.
76 Unless otherwise stated, all functions in this module fail if the spec‐
78 ified event manager does not exist or if bad arguments are specified.
79
81 handler() = atom() | {atom(), term()}
82 handler_args() = term()
84 add_handler_ret() = ok | term() | {'EXIT', term()}
86 del_handler_ret() = ok | term() | {'EXIT', term()}
88 request_id() = term()
90 A request handle, see send_request/3 for details.
92
94 add_handler(EventMgrRef, Handler, Args) -> Result
95 Types:
97 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
99 {via,Module,ViaName} | pid()
100 Name = Node = atom()
101 GlobalName = ViaName = term()
102 Handler = Module | {Module,Id}
103 Module = atom()
104 Id = term()
105 Args = term()
106 Result = ok | {'EXIT',Reason} | term()
107 Reason = term()
108 Adds a new event handler to event manager EventMgrRef. The event
110 manager calls Module:init/1 to initiate the event handler and
111 its internal state.
112 EventMgrRef can be any of the following:
114 * The pid
116 * Name, if the event manager is locally registered
118 * {Name,Node}, if the event manager is locally registered at
120 another node
121 * {global,GlobalName}, if the event manager is globally regis‐
123 tered
124 * {via,Module,ViaName}, if the event manager is registered
126 through an alternative process registry
127 Handler is the name of the callback module Module or a tuple
129 {Module,Id}, where Id is any term. The {Module,Id} representa‐
130 tion makes it possible to identify a specific event handler when
131 many event handlers use the same callback module.
132 Args is any term that is passed as the argument to Mod‐
134 ule:init/1.
135 If Module:init/1 returns a correct value indicating successful
137 completion, the event manager adds the event handler and this
138 function returns ok. If Module:init/1 fails with Reason or re‐
139 turns {error,Reason}, the event handler is ignored and this
140 function returns {'EXIT',Reason} or {error,Reason}, respec‐
141 tively.
142 add_sup_handler(EventMgrRef, Handler, Args) -> Result
144 Types:
146 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
148 {via,Module,ViaName} | pid()
149 Name = Node = atom()
150 GlobalName = ViaName = term()
151 Handler = Module | {Module,Id}
152 Module = atom()
153 Id = term()
154 Args = term()
155 Result = ok | {'EXIT',Reason} | term()
156 Reason = term()
157 Adds a new event handler in the same way as add_handler/3, but
159 also supervises the connection between the event handler and the
160 calling process.
161 * If the calling process later terminates with Reason, the
163 event manager deletes the event handler by calling Mod‐
164 ule:terminate/2 with {stop,Reason} as argument.
165 * If the event handler is deleted later, the event manager
167 sends a message {gen_event_EXIT,Handler,Reason} to the call‐
168 ing process. Reason is one of the following:
169 * normal, if the event handler has been removed because of a
171 call to delete_handler/3, or remove_handler has been re‐
172 turned by a callback function (see below).
173 * shutdown, if the event handler has been removed because
175 the event manager is terminating.
176 * {swapped,NewHandler,Pid}, if the process Pid has replaced
178 the event handler with another event handler NewHandler
179 using a call to swap_handler/3 or swap_sup_handler/3.
180 * A term, if the event handler is removed because of an er‐
182 ror. Which term depends on the error.
183 For a description of the arguments and return values, see
185 add_handler/3.
186 call(EventMgrRef, Handler, Request) -> Result
188 call(EventMgrRef, Handler, Request, Timeout) -> Result
189 Types:
191 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
193 {via,Module,ViaName} | pid()
194 Name = Node = atom()
195 GlobalName = ViaName = term()
196 Handler = Module | {Module,Id}
197 Module = atom()
198 Id = term()
199 Request = term()
200 Timeout = int()>0 | infinity
201 Result = Reply | {error,Error}
202 Reply = term()
203 Error = bad_module | {'EXIT',Reason} | term()
204 Reason = term()
205 Makes a synchronous call to event handler Handler installed in
207 event manager EventMgrRef by sending a request and waiting until
208 a reply arrives or a time-out occurs. The event manager calls
209 Module:handle_call/2 to handle the request.
210 For a description of EventMgrRef and Handler, see add_handler/3.
212 Request is any term that is passed as one of the arguments to
214 Module:handle_call/2.
215 Timeout is an integer greater than zero that specifies how many
217 milliseconds to wait for a reply, or the atom infinity to wait
218 indefinitely. Defaults to 5000. If no reply is received within
219 the specified time, the function call fails.
220 The return value Reply is defined in the return value of Mod‐
222 ule:handle_call/2. If the specified event handler is not in‐
223 stalled, the function returns {error,bad_module}. If the call‐
224 back function fails with Reason or returns an unexpected value
225 Term, this function returns {error,{'EXIT',Reason}} or {er‐
226 ror,Term}, respectively.
227 check_response(Msg, RequestId) -> Result
229 Types:
231 Msg = term()
233 RequestId = request_id()
234 Result = {reply, Reply} | no_reply | {error, Error}
235 Reply = Error = term()
236 This function is used to check if a previously received message,
238 for example by receive or handle_info/2, is a result of a re‐
239 quest made with send_request/3. If Msg is a reply to the handle
240 RequestId the result of the request is returned in Reply. Other‐
241 wise returns no_reply and no cleanup is done, and thus the func‐
242 tion shall be invoked repeatedly until a reply is returned.
243 If the specified event handler is not installed, the function
245 returns {error,bad_module}. If the callback function fails with
246 Reason or returns an unexpected value Term, this function re‐
247 turns {error,{'EXIT',Reason}} or {error,Term}, respectively. If
248 the event manager dies before or during the request this func‐
249 tion returns {error,{Reason, EventMgrRef}}.
250 delete_handler(EventMgrRef, Handler, Args) -> Result
252 Types:
254 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
256 {via,Module,ViaName} | pid()
257 Name = Node = atom()
258 GlobalName = ViaName = term()
259 Handler = Module | {Module,Id}
260 Module = atom()
261 Id = term()
262 Args = term()
263 Result = term() | {error,module_not_found} | {'EXIT',Reason}
264 Reason = term()
265 Deletes an event handler from event manager EventMgrRef. The
267 event manager calls Module:terminate/2 to terminate the event
268 handler.
269 For a description of EventMgrRef and Handler, see add_handler/3.
271 Args is any term that is passed as one of the arguments to Mod‐
273 ule:terminate/2.
274 The return value is the return value of Module:terminate/2. If
276 the specified event handler is not installed, the function re‐
277 turns {error,module_not_found}. If the callback function fails
278 with Reason, the function returns {'EXIT',Reason}.
279 notify(EventMgrRef, Event) -> ok
281 sync_notify(EventMgrRef, Event) -> ok
282 Types:
284 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
286 {via,Module,ViaName} | pid()
287 Name = Node = atom()
288 GlobalName = ViaName = term()
289 Event = term()
290 Sends an event notification to event manager EventMgrRef. The
292 event manager calls Module:handle_event/2 for each installed
293 event handler to handle the event.
294 notify/2 is asynchronous and returns immediately after the event
296 notification has been sent. sync_notify/2 is synchronous in the
297 sense that it returns ok after the event has been handled by all
298 event handlers.
299 For a description of EventMgrRef, see add_handler/3.
301 Event is any term that is passed as one of the arguments to Mod‐
303 ule:handle_event/2.
304 notify/1 does not fail even if the specified event manager does
306 not exist, unless it is specified as Name.
307 receive_response(RequestId, Timeout) -> Result
309 Types:
311 RequestId = request_id()
313 Reply = term()
314 Timeout = timeout()
315 Result = {reply, Reply} | timeout | {error, Error}
316 Reply = Error = term()
317 This function is used to receive for a reply of a request made
319 with send_request/3 to the event manager. This function must be
320 called from the same process from which send_request/3 was made.
321 Timeout is an integer greater then or equal to zero that speci‐
323 fies how many milliseconds to wait for an reply, or the atom in‐
324 finity to wait indefinitely. If no reply is received within the
325 specified time, the function returns timeout. Assuming that the
326 server executes on a node supporting aliases (introduced in OTP
327 24) no response will be received after a timeout. Otherwise, a
328 garbage response might be received at a later time.
329 The return value Reply is defined in the return value of Mod‐
331 ule:handle_call/3.
332 If the specified event handler is not installed, the function
334 returns {error,bad_module}. If the callback function fails with
335 Reason or returns an unexpected value Term, this function re‐
336 turns {error,{'EXIT',Reason}} or {error,Term}, respectively. If
337 the event manager dies before or during the request this func‐
338 tion returns {error,{Reason, EventMgrRef}}.
339 The difference between wait_response() and receive_response() is
341 that receive_response() abandons the request at timeout so that
342 a potential future response is ignored, while wait_response()
343 does not.
344 send_request(EventMgrRef, Handler, Request) -> RequestId
346 Types:
348 EventMgrRef = Name | {Name,Node} | {global,GlobalName}
350 | {via,Module,ViaName} | pid()
351 Node = atom()
352 GlobalName = ViaName = term()
353 Handler = Module | {Module,Id}
354 Module = atom()
355 Id = term()
356 Request = term()
357 RequestId = request_id()
358 Sends a request to event handler Handler installed in event man‐
360 ager EventMgrRef and returns a handle RequestId. The return
361 value RequestId shall later be used with receive_response/2,
362 wait_response/2, or check_response/2 in the same process to
363 fetch the actual result of the request.
364 The call gen_event:wait_response(gen_event:send_request(EventM‐
366 grRef,Handler,Request), Timeout) can be seen as equivalent to
367 gen_event:call(EventMgrRef,Handler,Request,Timeout), ignoring
368 the error handling.
369 The event manager calls Module:handle_call/2 to handle the re‐
371 quest.
372 Request is any term that is passed as one of the arguments to
374 Module:handle_call/3.
375 start() -> Result
377 start(EventMgrName | Options) -> Result
378 start(EventMgrName, Options) -> Result
379 Types:
381 EventMgrName = {local,Name} | {global,GlobalName} | {via,Mod‐
383 ule,ViaName}
384 Name = atom()
385 GlobalName = ViaName = term()
386 Options = [Option]
387 Option = {debug,Dbgs} | {timeout,Time} | {hibernate_af‐
388 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
389 Dbgs = [Dbg]
390 Dbg = trace | log | statistics | {log_to_file,FileName} |
391 {install,{Func,FuncState}}
392 SOpts = [term()]
393 Result = {ok,Pid} | {error,{already_started,Pid}}
394 Pid = pid()
395 Creates a stand-alone event manager process, that is, an event
397 manager that is not part of a supervision tree and thus has no
398 supervisor.
399 For a description of the arguments and return values, see
401 start_link/0,1.
402 start_link() -> Result
404 start_link(EventMgrName | Options) -> Result
405 start_link(EventMgrName, Options) -> Result
406 Types:
408 EventMgrName = {local,Name} | {global,GlobalName} | {via,Mod‐
410 ule,ViaName}
411 Name = atom()
412 GlobalName = ViaName = term()
413 Options = [Option]
414 Option = {debug,Dbgs} | {timeout,Time} | {hibernate_af‐
415 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
416 Dbgs = [Dbg]
417 Dbg = trace | log | statistics | {log_to_file,FileName} |
418 {install,{Func,FuncState}}
419 SOpts = [term()]
420 Result = {ok,Pid} | {error,{already_started,Pid}}
421 Pid = pid()
422 Creates an event manager process as part of a supervision tree.
424 The function is to be called, directly or indirectly, by the su‐
425 pervisor. For example, it ensures that the event manager is
426 linked to the supervisor.
427 * If EventMgrName={local,Name}, the event manager is regis‐
429 tered locally as Name using register/2.
430 * If EventMgrName={global,GlobalName}, the event manager is
432 registered globally as GlobalName using global:regis‐
433 ter_name/2. If no name is provided, the event manager is not
434 registered.
435 * If EventMgrName={via,Module,ViaName}, the event manager reg‐
437 isters with the registry represented by Module. The Module
438 callback is to export the functions register_name/2, unreg‐
439 ister_name/1, whereis_name/1, and send/2, which are to be‐
440 have as the corresponding functions in global. Thus,
441 {via,global,GlobalName} is a valid reference.
442 * If option {hibernate_after,HibernateAfterTimeout} is
444 present, the gen_event process awaits any message for Hiber‐
445 nateAfterTimeout milliseconds and if no message is received,
446 the process goes into hibernation automatically (by calling
447 proc_lib:hibernate/3).
448 If the event manager is successfully created, the function re‐
450 turns {ok,Pid}, where Pid is the pid of the event manager. If a
451 process with the specified EventMgrName exists already, the
452 function returns {error,{already_started,Pid}}, where Pid is the
453 pid of that process.
454 start_monitor() -> Result
456 start_monitor(EventMgrName | Options) -> Result
457 start_monitor(EventMgrName, Options) -> Result
458 Types:
460 EventMgrName = {local,Name} | {global,GlobalName} | {via,Mod‐
462 ule,ViaName}
463 Name = atom()
464 GlobalName = ViaName = term()
465 Options = [Option]
466 Option = {debug,Dbgs} | {timeout,Time} | {hibernate_af‐
467 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
468 Dbgs = [Dbg]
469 Dbg = trace | log | statistics | {log_to_file,FileName} |
470 {install,{Func,FuncState}}
471 SOpts = [term()]
472 Result = {ok,{Pid,Mon}} | {error,{already_started,Pid}}
473 Pid = pid()
474 Creates a stand-alone event manager process, that is, an event
476 manager that is not part of a supervision tree (and thus has no
477 supervisor) and atomically sets up a monitor to the newly cre‐
478 ated process.
479 For a description of the arguments and return values, see
481 start_link/0,1. Note that the return value on successful start
482 differs from start_link/3,4. start_monitor/3,4 will return
483 {ok,{Pid,Mon}} where Pid is the process identifier of the
484 process, and Mon is a reference to the monitor set up to monitor
485 the process. If the start is not successful, the caller will be
486 blocked until the DOWN message has been received and removed
487 from the message queue.
488 stop(EventMgrRef) -> ok
490 stop(EventMgrRef, Reason, Timeout) -> ok
491 Types:
493 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
495 {via,Module,ViaName} | pid()
496 Name = Node = atom()
497 GlobalName = ViaName = term()
498 Reason = term()
499 Timeout = int()>0 | infinity
500 Orders event manager EventMgrRef to exit with the specifies Rea‐
502 son and waits for it to terminate. Before terminating, gen_event
503 calls Module:terminate(stop,...) for each installed event han‐
504 dler.
505 The function returns ok if the event manager terminates with the
507 expected reason. Any other reason than normal, shutdown, or
508 {shutdown,Term} causes an error report to be issued using log‐
509 ger(3). The default Reason is normal.
510 Timeout is an integer greater than zero that specifies how many
512 milliseconds to wait for the event manager to terminate, or the
513 atom infinity to wait indefinitely. Defaults to infinity. If the
514 event manager has not terminated within the specified time, a
515 timeout exception is raised.
516 If the process does not exist, a noproc exception is raised.
518 For a description of EventMgrRef, see add_handler/3.
520 swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result
522 Types:
524 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
526 {via,Module,ViaName} | pid()
527 Name = Node = atom()
528 GlobalName = ViaName = term()
529 Handler1 = Handler2 = Module | {Module,Id}
530 Module = atom()
531 Id = term()
532 Args1 = Args2 = term()
533 Result = ok | {error,Error}
534 Error = {'EXIT',Reason} | term()
535 Reason = term()
536 Replaces an old event handler with a new event handler in event
538 manager EventMgrRef.
539 For a description of the arguments, see add_handler/3.
541 First the old event handler Handler1 is deleted. The event man‐
543 ager calls Module1:terminate(Args1, ...), where Module1 is the
544 callback module of Handler1, and collects the return value.
545 Then the new event handler Handler2 is added and initiated by
547 calling Module2:init({Args2,Term}), where Module2 is the call‐
548 back module of Handler2 and Term is the return value of Mod‐
549 ule1:terminate/2. This makes it possible to transfer information
550 from Handler1 to Handler2.
551 The new handler is added even if the the specified old event
553 handler is not installed, in which case Term=error, or if Mod‐
554 ule1:terminate/2 fails with Reason, in which case
555 Term={'EXIT',Reason}. The old handler is deleted even if Mod‐
556 ule2:init/1 fails.
557 If there was a supervised connection between Handler1 and a
559 process Pid, there is a supervised connection between Handler2
560 and Pid instead.
561 If Module2:init/1 returns a correct value, this function returns
563 ok. If Module2:init/1 fails with Reason or returns an unexpected
564 value Term, this function returns {error,{'EXIT',Reason}} or
565 {error,Term}, respectively.
566 swap_sup_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) ->
568 Result
569 Types:
571 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
573 {via,Module,ViaName} | pid()
574 Name = Node = atom()
575 GlobalName = ViaName = term()
576 Handler1 = Handler 2 = Module | {Module,Id}
577 Module = atom()
578 Id = term()
579 Args1 = Args2 = term()
580 Result = ok | {error,Error}
581 Error = {'EXIT',Reason} | term()
582 Reason = term()
583 Replaces an event handler in event manager EventMgrRef in the
585 same way as swap_handler/3, but also supervises the connection
586 between Handler2 and the calling process.
587 For a description of the arguments and return values, see
589 swap_handler/3.
590 wait_response(RequestId, Timeout) -> Result
592 Types:
594 RequestId = request_id()
596 Reply = term()
597 Timeout = timeout()
598 Result = {reply, Reply} | timeout | {error, Error}
599 Reply = Error = term()
600 This function is used to wait for a reply of a request made with
602 send_request/3 to the event manager. This function must be
603 called from the same process from which send_request/3 was made.
604 Timeout is an integer greater then or equal to zero that speci‐
606 fies how many milliseconds to wait for an reply, or the atom in‐
607 finity to wait indefinitely. If no reply is received within the
608 specified time, the function returns timeout and no cleanup is
609 done, and thus the function must be invoked repeatedly until a
610 reply is returned.
611 The return value Reply is defined in the return value of Mod‐
613 ule:handle_call/3.
614 If the specified event handler is not installed, the function
616 returns {error,bad_module}. If the callback function fails with
617 Reason or returns an unexpected value Term, this function re‐
618 turns {error,{'EXIT',Reason}} or {error,Term}, respectively. If
619 the event manager dies before or during the request this func‐
620 tion returns {error,{Reason, EventMgrRef}}.
621 The difference between receive_response() and wait_response() is
623 that receive_response() abandons the request at timeout so that
624 a potential future response is ignored, while wait_response()
625 does not.
626 which_handlers(EventMgrRef) -> [Handler]
628 Types:
630 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
632 {via,Module,ViaName} | pid()
633 Name = Node = atom()
634 GlobalName = ViaName = term()
635 Handler = Module | {Module,Id}
636 Module = atom()
637 Id = term()
638 Returns a list of all event handlers installed in event manager
640 EventMgrRef.
641 For a description of EventMgrRef and Handler, see add_handler/3.
643
645 The following functions are to be exported from a gen_event callback
646 module.
647
649 Module:code_change(OldVsn, State, Extra) -> {ok, NewState}
650 Types:
652 OldVsn = Vsn | {down, Vsn}
654 Vsn = term()
655 State = NewState = term()
656 Extra = term()
657 Note:
659 This callback is optional, so callback modules need not export
660 it. If a release upgrade/downgrade with Change={advanced,Extra}
661 specified in the .appup file is made when code_change/3 isn't
662 implemented the event handler will crash with an undef error
663 reason.
664 This function is called for an installed event handler that is
667 to update its internal state during a release upgrade/downgrade,
668 that is, when the instruction {update,Module,Change,...}, where
669 Change={advanced,Extra}, is specified in the .appup file. For
670 more information, see OTP Design Principles.
671 For an upgrade, OldVsn is Vsn, and for a downgrade, OldVsn is
673 {down,Vsn}. Vsn is defined by the vsn attribute(s) of the old
674 version of the callback module Module. If no such attribute is
675 defined, the version is the checksum of the Beam file.
676 State is the internal state of the event handler.
678 Extra is passed "as is" from the {advanced,Extra} part of the
680 update instruction.
681 The function is to return the updated internal state.
683 Module:format_status(Opt, [PDict, State]) -> Status
685 Types:
687 Opt = normal | terminate
689 PDict = [{Key, Value}]
690 State = term()
691 Status = term()
692 Note:
694 This callback is optional, so event handler modules need not ex‐
695 port it. If a handler does not export this function, the
696 gen_event module uses the handler state directly for the pur‐
697 poses described below.
698 This function is called by a gen_event process in the following
701 situations:
702 * One of sys:get_status/1,2 is invoked to get the gen_event
704 status. Opt is set to the atom normal for this case.
705 * The event handler terminates abnormally and gen_event logs
707 an error. Opt is set to the atom terminate for this case.
708 This function is useful for changing the form and appearance of
710 the event handler state for these cases. An event handler call‐
711 back module wishing to change the the sys:get_status/1,2 return
712 value as well as how its state appears in termination error
713 logs, exports an instance of format_status/2 that returns a term
714 describing the current state of the event handler.
715 PDict is the current value of the process dictionary of
717 gen_event.
718 State is the internal state of the event handler.
720 The function is to return Status, a term that change the details
722 of the current state of the event handler. Any term is allowed
723 for Status. The gen_event module uses Status as follows:
724 * When sys:get_status/1,2 is called, gen_event ensures that
726 its return value contains Status in place of the state term
727 of the event handler.
728 * When an event handler terminates abnormally, gen_event logs
730 Status in place of the state term of the event handler.
731 One use for this function is to return compact alternative state
733 representations to avoid that large state terms are printed in
734 log files.
735 Module:handle_call(Request, State) -> Result
737 Types:
739 Request = term()
741 State = term()
742 Result = {ok,Reply,NewState} | {ok,Reply,NewState,hibernate}
743 | {swap_handler,Reply,Args1,NewState,Handler2,Args2}
744 | {remove_handler, Reply}
745 Reply = term()
746 NewState = term()
747 Args1 = Args2 = term()
748 Handler2 = Module2 | {Module2,Id}
749 Module2 = atom()
750 Id = term()
751 Whenever an event manager receives a request sent using
753 call/3,4, this function is called for the specified event han‐
754 dler to handle the request.
755 Request is the Request argument of call/3,4.
757 State is the internal state of the event handler.
759 The return values are the same as for Module:handle_event/2 ex‐
761 cept that they also contain a term Reply, which is the reply to
762 the client as the return value of call/3,4.
763 Module:handle_event(Event, State) -> Result
765 Types:
767 Event = term()
769 State = term()
770 Result = {ok,NewState} | {ok,NewState,hibernate}
771 | {swap_handler,Args1,NewState,Handler2,Args2} | remove_han‐
772 dler
773 NewState = term()
774 Args1 = Args2 = term()
775 Handler2 = Module2 | {Module2,Id}
776 Module2 = atom()
777 Id = term()
778 Whenever an event manager receives an event sent using notify/2
780 or sync_notify/2, this function is called for each installed
781 event handler to handle the event.
782 Event is the Event argument of notify/2/sync_notify/2.
784 State is the internal state of the event handler.
786 * If {ok,NewState} or {ok,NewState,hibernate} is returned, the
788 event handler remains in the event manager with the possible
789 updated internal state NewState.
790 * If {ok,NewState,hibernate} is returned, the event manager
792 also goes into hibernation (by calling proc_lib:hiber‐
793 nate/3), waiting for the next event to occur. It is suffi‐
794 cient that one of the event handlers return {ok,NewState,hi‐
795 bernate} for the whole event manager process to hibernate.
796 * If {swap_handler,Args1,NewState,Handler2,Args2} is returned,
798 the event handler is replaced by Handler2 by first calling
799 Module:terminate(Args1,NewState) and then Mod‐
800 ule2:init({Args2,Term}), where Term is the return value of
801 Module:terminate/2. For more information, see swap_han‐
802 dler/3.
803 * If remove_handler is returned, the event handler is deleted
805 by calling Module:terminate(remove_handler,State).
806 Module:handle_info(Info, State) -> Result
808 Types:
810 Info = term()
812 State = term()
813 Result = {ok,NewState} | {ok,NewState,hibernate}
814 | {swap_handler,Args1,NewState,Handler2,Args2} | remove_han‐
815 dler
816 NewState = term()
817 Args1 = Args2 = term()
818 Handler2 = Module2 | {Module2,Id}
819 Module2 = atom()
820 Id = term()
821 Note:
823 This callback is optional, so callback modules need not export
824 it. The gen_event module provides a default implementation of
825 this function that logs about the unexpected Info message, drops
826 it and returns {ok, State}.
827 This function is called for each installed event handler when an
830 event manager receives any other message than an event or a syn‐
831 chronous request (or a system message).
832 Info is the received message.
834 For a description of State and possible return values, see Mod‐
836 ule:handle_event/2.
837 Module:init(InitArgs) -> {ok,State} | {ok,State,hibernate} | {er‐
839 ror,Reason}
840 Types:
842 InitArgs = Args | {Args,Term}
844 Args = Term = term()
845 State = term()
846 Reason = term()
847 Whenever a new event handler is added to an event manager, this
849 function is called to initialize the event handler.
850 If the event handler is added because of a call to add_handler/3
852 or add_sup_handler/3, InitArgs is the Args argument of these
853 functions.
854 If the event handler replaces another event handler because of a
856 call to swap_handler/3 or swap_sup_handler/3, or because of a
857 swap return tuple from one of the other callback functions, Ini‐
858 tArgs is a tuple {Args,Term}, where Args is the argument pro‐
859 vided in the function call/return tuple and Term is the result
860 of terminating the old event handler, see swap_handler/3.
861 If successful, the function returns {ok,State} or {ok,State,hi‐
863 bernate}, where State is the initial internal state of the event
864 handler.
865 If {ok,State,hibernate} is returned, the event manager goes into
867 hibernation (by calling proc_lib:hibernate/3), waiting for the
868 next event to occur.
869 Module:terminate(Arg, State) -> term()
871 Types:
873 Arg = Args | {stop,Reason} | stop | remove_handler
875 | {error,{'EXIT',Reason}} | {error,Term}
876 Args = Reason = Term = term()
877 Note:
879 This callback is optional, so callback modules need not export
880 it. The gen_event module provides a default implementation with‐
881 out cleanup.
882 Whenever an event handler is deleted from an event manager, this
885 function is called. It is to be the opposite of Module:init/1
886 and do any necessary cleaning up.
887 If the event handler is deleted because of a call to delete_han‐
889 dler/3, swap_handler/3, or swap_sup_handler/3, Arg is the Args
890 argument of this function call.
891 Arg={stop,Reason} if the event handler has a supervised connec‐
893 tion to a process that has terminated with reason Reason.
894 Arg=stop if the event handler is deleted because the event man‐
896 ager is terminating.
897 The event manager terminates if it is part of a supervision tree
899 and it is ordered by its supervisor to terminate. Even if it is
900 not part of a supervision tree, it terminates if it receives an
901 'EXIT' message from its parent.
902 Arg=remove_handler if the event handler is deleted because an‐
904 other callback function has returned remove_handler or {re‐
905 move_handler,Reply}.
906 Arg={error,Term} if the event handler is deleted because a call‐
908 back function returned an unexpected value Term, or Arg={er‐
909 ror,{'EXIT',Reason}} if a callback function failed.
910 State is the internal state of the event handler.
912 The function can return any term. If the event handler is
914 deleted because of a call to gen_event:delete_handler/3, the re‐
915 turn value of that function becomes the return value of this
916 function. If the event handler is to be replaced with another
917 event handler because of a swap, the return value is passed to
918 the init function of the new event handler. Otherwise the return
919 value is ignored.
920
922 supervisor(3), sys(3)
923Ericsson AB stdlib 3.17.2 gen_event(3)