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 send_request(EventMgrRef, Handler, Request) -> RequestId
309 Types:
311 EventMgrRef = Name | {Name,Node} | {global,GlobalName}
313 | {via,Module,ViaName} | pid()
314 Node = atom()
315 GlobalName = ViaName = term()
316 Handler = Module | {Module,Id}
317 Module = atom()
318 Id = term()
319 Request = term()
320 RequestId = request_id()
321 Sends a request to event handler Handler installed in event man‐
323 ager EventMgrRef and returns a handle RequestId. The return
324 value RequestId shall later be used with wait_response/2 or
325 check_response/2 in the same process to fetch the actual result
326 of the request.
327 The call gen_event:wait_response(gen_event:send_request(EventM‐
329 grRef,Handler,Request), Timeout) can be seen as equivalent to
330 gen_event:call(EventMgrRef,Handler,Request,Timeout), ignoring
331 the error handling.
332 The event manager calls Module:handle_call/2 to handle the re‐
334 quest.
335 Request is any term that is passed as one of the arguments to
337 Module:handle_call/3.
338 start() -> Result
340 start(EventMgrName | Options) -> Result
341 start(EventMgrName, Options) -> Result
342 Types:
344 EventMgrName = {local,Name} | {global,GlobalName} | {via,Mod‐
346 ule,ViaName}
347 Name = atom()
348 GlobalName = ViaName = term()
349 Options = [Option]
350 Option = {debug,Dbgs} | {timeout,Time} | {hibernate_af‐
351 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
352 Dbgs = [Dbg]
353 Dbg = trace | log | statistics | {log_to_file,FileName} |
354 {install,{Func,FuncState}}
355 SOpts = [term()]
356 Result = {ok,Pid} | {error,{already_started,Pid}}
357 Pid = pid()
358 Creates a stand-alone event manager process, that is, an event
360 manager that is not part of a supervision tree and thus has no
361 supervisor.
362 For a description of the arguments and return values, see
364 start_link/0,1.
365 start_link() -> Result
367 start_link(EventMgrName | Options) -> Result
368 start_link(EventMgrName, Options) -> Result
369 Types:
371 EventMgrName = {local,Name} | {global,GlobalName} | {via,Mod‐
373 ule,ViaName}
374 Name = atom()
375 GlobalName = ViaName = term()
376 Options = [Option]
377 Option = {debug,Dbgs} | {timeout,Time} | {hibernate_af‐
378 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
379 Dbgs = [Dbg]
380 Dbg = trace | log | statistics | {log_to_file,FileName} |
381 {install,{Func,FuncState}}
382 SOpts = [term()]
383 Result = {ok,Pid} | {error,{already_started,Pid}}
384 Pid = pid()
385 Creates an event manager process as part of a supervision tree.
387 The function is to be called, directly or indirectly, by the su‐
388 pervisor. For example, it ensures that the event manager is
389 linked to the supervisor.
390 * If EventMgrName={local,Name}, the event manager is regis‐
392 tered locally as Name using register/2.
393 * If EventMgrName={global,GlobalName}, the event manager is
395 registered globally as GlobalName using global:regis‐
396 ter_name/2. If no name is provided, the event manager is not
397 registered.
398 * If EventMgrName={via,Module,ViaName}, the event manager reg‐
400 isters with the registry represented by Module. The Module
401 callback is to export the functions register_name/2, unreg‐
402 ister_name/1, whereis_name/1, and send/2, which are to be‐
403 have as the corresponding functions in global. Thus,
404 {via,global,GlobalName} is a valid reference.
405 * If option {hibernate_after,HibernateAfterTimeout} is
407 present, the gen_event process awaits any message for Hiber‐
408 nateAfterTimeout milliseconds and if no message is received,
409 the process goes into hibernation automatically (by calling
410 proc_lib:hibernate/3).
411 If the event manager is successfully created, the function re‐
413 turns {ok,Pid}, where Pid is the pid of the event manager. If a
414 process with the specified EventMgrName exists already, the
415 function returns {error,{already_started,Pid}}, where Pid is the
416 pid of that process.
417 start_monitor() -> Result
419 start_monitor(EventMgrName | Options) -> Result
420 start_monitor(EventMgrName, Options) -> Result
421 Types:
423 EventMgrName = {local,Name} | {global,GlobalName} | {via,Mod‐
425 ule,ViaName}
426 Name = atom()
427 GlobalName = ViaName = term()
428 Options = [Option]
429 Option = {debug,Dbgs} | {timeout,Time} | {hibernate_af‐
430 ter,HibernateAfterTimeout} | {spawn_opt,SOpts}
431 Dbgs = [Dbg]
432 Dbg = trace | log | statistics | {log_to_file,FileName} |
433 {install,{Func,FuncState}}
434 SOpts = [term()]
435 Result = {ok,{Pid,Mon}} | {error,{already_started,Pid}}
436 Pid = pid()
437 Creates a stand-alone event manager process, that is, an event
439 manager that is not part of a supervision tree (and thus has no
440 supervisor) and atomically sets up a monitor to the newly cre‐
441 ated process.
442 For a description of the arguments and return values, see
444 start_link/0,1. Note that the return value on successful start
445 differs from start_link/3,4. start_monitor/3,4 will return
446 {ok,{Pid,Mon}} where Pid is the process identifier of the
447 process, and Mon is a reference to the monitor set up to monitor
448 the process. If the start is not successful, the caller will be
449 blocked until the DOWN message has been received and removed
450 from the message queue.
451 stop(EventMgrRef) -> ok
453 stop(EventMgrRef, Reason, Timeout) -> ok
454 Types:
456 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
458 {via,Module,ViaName} | pid()
459 Name = Node = atom()
460 GlobalName = ViaName = term()
461 Reason = term()
462 Timeout = int()>0 | infinity
463 Orders event manager EventMgrRef to exit with the specifies Rea‐
465 son and waits for it to terminate. Before terminating, gen_event
466 calls Module:terminate(stop,...) for each installed event han‐
467 dler.
468 The function returns ok if the event manager terminates with the
470 expected reason. Any other reason than normal, shutdown, or
471 {shutdown,Term} causes an error report to be issued using log‐
472 ger(3). The default Reason is normal.
473 Timeout is an integer greater than zero that specifies how many
475 milliseconds to wait for the event manager to terminate, or the
476 atom infinity to wait indefinitely. Defaults to infinity. If the
477 event manager has not terminated within the specified time, a
478 timeout exception is raised.
479 If the process does not exist, a noproc exception is raised.
481 For a description of EventMgrRef, see add_handler/3.
483 swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result
485 Types:
487 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
489 {via,Module,ViaName} | pid()
490 Name = Node = atom()
491 GlobalName = ViaName = term()
492 Handler1 = Handler2 = Module | {Module,Id}
493 Module = atom()
494 Id = term()
495 Args1 = Args2 = term()
496 Result = ok | {error,Error}
497 Error = {'EXIT',Reason} | term()
498 Reason = term()
499 Replaces an old event handler with a new event handler in event
501 manager EventMgrRef.
502 For a description of the arguments, see add_handler/3.
504 First the old event handler Handler1 is deleted. The event man‐
506 ager calls Module1:terminate(Args1, ...), where Module1 is the
507 callback module of Handler1, and collects the return value.
508 Then the new event handler Handler2 is added and initiated by
510 calling Module2:init({Args2,Term}), where Module2 is the call‐
511 back module of Handler2 and Term is the return value of Mod‐
512 ule1:terminate/2. This makes it possible to transfer information
513 from Handler1 to Handler2.
514 The new handler is added even if the the specified old event
516 handler is not installed, in which case Term=error, or if Mod‐
517 ule1:terminate/2 fails with Reason, in which case
518 Term={'EXIT',Reason}. The old handler is deleted even if Mod‐
519 ule2:init/1 fails.
520 If there was a supervised connection between Handler1 and a
522 process Pid, there is a supervised connection between Handler2
523 and Pid instead.
524 If Module2:init/1 returns a correct value, this function returns
526 ok. If Module2:init/1 fails with Reason or returns an unexpected
527 value Term, this function returns {error,{'EXIT',Reason}} or
528 {error,Term}, respectively.
529 swap_sup_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) ->
531 Result
532 Types:
534 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
536 {via,Module,ViaName} | pid()
537 Name = Node = atom()
538 GlobalName = ViaName = term()
539 Handler1 = Handler 2 = Module | {Module,Id}
540 Module = atom()
541 Id = term()
542 Args1 = Args2 = term()
543 Result = ok | {error,Error}
544 Error = {'EXIT',Reason} | term()
545 Reason = term()
546 Replaces an event handler in event manager EventMgrRef in the
548 same way as swap_handler/3, but also supervises the connection
549 between Handler2 and the calling process.
550 For a description of the arguments and return values, see
552 swap_handler/3.
553 wait_response(RequestId, Timeout) -> Result
555 Types:
557 RequestId = request_id()
559 Reply = term()
560 Timeout = timeout()
561 Result = {reply, Reply} | timeout | {error, Error}
562 Reply = Error = term()
563 This function is used to wait for a reply of a request made with
565 send_request/3 from the event manager. This function must be
566 called from the same process from which send_request/3 was made.
567 Timeout is an integer greater then or equal to zero that speci‐
569 fies how many milliseconds to wait for an reply, or the atom in‐
570 finity to wait indefinitely. If no reply is received within the
571 specified time, the function returns timeout and no cleanup is
572 done, and thus the function must be invoked repeatedly until a
573 reply is returned.
574 The return value Reply is defined in the return value of Mod‐
576 ule:handle_call/3.
577 If the specified event handler is not installed, the function
579 returns {error,bad_module}. If the callback function fails with
580 Reason or returns an unexpected value Term, this function re‐
581 turns {error,{'EXIT',Reason}} or {error,Term}, respectively. If
582 the event manager dies before or during the request this func‐
583 tion returns {error,{Reason, EventMgrRef}}.
584 which_handlers(EventMgrRef) -> [Handler]
586 Types:
588 EventMgrRef = Name | {Name,Node} | {global,GlobalName} |
590 {via,Module,ViaName} | pid()
591 Name = Node = atom()
592 GlobalName = ViaName = term()
593 Handler = Module | {Module,Id}
594 Module = atom()
595 Id = term()
596 Returns a list of all event handlers installed in event manager
598 EventMgrRef.
599 For a description of EventMgrRef and Handler, see add_handler/3.
601
603 The following functions are to be exported from a gen_event callback
604 module.
605
607 Module:code_change(OldVsn, State, Extra) -> {ok, NewState}
608 Types:
610 OldVsn = Vsn | {down, Vsn}
612 Vsn = term()
613 State = NewState = term()
614 Extra = term()
615 Note:
617 This callback is optional, so callback modules need not export
618 it. If a release upgrade/downgrade with Change={advanced,Extra}
619 specified in the .appup file is made when code_change/3 isn't
620 implemented the event handler will crash with an undef error
621 reason.
622 This function is called for an installed event handler that is
625 to update its internal state during a release upgrade/downgrade,
626 that is, when the instruction {update,Module,Change,...}, where
627 Change={advanced,Extra}, is specified in the .appup file. For
628 more information, see OTP Design Principles.
629 For an upgrade, OldVsn is Vsn, and for a downgrade, OldVsn is
631 {down,Vsn}. Vsn is defined by the vsn attribute(s) of the old
632 version of the callback module Module. If no such attribute is
633 defined, the version is the checksum of the Beam file.
634 State is the internal state of the event handler.
636 Extra is passed "as is" from the {advanced,Extra} part of the
638 update instruction.
639 The function is to return the updated internal state.
641 Module:format_status(Opt, [PDict, State]) -> Status
643 Types:
645 Opt = normal | terminate
647 PDict = [{Key, Value}]
648 State = term()
649 Status = term()
650 Note:
652 This callback is optional, so event handler modules need not ex‐
653 port it. If a handler does not export this function, the
654 gen_event module uses the handler state directly for the pur‐
655 poses described below.
656 This function is called by a gen_event process in the following
659 situations:
660 * One of sys:get_status/1,2 is invoked to get the gen_event
662 status. Opt is set to the atom normal for this case.
663 * The event handler terminates abnormally and gen_event logs
665 an error. Opt is set to the atom terminate for this case.
666 This function is useful for changing the form and appearance of
668 the event handler state for these cases. An event handler call‐
669 back module wishing to change the the sys:get_status/1,2 return
670 value as well as how its state appears in termination error
671 logs, exports an instance of format_status/2 that returns a term
672 describing the current state of the event handler.
673 PDict is the current value of the process dictionary of
675 gen_event.
676 State is the internal state of the event handler.
678 The function is to return Status, a term that change the details
680 of the current state of the event handler. Any term is allowed
681 for Status. The gen_event module uses Status as follows:
682 * When sys:get_status/1,2 is called, gen_event ensures that
684 its return value contains Status in place of the state term
685 of the event handler.
686 * When an event handler terminates abnormally, gen_event logs
688 Status in place of the state term of the event handler.
689 One use for this function is to return compact alternative state
691 representations to avoid that large state terms are printed in
692 log files.
693 Module:handle_call(Request, State) -> Result
695 Types:
697 Request = term()
699 State = term()
700 Result = {ok,Reply,NewState} | {ok,Reply,NewState,hibernate}
701 | {swap_handler,Reply,Args1,NewState,Handler2,Args2}
702 | {remove_handler, Reply}
703 Reply = term()
704 NewState = term()
705 Args1 = Args2 = term()
706 Handler2 = Module2 | {Module2,Id}
707 Module2 = atom()
708 Id = term()
709 Whenever an event manager receives a request sent using
711 call/3,4, this function is called for the specified event han‐
712 dler to handle the request.
713 Request is the Request argument of call/3,4.
715 State is the internal state of the event handler.
717 The return values are the same as for Module:handle_event/2 ex‐
719 cept that they also contain a term Reply, which is the reply to
720 the client as the return value of call/3,4.
721 Module:handle_event(Event, State) -> Result
723 Types:
725 Event = term()
727 State = term()
728 Result = {ok,NewState} | {ok,NewState,hibernate}
729 | {swap_handler,Args1,NewState,Handler2,Args2} | remove_han‐
730 dler
731 NewState = term()
732 Args1 = Args2 = term()
733 Handler2 = Module2 | {Module2,Id}
734 Module2 = atom()
735 Id = term()
736 Whenever an event manager receives an event sent using notify/2
738 or sync_notify/2, this function is called for each installed
739 event handler to handle the event.
740 Event is the Event argument of notify/2/sync_notify/2.
742 State is the internal state of the event handler.
744 * If {ok,NewState} or {ok,NewState,hibernate} is returned, the
746 event handler remains in the event manager with the possible
747 updated internal state NewState.
748 * If {ok,NewState,hibernate} is returned, the event manager
750 also goes into hibernation (by calling proc_lib:hiber‐
751 nate/3), waiting for the next event to occur. It is suffi‐
752 cient that one of the event handlers return {ok,NewState,hi‐
753 bernate} for the whole event manager process to hibernate.
754 * If {swap_handler,Args1,NewState,Handler2,Args2} is returned,
756 the event handler is replaced by Handler2 by first calling
757 Module:terminate(Args1,NewState) and then Mod‐
758 ule2:init({Args2,Term}), where Term is the return value of
759 Module:terminate/2. For more information, see swap_han‐
760 dler/3.
761 * If remove_handler is returned, the event handler is deleted
763 by calling Module:terminate(remove_handler,State).
764 Module:handle_info(Info, State) -> Result
766 Types:
768 Info = term()
770 State = term()
771 Result = {ok,NewState} | {ok,NewState,hibernate}
772 | {swap_handler,Args1,NewState,Handler2,Args2} | remove_han‐
773 dler
774 NewState = term()
775 Args1 = Args2 = term()
776 Handler2 = Module2 | {Module2,Id}
777 Module2 = atom()
778 Id = term()
779 Note:
781 This callback is optional, so callback modules need not export
782 it. The gen_event module provides a default implementation of
783 this function that logs about the unexpected Info message, drops
784 it and returns {ok, State}.
785 This function is called for each installed event handler when an
788 event manager receives any other message than an event or a syn‐
789 chronous request (or a system message).
790 Info is the received message.
792 For a description of State and possible return values, see Mod‐
794 ule:handle_event/2.
795 Module:init(InitArgs) -> {ok,State} | {ok,State,hibernate} | {er‐
797 ror,Reason}
798 Types:
800 InitArgs = Args | {Args,Term}
802 Args = Term = term()
803 State = term()
804 Reason = term()
805 Whenever a new event handler is added to an event manager, this
807 function is called to initialize the event handler.
808 If the event handler is added because of a call to add_handler/3
810 or add_sup_handler/3, InitArgs is the Args argument of these
811 functions.
812 If the event handler replaces another event handler because of a
814 call to swap_handler/3 or swap_sup_handler/3, or because of a
815 swap return tuple from one of the other callback functions, Ini‐
816 tArgs is a tuple {Args,Term}, where Args is the argument pro‐
817 vided in the function call/return tuple and Term is the result
818 of terminating the old event handler, see swap_handler/3.
819 If successful, the function returns {ok,State} or {ok,State,hi‐
821 bernate}, where State is the initial internal state of the event
822 handler.
823 If {ok,State,hibernate} is returned, the event manager goes into
825 hibernation (by calling proc_lib:hibernate/3), waiting for the
826 next event to occur.
827 Module:terminate(Arg, State) -> term()
829 Types:
831 Arg = Args | {stop,Reason} | stop | remove_handler
833 | {error,{'EXIT',Reason}} | {error,Term}
834 Args = Reason = Term = term()
835 Note:
837 This callback is optional, so callback modules need not export
838 it. The gen_event module provides a default implementation with‐
839 out cleanup.
840 Whenever an event handler is deleted from an event manager, this
843 function is called. It is to be the opposite of Module:init/1
844 and do any necessary cleaning up.
845 If the event handler is deleted because of a call to delete_han‐
847 dler/3, swap_handler/3, or swap_sup_handler/3, Arg is the Args
848 argument of this function call.
849 Arg={stop,Reason} if the event handler has a supervised connec‐
851 tion to a process that has terminated with reason Reason.
852 Arg=stop if the event handler is deleted because the event man‐
854 ager is terminating.
855 The event manager terminates if it is part of a supervision tree
857 and it is ordered by its supervisor to terminate. Even if it is
858 not part of a supervision tree, it terminates if it receives an
859 'EXIT' message from its parent.
860 Arg=remove_handler if the event handler is deleted because an‐
862 other callback function has returned remove_handler or {re‐
863 move_handler,Reply}.
864 Arg={error,Term} if the event handler is deleted because a call‐
866 back function returned an unexpected value Term, or Arg={er‐
867 ror,{'EXIT',Reason}} if a callback function failed.
868 State is the internal state of the event handler.
870 The function can return any term. If the event handler is
872 deleted because of a call to gen_event:delete_handler/3, the re‐
873 turn value of that function becomes the return value of this
874 function. If the event handler is to be replaced with another
875 event handler because of a swap, the return value is passed to
876 the init function of the new event handler. Otherwise the return
877 value is ignored.
878
880 supervisor(3), sys(3)
881Ericsson AB stdlib 3.14.2.1 gen_event(3)