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},
58 respectively. 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
139 returns {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
172 returned 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
182 error. 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
223 installed, 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
226 {error,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
239 request made with send_request/3. If Msg is a reply to the han‐
240 dle RequestId the result of the request is returned in Reply.
241 Otherwise returns no_reply and no cleanup is done, and thus the
242 function 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
247 returns {error,{'EXIT',Reason}} or {error,Term}, respectively.
248 If the event manager dies before or during the request this
249 function 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
277 returns {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
334 request.
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} | {hiber‐
351 nate_after,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} | {hiber‐
378 nate_after,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
388 supervisor. 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
403 behave 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
413 returns {ok,Pid}, where Pid is the pid of the event manager. If
414 a 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} | {hiber‐
430 nate_after,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
570 infinity to wait indefinitely. If no reply is received within
571 the specified time, the function returns timeout and no cleanup
572 is done, and thus the function must be invoked repeatedly until
573 a 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
581 returns {error,{'EXIT',Reason}} or {error,Term}, respectively.
582 If the event manager dies before or during the request this
583 function 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
653 export 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
719 except that they also contain a term Reply, which is the reply
720 to 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,New‐
753 State,hibernate} for the whole event manager process to
754 hibernate.
755 * If {swap_handler,Args1,NewState,Handler2,Args2} is returned,
757 the event handler is replaced by Handler2 by first calling
758 Module:terminate(Args1,NewState) and then Mod‐
759 ule2:init({Args2,Term}), where Term is the return value of
760 Module:terminate/2. For more information, see swap_han‐
761 dler/3.
762 * If remove_handler is returned, the event handler is deleted
764 by calling Module:terminate(remove_handler,State).
765 Module:handle_info(Info, State) -> Result
767 Types:
769 Info = term()
771 State = term()
772 Result = {ok,NewState} | {ok,NewState,hibernate}
773 | {swap_handler,Args1,NewState,Handler2,Args2} | remove_han‐
774 dler
775 NewState = term()
776 Args1 = Args2 = term()
777 Handler2 = Module2 | {Module2,Id}
778 Module2 = atom()
779 Id = term()
780 Note:
782 This callback is optional, so callback modules need not export
783 it. The gen_event module provides a default implementation of
784 this function that logs about the unexpected Info message, drops
785 it and returns {ok, State}.
786 This function is called for each installed event handler when an
789 event manager receives any other message than an event or a syn‐
790 chronous request (or a system message).
791 Info is the received message.
793 For a description of State and possible return values, see Mod‐
795 ule:handle_event/2.
796 Module:init(InitArgs) -> {ok,State} | {ok,State,hibernate} |
798 {error,Reason}
799 Types:
801 InitArgs = Args | {Args,Term}
803 Args = Term = term()
804 State = term()
805 Reason = term()
806 Whenever a new event handler is added to an event manager, this
808 function is called to initialize the event handler.
809 If the event handler is added because of a call to add_handler/3
811 or add_sup_handler/3, InitArgs is the Args argument of these
812 functions.
813 If the event handler replaces another event handler because of a
815 call to swap_handler/3 or swap_sup_handler/3, or because of a
816 swap return tuple from one of the other callback functions, Ini‐
817 tArgs is a tuple {Args,Term}, where Args is the argument pro‐
818 vided in the function call/return tuple and Term is the result
819 of terminating the old event handler, see swap_handler/3.
820 If successful, the function returns {ok,State} or
822 {ok,State,hibernate}, where State is the initial internal state
823 of the event handler.
824 If {ok,State,hibernate} is returned, the event manager goes into
826 hibernation (by calling proc_lib:hibernate/3), waiting for the
827 next event to occur.
828 Module:terminate(Arg, State) -> term()
830 Types:
832 Arg = Args | {stop,Reason} | stop | remove_handler
834 | {error,{'EXIT',Reason}} | {error,Term}
835 Args = Reason = Term = term()
836 Note:
838 This callback is optional, so callback modules need not export
839 it. The gen_event module provides a default implementation with‐
840 out cleanup.
841 Whenever an event handler is deleted from an event manager, this
844 function is called. It is to be the opposite of Module:init/1
845 and do any necessary cleaning up.
846 If the event handler is deleted because of a call to delete_han‐
848 dler/3, swap_handler/3, or swap_sup_handler/3, Arg is the Args
849 argument of this function call.
850 Arg={stop,Reason} if the event handler has a supervised connec‐
852 tion to a process that has terminated with reason Reason.
853 Arg=stop if the event handler is deleted because the event man‐
855 ager is terminating.
856 The event manager terminates if it is part of a supervision tree
858 and it is ordered by its supervisor to terminate. Even if it is
859 not part of a supervision tree, it terminates if it receives an
860 'EXIT' message from its parent.
861 Arg=remove_handler if the event handler is deleted because
863 another callback function has returned remove_handler or
864 {remove_handler,Reply}.
865 Arg={error,Term} if the event handler is deleted because a call‐
867 back function returned an unexpected value Term, or
868 Arg={error,{'EXIT',Reason}} if a callback function failed.
869 State is the internal state of the event handler.
871 The function can return any term. If the event handler is
873 deleted because of a call to gen_event:delete_handler/3, the
874 return value of that function becomes the return value of this
875 function. If the event handler is to be replaced with another
876 event handler because of a swap, the return value is passed to
877 the init function of the new event handler. Otherwise the return
878 value is ignored.
879
881 supervisor(3), sys(3)
882Ericsson AB stdlib 3.14.1 gen_event(3)