1gen_event(3)               Erlang Module Definition               gen_event(3)
2
3
4

NAME

6       gen_event - Generic event handling behavior.
7

DESCRIPTION

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
13       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
18       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
22       gen_event module                   Callback module
23       ----------------                   ---------------
24       gen_event:start
25       gen_event:start_link       ----->  -
26
27       gen_event:add_handler
28       gen_event:add_sup_handler  ----->  Module:init/1
29
30       gen_event:notify
31       gen_event:sync_notify      ----->  Module:handle_event/2
32
33       gen_event:call             ----->  Module:handle_call/2
34
35       -                          ----->  Module:handle_info/2
36
37       gen_event:delete_handler   ----->  Module:terminate/2
38
39       gen_event:swap_handler
40       gen_event:swap_sup_handler ----->  Module1:terminate/2
41                                          Module2:init/1
42
43       gen_event:which_handlers   ----->  -
44
45       gen_event:stop             ----->  Module:terminate/2
46
47       -                          ----->  Module:code_change/3
48
49       As each event handler is one callback module, an event manager has many
50       callback  modules  that are added and deleted dynamically. gen_event is
51       therefore more tolerant of callback module errors than the other behav‐
52       iors.  If a callback function for an installed event handler fails with
53       Reason, or returns a bad value Term, the event manager does  not  fail.
54       It deletes the event handler by calling callback function Module:termi‐
55       nate/2, giving as  argument  {error,{'EXIT',Reason}}  or  {error,Term},
56       respectively. No other event handler is affected.
57
58       A gen_event process handles system messages as described in sys(3). The
59       sys module can be used for debugging an event manager.
60
61       Notice that an event manager does trap exit signals automatically.
62
63       The gen_event process can go into hibernation (see  erlang:hibernate/3)
64       if  a  callback function in a handler module specifies hibernate in its
65       return value. This can be useful if the server is expected to  be  idle
66       for  a  long  time. However, use this feature with care, as hibernation
67       implies at least two garbage collections (when hibernating and  shortly
68       after waking up) and is not something you want to do between each event
69       handled by a busy event manager.
70
71       Notice that when multiple event handlers are invoked, it is  sufficient
72       that one single event handler returns a hibernate request for the whole
73       event manager to go into hibernation.
74
75       Unless otherwise stated, all functions in this module fail if the spec‐
76       ified event manager does not exist or if bad arguments are specified.
77

DATA TYPES

79       handler() = atom() | {atom(), term()}
80
81       handler_args() = term()
82
83       add_handler_ret() = ok | term() | {'EXIT', term()}
84
85       del_handler_ret() = ok | term() | {'EXIT', term()}
86

EXPORTS

88       add_handler(EventMgrRef, Handler, Args) -> Result
89
90              Types:
91
92                 EventMgrRef  =  Name  |  {Name,Node}  | {global,GlobalName} |
93                 {via,Module,ViaName} | pid()
94                  Name = Node = atom()
95                  GlobalName = ViaName = term()
96                 Handler = Module | {Module,Id}
97                  Module = atom()
98                  Id = term()
99                 Args = term()
100                 Result = ok | {'EXIT',Reason} | term()
101                  Reason = term()
102
103              Adds a new event handler to event manager EventMgrRef. The event
104              manager  calls  Module:init/1  to initiate the event handler and
105              its internal state.
106
107              EventMgrRef can be any of the following:
108
109                * The pid
110
111                * Name, if the event manager is locally registered
112
113                * {Name,Node}, if the event manager is locally  registered  at
114                  another node
115
116                * {global,GlobalName}, if the event manager is globally regis‐
117                  tered
118
119                * {via,Module,ViaName}, if the  event  manager  is  registered
120                  through an alternative process registry
121
122              Handler  is  the  name  of the callback module Module or a tuple
123              {Module,Id}, where Id is any term. The  {Module,Id}  representa‐
124              tion makes it possible to identify a specific event handler when
125              many event handlers use the same callback module.
126
127              Args is any  term  that  is  passed  as  the  argument  to  Mod‐
128              ule:init/1.
129
130              If  Module:init/1  returns a correct value indicating successful
131              completion, the event manager adds the event  handler  and  this
132              function  returns  ok.  If  Module:init/1  fails  with Reason or
133              returns {error,Reason}, the event handler is  ignored  and  this
134              function  returns  {'EXIT',Reason}  or  {error,Reason},  respec‐
135              tively.
136
137       add_sup_handler(EventMgrRef, Handler, Args) -> Result
138
139              Types:
140
141                 EventMgrRef = Name  |  {Name,Node}  |  {global,GlobalName}  |
142                 {via,Module,ViaName} | pid()
143                  Name = Node = atom()
144                  GlobalName = ViaName = term()
145                 Handler = Module | {Module,Id}
146                  Module = atom()
147                  Id = term()
148                 Args = term()
149                 Result = ok | {'EXIT',Reason} | term()
150                  Reason = term()
151
152              Adds  a  new event handler in the same way as add_handler/3, but
153              also supervises the connection between the event handler and the
154              calling process.
155
156                * If  the  calling  process  later terminates with Reason, the
157                  event manager deletes the  event  handler  by  calling  Mod‐
158                  ule:terminate/2 with {stop,Reason} as argument.
159
160                * If  the  event  handler  is deleted later, the event manager
161                  sends a message {gen_event_EXIT,Handler,Reason} to the call‐
162                  ing process. Reason is one of the following:
163
164                  * normal, if the event handler has been removed because of a
165                    call  to  delete_handler/3,  or  remove_handler  has  been
166                    returned by a callback function (see below).
167
168                  * shutdown,  if  the  event handler has been removed because
169                    the event manager is terminating.
170
171                  * {swapped,NewHandler,Pid}, if the process Pid has  replaced
172                    the  event  handler  with another event handler NewHandler
173                    using a call to swap_handler/3 or swap_sup_handler/3.
174
175                  * A term, if the event handler  is  removed  because  of  an
176                    error. Which term depends on the error.
177
178              For  a  description  of  the  arguments  and  return values, see
179              add_handler/3.
180
181       call(EventMgrRef, Handler, Request) -> Result
182       call(EventMgrRef, Handler, Request, Timeout) -> Result
183
184              Types:
185
186                 EventMgrRef = Name  |  {Name,Node}  |  {global,GlobalName}  |
187                 {via,Module,ViaName} | pid()
188                  Name = Node = atom()
189                  GlobalName = ViaName = term()
190                 Handler = Module | {Module,Id}
191                  Module = atom()
192                  Id = term()
193                 Request = term()
194                 Timeout = int()>0 | infinity
195                 Result = Reply | {error,Error}
196                  Reply = term()
197                  Error = bad_module | {'EXIT',Reason} | term()
198                  Reason = term()
199
200              Makes  a  synchronous call to event handler Handler installed in
201              event manager EventMgrRef by sending a request and waiting until
202              a  reply  arrives  or a time-out occurs. The event manager calls
203              Module:handle_call/2 to handle the request.
204
205              For a description of EventMgrRef and Handler, see add_handler/3.
206
207              Request is any term that is passed as one of  the  arguments  to
208              Module:handle_call/2.
209
210              Timeout  is an integer greater than zero that specifies how many
211              milliseconds to wait for a reply, or the atom infinity  to  wait
212              indefinitely.  Defaults  to 5000. If no reply is received within
213              the specified time, the function call fails.
214
215              The return value Reply is defined in the return  value  of  Mod‐
216              ule:handle_call/2.   If  the  specified  event  handler  is  not
217              installed, the function returns {error,bad_module}. If the call‐
218              back  function  fails with Reason or returns an unexpected value
219              Term,   this   function   returns   {error,{'EXIT',Reason}}   or
220              {error,Term}, respectively.
221
222       delete_handler(EventMgrRef, Handler, Args) -> Result
223
224              Types:
225
226                 EventMgrRef  =  Name  |  {Name,Node}  | {global,GlobalName} |
227                 {via,Module,ViaName} | pid()
228                  Name = Node = atom()
229                  GlobalName = ViaName = term()
230                 Handler = Module | {Module,Id}
231                  Module = atom()
232                  Id = term()
233                 Args = term()
234                 Result = term() | {error,module_not_found} | {'EXIT',Reason}
235                  Reason = term()
236
237              Deletes an event handler from  event  manager  EventMgrRef.  The
238              event  manager  calls  Module:terminate/2 to terminate the event
239              handler.
240
241              For a description of EventMgrRef and Handler, see add_handler/3.
242
243              Args is any term that is passed as one of the arguments to  Mod‐
244              ule:terminate/2.
245
246              The  return  value is the return value of Module:terminate/2. If
247              the specified event  handler  is  not  installed,  the  function
248              returns {error,module_not_found}. If the callback function fails
249              with Reason, the function returns {'EXIT',Reason}.
250
251       notify(EventMgrRef, Event) -> ok
252       sync_notify(EventMgrRef, Event) -> ok
253
254              Types:
255
256                 EventMgrRef = Name  |  {Name,Node}  |  {global,GlobalName}  |
257                 {via,Module,ViaName} | pid()
258                  Name = Node = atom()
259                  GlobalName = ViaName = term()
260                 Event = term()
261
262              Sends  an  event  notification to event manager EventMgrRef. The
263              event manager calls  Module:handle_event/2  for  each  installed
264              event handler to handle the event.
265
266              notify/2 is asynchronous and returns immediately after the event
267              notification has been sent. sync_notify/2 is synchronous in  the
268              sense that it returns ok after the event has been handled by all
269              event handlers.
270
271              For a description of EventMgrRef, see add_handler/3.
272
273              Event is any term that is passed as one of the arguments to Mod‐
274              ule:handle_event/2.
275
276              notify/1  does not fail even if the specified event manager does
277              not exist, unless it is specified as Name.
278
279       start() -> Result
280       start(EventMgrName | Options) -> Result
281       start(EventMgrName, Options) -> Result
282
283              Types:
284
285                 EventMgrName = {local,Name} | {global,GlobalName} | {via,Mod‐
286                 ule,ViaName}
287                  Name = atom()
288                  GlobalName = ViaName = term()
289                 Options = [Option]
290                  Option   =   {debug,Dbgs}   |   {timeout,Time}   |   {hiber‐
291                 nate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}
292                  Dbgs = [Dbg]
293                  Dbg = trace | log | statistics  |  {log_to_file,FileName}  |
294                 {install,{Func,FuncState}}
295                  SOpts = [term()]
296                 Result = {ok,Pid} | {error,{already_started,Pid}}
297                  Pid = pid()
298
299              Creates  a  stand-alone event manager process, that is, an event
300              manager that is not part of a supervision tree and thus  has  no
301              supervisor.
302
303              For  a  description  of  the  arguments  and  return values, see
304              start_link/0,1.
305
306       start_link() -> Result
307       start_link(EventMgrName | Options) -> Result
308       start_link(EventMgrName, Options) -> Result
309
310              Types:
311
312                 EventMgrName = {local,Name} | {global,GlobalName} | {via,Mod‐
313                 ule,ViaName}
314                  Name = atom()
315                  GlobalName = ViaName = term()
316                 Options = [Option]
317                  Option   =   {debug,Dbgs}   |   {timeout,Time}   |   {hiber‐
318                 nate_after,HibernateAfterTimeout} | {spawn_opt,SOpts}
319                  Dbgs = [Dbg]
320                  Dbg = trace | log | statistics  |  {log_to_file,FileName}  |
321                 {install,{Func,FuncState}}
322                  SOpts = [term()]
323                 Result = {ok,Pid} | {error,{already_started,Pid}}
324                  Pid = pid()
325
326              Creates  an event manager process as part of a supervision tree.
327              The function is to be called, directly  or  indirectly,  by  the
328              supervisor.  For  example,  it ensures that the event manager is
329              linked to the supervisor.
330
331                * If EventMgrName={local,Name}, the event  manager  is  regis‐
332                  tered locally as Name using register/2.
333
334                * If  EventMgrName={global,GlobalName},  the  event manager is
335                  registered  globally  as  GlobalName   using   global:regis‐
336                  ter_name/2. If no name is provided, the event manager is not
337                  registered.
338
339                * If EventMgrName={via,Module,ViaName}, the event manager reg‐
340                  isters  with  the registry represented by Module. The Module
341                  callback is to export the functions register_name/2,  unreg‐
342                  ister_name/1,  whereis_name/1,  and  send/2,  which  are  to
343                  behave as  the  corresponding  functions  in  global.  Thus,
344                  {via,global,GlobalName} is a valid reference.
345
346                * If    option    {hibernate_after,HibernateAfterTimeout}   is
347                  present, the gen_event process awaits any message for Hiber‐
348                  nateAfterTimeout milliseconds and if no message is received,
349                  the process goes into hibernation automatically (by  calling
350                  proc_lib:hibernate/3).
351
352              If  the  event  manager  is  successfully  created, the function
353              returns {ok,Pid}, where Pid is the pid of the event manager.  If
354              a  process  with  the specified EventMgrName exists already, the
355              function returns {error,{already_started,Pid}}, where Pid is the
356              pid of that process.
357
358       stop(EventMgrRef) -> ok
359       stop(EventMgrRef, Reason, Timeout) -> ok
360
361              Types:
362
363                 EventMgrRef  =  Name  |  {Name,Node}  | {global,GlobalName} |
364                 {via,Module,ViaName} | pid()
365                 Name = Node = atom()
366                 GlobalName = ViaName = term()
367                 Reason = term()
368                 Timeout = int()>0 | infinity
369
370              Orders event manager EventMgrRef to exit with the specifies Rea‐
371              son and waits for it to terminate. Before terminating, gen_event
372              calls Module:terminate(stop,...) for each installed  event  han‐
373              dler.
374
375              The function returns ok if the event manager terminates with the
376              expected reason. Any other  reason  than  normal,  shutdown,  or
377              {shutdown,Term}  causes  an error report to be issued using log‐
378              ger(3). The default Reason is normal.
379
380              Timeout is an integer greater than zero that specifies how  many
381              milliseconds  to wait for the event manager to terminate, or the
382              atom infinity to wait indefinitely. Defaults to infinity. If the
383              event  manager  has  not terminated within the specified time, a
384              timeout exception is raised.
385
386              If the process does not exist, a noproc exception is raised.
387
388              For a description of EventMgrRef, see add_handler/3.
389
390       swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result
391
392              Types:
393
394                 EventMgrRef = Name  |  {Name,Node}  |  {global,GlobalName}  |
395                 {via,Module,ViaName} | pid()
396                  Name = Node = atom()
397                  GlobalName = ViaName = term()
398                 Handler1 = Handler2 = Module | {Module,Id}
399                  Module = atom()
400                  Id = term()
401                 Args1 = Args2 = term()
402                 Result = ok | {error,Error}
403                  Error = {'EXIT',Reason} | term()
404                  Reason = term()
405
406              Replaces  an old event handler with a new event handler in event
407              manager EventMgrRef.
408
409              For a description of the arguments, see add_handler/3.
410
411              First the old event handler Handler1 is deleted. The event  man‐
412              ager  calls  Module1:terminate(Args1, ...), where Module1 is the
413              callback module of Handler1, and collects the return value.
414
415              Then the new event handler Handler2 is added  and  initiated  by
416              calling  Module2:init({Args2,Term}),  where Module2 is the call‐
417              back module of Handler2 and Term is the  return  value  of  Mod‐
418              ule1:terminate/2. This makes it possible to transfer information
419              from Handler1 to Handler2.
420
421              The new handler is added even if the  the  specified  old  event
422              handler  is  not installed, in which case Term=error, or if Mod‐
423              ule1:terminate/2   fails   with   Reason,    in    which    case
424              Term={'EXIT',Reason}.  The  old  handler is deleted even if Mod‐
425              ule2:init/1 fails.
426
427              If there was a supervised  connection  between  Handler1  and  a
428              process  Pid,  there is a supervised connection between Handler2
429              and Pid instead.
430
431              If Module2:init/1 returns a correct value, this function returns
432              ok. If Module2:init/1 fails with Reason or returns an unexpected
433              value Term, this  function  returns  {error,{'EXIT',Reason}}  or
434              {error,Term}, respectively.
435
436       swap_sup_handler(EventMgrRef,  {Handler1,Args1},  {Handler2,Args2})  ->
437       Result
438
439              Types:
440
441                 EventMgrRef = Name  |  {Name,Node}  |  {global,GlobalName}  |
442                 {via,Module,ViaName} | pid()
443                  Name = Node = atom()
444                  GlobalName = ViaName = term()
445                 Handler1 = Handler 2 = Module | {Module,Id}
446                  Module = atom()
447                  Id = term()
448                 Args1 = Args2 = term()
449                 Result = ok | {error,Error}
450                  Error = {'EXIT',Reason} | term()
451                  Reason = term()
452
453              Replaces  an  event  handler in event manager EventMgrRef in the
454              same way as swap_handler/3, but also supervises  the  connection
455              between Handler2 and the calling process.
456
457              For  a  description  of  the  arguments  and  return values, see
458              swap_handler/3.
459
460       which_handlers(EventMgrRef) -> [Handler]
461
462              Types:
463
464                 EventMgrRef = Name  |  {Name,Node}  |  {global,GlobalName}  |
465                 {via,Module,ViaName} | pid()
466                  Name = Node = atom()
467                  GlobalName = ViaName = term()
468                 Handler = Module | {Module,Id}
469                  Module = atom()
470                  Id = term()
471
472              Returns  a list of all event handlers installed in event manager
473              EventMgrRef.
474
475              For a description of EventMgrRef and Handler, see add_handler/3.
476

CALLBACK FUNCTIONS

478       The following functions are to be exported from  a  gen_event  callback
479       module.
480

EXPORTS

482       Module:code_change(OldVsn, State, Extra) -> {ok, NewState}
483
484              Types:
485
486                 OldVsn = Vsn | {down, Vsn}
487                  Vsn = term()
488                 State = NewState = term()
489                 Extra = term()
490
491          Note:
492              This  callback  is optional, so callback modules need not export
493              it. If a release upgrade/downgrade with  Change={advanced,Extra}
494              specified  in  the  .appup file is made when code_change/3 isn't
495              implemented the event handler will crash  with  an  undef  error
496              reason.
497
498
499              This  function  is called for an installed event handler that is
500              to update its internal state during a release upgrade/downgrade,
501              that  is, when the instruction {update,Module,Change,...}, where
502              Change={advanced,Extra}, is specified in the  .appup  file.  For
503              more information, see OTP Design Principles.
504
505              For  an  upgrade,  OldVsn is Vsn, and for a downgrade, OldVsn is
506              {down,Vsn}. Vsn is defined by the vsn attribute(s)  of  the  old
507              version  of  the callback module Module. If no such attribute is
508              defined, the version is the checksum of the Beam file.
509
510              State is the internal state of the event handler.
511
512              Extra is passed "as is" from the {advanced,Extra}  part  of  the
513              update instruction.
514
515              The function is to return the updated internal state.
516
517       Module:format_status(Opt, [PDict, State]) -> Status
518
519              Types:
520
521                 Opt = normal | terminate
522                 PDict = [{Key, Value}]
523                 State = term()
524                 Status = term()
525
526          Note:
527              This  callback  is  optional,  so event handler modules need not
528              export it. If a handler  does  not  export  this  function,  the
529              gen_event  module  uses  the handler state directly for the pur‐
530              poses described below.
531
532
533              This function is called by a gen_event process in the  following
534              situations:
535
536                * One  of  sys:get_status/1,2  is invoked to get the gen_event
537                  status. Opt is set to the atom normal for this case.
538
539                * The event handler terminates abnormally and  gen_event  logs
540                  an error. Opt is set to the atom terminate for this case.
541
542              This  function is useful for changing the form and appearance of
543              the event handler state for these cases. An event handler  call‐
544              back  module wishing to change the the sys:get_status/1,2 return
545              value as well as how its  state  appears  in  termination  error
546              logs, exports an instance of format_status/2 that returns a term
547              describing the current state of the event handler.
548
549              PDict  is  the  current  value  of  the  process  dictionary  of
550              gen_event.
551
552              State is the internal state of the event handler.
553
554              The function is to return Status, a term that change the details
555              of the current state of the event handler. Any term  is  allowed
556              for Status. The gen_event module uses Status as follows:
557
558                * When  sys:get_status/1,2  is  called, gen_event ensures that
559                  its return value contains Status in place of the state  term
560                  of the event handler.
561
562                * When  an event handler terminates abnormally, gen_event logs
563                  Status in place of the state term of the event handler.
564
565              One use for this function is to return compact alternative state
566              representations  to  avoid that large state terms are printed in
567              log files.
568
569       Module:handle_call(Request, State) -> Result
570
571              Types:
572
573                 Request = term()
574                 State = term()
575                 Result = {ok,Reply,NewState} | {ok,Reply,NewState,hibernate}
576                  | {swap_handler,Reply,Args1,NewState,Handler2,Args2}
577                  | {remove_handler, Reply}
578                  Reply = term()
579                  NewState = term()
580                  Args1 = Args2 = term()
581                  Handler2 = Module2 | {Module2,Id}
582                  Module2 = atom()
583                  Id = term()
584
585              Whenever  an  event  manager  receives  a  request  sent   using
586              call/3,4,  this  function is called for the specified event han‐
587              dler to handle the request.
588
589              Request is the Request argument of call/3,4.
590
591              State is the internal state of the event handler.
592
593              The return values are  the  same  as  for  Module:handle_event/2
594              except  that  they also contain a term Reply, which is the reply
595              to the client as the return value of call/3,4.
596
597       Module:handle_event(Event, State) -> Result
598
599              Types:
600
601                 Event = term()
602                 State = term()
603                 Result = {ok,NewState} | {ok,NewState,hibernate}
604                  | {swap_handler,Args1,NewState,Handler2,Args2} | remove_han‐
605                 dler
606                  NewState = term()
607                  Args1 = Args2 = term()
608                  Handler2 = Module2 | {Module2,Id}
609                  Module2 = atom()
610                  Id = term()
611
612              Whenever  an event manager receives an event sent using notify/2
613              or sync_notify/2, this function is  called  for  each  installed
614              event handler to handle the event.
615
616              Event is the Event argument of notify/2/sync_notify/2.
617
618              State is the internal state of the event handler.
619
620                * If {ok,NewState} or {ok,NewState,hibernate} is returned, the
621                  event handler remains in the event manager with the possible
622                  updated internal state NewState.
623
624                * If  {ok,NewState,hibernate}  is  returned, the event manager
625                  also  goes  into  hibernation  (by  calling  proc_lib:hiber‐
626                  nate/3),  waiting  for the next event to occur. It is suffi‐
627                  cient  that  one  of  the  event  handlers  return  {ok,New‐
628                  State,hibernate}  for  the  whole  event  manager process to
629                  hibernate.
630
631                * If {swap_handler,Args1,NewState,Handler2,Args2} is returned,
632                  the  event  handler is replaced by Handler2 by first calling
633                  Module:terminate(Args1,NewState)     and      then      Mod‐
634                  ule2:init({Args2,Term}),  where  Term is the return value of
635                  Module:terminate/2.  For  more  information,  see  swap_han‐
636                  dler/3.
637
638                * If  remove_handler is returned, the event handler is deleted
639                  by calling Module:terminate(remove_handler,State).
640
641       Module:handle_info(Info, State) -> Result
642
643              Types:
644
645                 Info = term()
646                 State = term()
647                 Result = {ok,NewState} | {ok,NewState,hibernate}
648                  | {swap_handler,Args1,NewState,Handler2,Args2} | remove_han‐
649                 dler
650                  NewState = term()
651                  Args1 = Args2 = term()
652                  Handler2 = Module2 | {Module2,Id}
653                  Module2 = atom()
654                  Id = term()
655
656          Note:
657              This  callback  is optional, so callback modules need not export
658              it. The gen_event module provides a  default  implementation  of
659              this function that logs about the unexpected Info message, drops
660              it and returns {ok, State}.
661
662
663              This function is called for each installed event handler when an
664              event manager receives any other message than an event or a syn‐
665              chronous request (or a system message).
666
667              Info is the received message.
668
669              For a description of State and possible return values, see  Mod‐
670              ule:handle_event/2.
671
672       Module:init(InitArgs)    ->   {ok,State}   |   {ok,State,hibernate}   |
673       {error,Reason}
674
675              Types:
676
677                 InitArgs = Args | {Args,Term}
678                  Args = Term = term()
679                 State = term()
680                 Reason = term()
681
682              Whenever a new event handler is added to an event manager,  this
683              function is called to initialize the event handler.
684
685              If the event handler is added because of a call to add_handler/3
686              or add_sup_handler/3, InitArgs is the  Args  argument  of  these
687              functions.
688
689              If the event handler replaces another event handler because of a
690              call to swap_handler/3 or swap_sup_handler/3, or  because  of  a
691              swap return tuple from one of the other callback functions, Ini‐
692              tArgs is a tuple {Args,Term}, where Args is  the  argument  pro‐
693              vided  in  the function call/return tuple and Term is the result
694              of terminating the old event handler, see swap_handler/3.
695
696              If   successful,   the   function    returns    {ok,State}    or
697              {ok,State,hibernate},  where State is the initial internal state
698              of the event handler.
699
700              If {ok,State,hibernate} is returned, the event manager goes into
701              hibernation  (by  calling proc_lib:hibernate/3), waiting for the
702              next event to occur.
703
704       Module:terminate(Arg, State) -> term()
705
706              Types:
707
708                 Arg = Args | {stop,Reason} | stop | remove_handler
709                  | {error,{'EXIT',Reason}} | {error,Term}
710                  Args = Reason = Term = term()
711
712          Note:
713              This callback is optional, so callback modules need  not  export
714              it. The gen_event module provides a default implementation with‐
715              out cleanup.
716
717
718              Whenever an event handler is deleted from an event manager, this
719              function  is  called.  It is to be the opposite of Module:init/1
720              and do any necessary cleaning up.
721
722              If the event handler is deleted because of a call to delete_han‐
723              dler/3,  swap_handler/3,  or swap_sup_handler/3, Arg is the Args
724              argument of this function call.
725
726              Arg={stop,Reason} if the event handler has a supervised  connec‐
727              tion to a process that has terminated with reason Reason.
728
729              Arg=stop  if the event handler is deleted because the event man‐
730              ager is terminating.
731
732              The event manager terminates if it is part of a supervision tree
733              and  it is ordered by its supervisor to terminate. Even if it is
734              not part of a supervision tree, it terminates if it receives  an
735              'EXIT' message from its parent.
736
737              Arg=remove_handler  if  the  event  handler  is  deleted because
738              another  callback  function  has  returned   remove_handler   or
739              {remove_handler,Reply}.
740
741              Arg={error,Term} if the event handler is deleted because a call‐
742              back  function   returned   an   unexpected   value   Term,   or
743              Arg={error,{'EXIT',Reason}} if a callback function failed.
744
745              State is the internal state of the event handler.
746
747              The  function  can  return  any  term.  If  the event handler is
748              deleted because of a  call  to  gen_event:delete_handler/3,  the
749              return  value  of that function becomes the return value of this
750              function. If the event handler is to be  replaced  with  another
751              event  handler  because of a swap, the return value is passed to
752              the init function of the new event handler. Otherwise the return
753              value is ignored.
754

SEE ALSO

756       supervisor(3), sys(3)
757
758
759
760Ericsson AB                       stdlib 3.10                     gen_event(3)
Impressum