File: gen_event.html

package info (click to toggle)
erlang-doc-html 1%3A11.b.2-1
links: PTS
area: main
in suites: etch, etch-m68k
size: 23,284 kB
ctags: 10,724
sloc: erlang: 505; ansic: 323; makefile: 62; perl: 61; sh: 45
file content (778 lines) | stat: -rw-r--r-- 30,765 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.3 -->
<HTML>
<HEAD>
  <TITLE>gen_event</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>gen_event</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
gen_event
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Generic Event Handling Behaviour
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>A behaviour module for implementing event handling functionality.
The OTP event handling model consists of a generic event manager
process with an arbitrary number of event handlers which are added and
deleted dynamically.
<P> An event manager implemented using this module will have a standard
set of interface functions and include functionality for tracing and
error reporting. It will also fit into an OTP supervision tree.
Refer to <STRONG>OTP Design Principles</STRONG> for more information.
<P>Each event handler is implemented as a callback module exporting
a pre-defined set of functions. The relationship between the behaviour
functions and the callback functions can be illustrated as follows:
<PRE>
gen_event module                   Callback module
---------------                    -------------
gen_event:start_link       -----&#62;  -

gen_event:add_handler
gen_event:add_suphandler   -----&#62;  Module:init/1

gen_event:notify
gen_event:sync_notify      -----&#62;  Module:handle_event/2

gen_event:call             -----&#62;  Module:handle_call/2

-                          -----&#62;  Module:handle_info/2

gen_event:delete_handler   -----&#62;  Module:terminate/2

gen_event:swap_handler
gen_event:swap_sup_handler -----&#62;  Module1:terminate/2
                                   Module2:init/1

gen_event:which_handlers   -----&#62;  -

gen_event:stop             -----&#62;  Module:terminate/2

-                          -----&#62;  Module:code_change/3
    
</PRE>

<P>Since each event handler is one callback module, an event manager
will have several callback modules which are added and deleted
dynamically. Therefore <CODE>gen_event</CODE> is more tolerant of callback
module errors than the other behaviours. If a callback function for
an installed event handler fails with <CODE>Reason</CODE>, or returns a
bad value <CODE>Term</CODE>, the event manager will not fail. It will delete
the event handler by calling the callback function
<CODE>Module:terminate/2</CODE> (see below), giving as argument
<CODE>{error,{'EXIT',Reason}}</CODE> or <CODE>{error,Term}</CODE>, respectively.
No other event handler will be affected.
<P>The <CODE>sys</CODE> module can be used for debugging an event manager.
<P>Note that an event manager <STRONG>does</STRONG> trap exit signals
automatically.

<P>Unless otherwise stated, all functions in this module fail if
the specified event manager does not exist or if bad arguments are
given.
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="start_link/0"><STRONG><CODE>start_link() -&#62; Result</CODE></STRONG></A><BR>
<A NAME="start_link/1"><STRONG><CODE>start_link(EventMgrName) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgrName = {local,Name} | {global,Name}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Pid} | {error,{already_started,Pid}}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Creates an event manager process as part of a supervision
         tree. The function should be called, directly or indirectly,
         by the supervisor. It will, among other things, ensure that
         the event manager is linked to the supervisor.
<P>If <CODE>EventMgrName={local,Name}</CODE>, the event manager is
         registered locally as <CODE>Name</CODE> using <CODE>register/2</CODE>.
         If <CODE>EventMgrName={global,Name}</CODE>, the event manager is
         registered globally as <CODE>Name</CODE> using
         <CODE>global:register_name/2</CODE>. If no name is provided,
         the event manager is not registered.
<P>If the event manager is successfully created the function
         returns <CODE>{ok,Pid}</CODE>, where <CODE>Pid</CODE> is the pid of
         the event manager. If there already exists a process with
         the specified <CODE>EventMgrName</CODE> the function returns
         <CODE>{error,{already_started,Pid}}</CODE>, where <CODE>Pid</CODE> is
         the pid of that process.
</DIV>

<P><A NAME="start/0"><STRONG><CODE>start() -&#62; Result</CODE></STRONG></A><BR>
<A NAME="start/1"><STRONG><CODE>start(EventMgrName) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgrName = {local,Name} | {global,Name}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Pid} | {error,{already_started,Pid}}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Creates a stand-alone event manager process, i.e. an event
         manager which is not part of a supervision tree and thus has
         no supervisor.
<P>See <CODE>start_link/0,1</CODE> for a description of arguments and
         return values.
</DIV>

<P><A NAME="add_handler/3"><STRONG><CODE>add_handler(EventMgrRef, Handler, Args) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgr = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Handler = Module | {Module,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | {'EXIT',Reason} | term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Adds a new event handler to the event manager <CODE>EventMgrRef</CODE>.
         The event manager will call <CODE>Module:init/1</CODE> to initiate
         the event handler and its internal state.
<P><CODE>EventMgrRef</CODE> can be:
<P>
<UL>

<LI>
the pid,
</LI>


<LI>
<CODE>Name</CODE>, if the event manager is locally registered,
         
</LI>


<LI>
<CODE>{Name,Node}</CODE>, if the event manager is locally
         registered at another node, or
</LI>


<LI>
<CODE>{global,Name}</CODE>, if the event manager is globally
         registered.
</LI>


</UL>

<P><CODE>Handler</CODE> is the name of the callback module <CODE>Module</CODE> or
         a tuple <CODE>{Module,Id}</CODE>, where <CODE>Id</CODE> is any term.
         The <CODE>{Module,Id}</CODE> representation makes it possible to
         identify a specific event handler when there are several event
         handlers using the same callback module.
<P><CODE>Args</CODE> is an arbitrary term which is passed as the argument
         to <CODE>Module:init/1</CODE>.
<P>If <CODE>Module:init/1</CODE> returns a correct value, the event
         manager adds the event handler and this function returns
         <CODE>ok</CODE>. If <CODE>Module:init/1</CODE> fails with <CODE>Reason</CODE> or
         returns an unexpected value <CODE>Term</CODE>, the event handler is
         ignored and this function returns <CODE>{'EXIT',Reason}</CODE> or
         <CODE>Term</CODE>, respectively.
</DIV>

<P><A NAME="add_sup_handler/3"><STRONG><CODE>add_sup_handler(EventMgrRef, Handler, Args) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgr = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Handler = Module | {Module,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | {'EXIT',Reason} | term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Adds a new event handler in the same way as <CODE>add_handler/3</CODE>
         but will also supervise the connection between the event handler
         and the calling process.
<P>
<UL>

<LI>
If the calling process later terminates with <CODE>Reason</CODE>,
         the event manager will delete the event handler by calling
         <CODE>Module:terminate/2</CODE> with <CODE>{stop,Reason}</CODE> as argument.
         
</LI>


<LI>
If the event handler later is deleted, the event manager
         sends a message<CODE>{gen_event_EXIT,Handler,Reason}</CODE> to
         the calling process. <CODE>Reason</CODE> is one of the following:
         
<UL>

<LI>
                <CODE>normal</CODE>, if the event handler has been removed due to a
                call to <CODE>delete_handler/3</CODE>, or <CODE>remove_handler</CODE>
                has been returned by a callback function (see below).
         
</LI>


<LI>
                <CODE>shutdown</CODE>, if the event handler has been removed
                because the event manager is terminating.
         
</LI>


<LI>
                <CODE>{swapped,NewHandler,Pid}</CODE>, if the process <CODE>Pid</CODE>
                has replaced the event handler with another event handler
                <CODE>NewHandler</CODE> using a call to <CODE>swap_handler/3</CODE> or
                <CODE>swap_sup_handler/3</CODE>.
         
</LI>


<LI>
                a term, if the event handler is removed due to an error.
                Which term depends on the error.
         
</LI>


</UL>

         
</LI>


</UL>

<P>See <CODE>add_handler/3</CODE> for a description of the arguments
         and return values.
</DIV>

<P><A NAME="notify/2"><STRONG><CODE>notify(EventMgrRef, Event) -&#62; ok</CODE></STRONG></A><BR>
<A NAME="sync_notify/2"><STRONG><CODE>sync_notify(EventMgrRef, Event) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Sends an event notification to the event manager
         <CODE>EventMgrRef</CODE>. The event manager will call
         <CODE>Module:handle_event/2</CODE> for each installed event handler to
         handle the event.
<P><CODE>notify</CODE> is asynchronous and will return immediately after
         the event notification has been sent. <CODE>sync_notify</CODE> is
         synchronous in the sense that it will return <CODE>ok</CODE> after
         the event has been handled by all event handlers.
<P>See <CODE>add_handler/3</CODE> for a description of <CODE>EventMgrRef</CODE>.
        
<P><CODE>Event</CODE> is an arbitrary term which is passed as one of
         the arguments to <CODE>Module:handle_event/2</CODE>.
<P><CODE>notify</CODE> will not fail even if the specified event manager
         does not exist, unless it is specified as <CODE>Name</CODE>.

</DIV>

<P><A NAME="call/3"><STRONG><CODE>call(EventMgrRef, Handler, Request) -&#62; Result</CODE></STRONG></A><BR>
<A NAME="call/4"><STRONG><CODE>call(EventMgrRef, Handler, Request, Timeout) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Handler = Module | {Module,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>
<STRONG><CODE>Request = term()</CODE></STRONG><BR>
<STRONG><CODE>Timeout = int()&#62;0 | infinity</CODE></STRONG><BR>
<STRONG><CODE>Result = Reply | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>
<STRONG><CODE>Error = bad_module | {'EXIT',Reason} | term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Makes a synchronous call to the event handler <CODE>Handler</CODE>
         installed in the event manager <CODE>EventMgrRef</CODE> by sending a
         request and waiting until a reply arrives or a timeout occurs.
         The event manager will call <CODE>Module:handle_call/2</CODE> to handle
         the request.
<P>See <CODE>add_handler/3</CODE> for a description of <CODE>EventMgrRef</CODE>
         and <CODE>Handler</CODE>.
<P><CODE>Request</CODE> is an arbitrary term which is passed as one of
         the arguments to <CODE>Module:handle_call/2</CODE>.
<P><CODE>Timeout</CODE> is an integer greater than zero which specifies
         how many milliseconds to wait for a reply, or the atom
         <CODE>infinity</CODE> to wait indefinitely. Default value is 5000.
         If no reply is received within the specified time, the function
         call fails.
<P>The return value <CODE>Reply</CODE> is defined in the return value of
         <CODE>Module:handle_call/2</CODE>. If the specified event handler is not
         installed, the function returns <CODE>{error,bad_module}</CODE>. If
         the callback function fails with <CODE>Reason</CODE> or returns an
         unexpected value <CODE>Term</CODE>, this function returns
         <CODE>{error,{'EXIT',Reason}}</CODE> or <CODE>{error,Term}</CODE>,
         respectively.
</DIV>

<P><A NAME="delete_handler/3"><STRONG><CODE>delete_handler(EventMgrRef, Handler, Args) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Handler = Module | {Module,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>
<STRONG><CODE>Args = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = term() | {error,module_not_found} | {'EXIT',Reason}</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Deletes an event handler from the event manager
         <CODE>EventMgrRef</CODE>. The event manager will call
         <CODE>Module:terminate/2</CODE> to terminate the event handler.
<P>See <CODE>add_handler/3</CODE> for a description of <CODE>EventMgrRef</CODE>
         and <CODE>Handler</CODE>.
<P><CODE>Args</CODE> is an arbitrary term which is passed as one of
         the arguments to <CODE>Module:terminate/2</CODE>.
<P>The return value is the return value of <CODE>Module:terminate/2</CODE>.
         If the specified event handler is not installed, the function
         returns <CODE>{error,module_not_found}</CODE>. If the callback function
         fails with <CODE>Reason</CODE>, the function returns
         <CODE>{'EXIT',Reason}</CODE>.
</DIV>

<P><A NAME="swap_handler/5"><STRONG><CODE>swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2})
        -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Handler1 = Handler2 = Module | {Module,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>
<STRONG><CODE>Args1 = Args2 = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE>Error = {'EXIT',Reason} | term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Replaces an old event handler with a new event handler in
         the event manager <CODE>EventMgrRef</CODE>.
<P>See <CODE>add_handler/3</CODE> for a description of the arguments.
<P>First the old event handler <CODE>Handler1</CODE> is deleted.
         The event manager calls <CODE>Module1:terminate(Args1, ...)</CODE>,
         where <CODE>Module1</CODE> is the callback module of <CODE>Handler1</CODE>,
         and collects the return value.
<P>Then the new event handler <CODE>Handler2</CODE> is added and initiated
         by calling <CODE>Module2:init({Args2,Term})</CODE>, where <CODE>Module2</CODE>
         is the callback module of <CODE>Handler2</CODE> and <CODE>Term</CODE>
         the return value of <CODE>Module1:terminate/2</CODE>. This makes it
         possible to transfer information from <CODE>Handler1</CODE> to
         <CODE>Handler2</CODE>.
<P>The new handler will be added even if the the specified old event
         handler is not installed in which case <CODE>Term=error</CODE>, or if
         <CODE>Module1:terminate/2</CODE> fails with <CODE>Reason</CODE> in which case
         <CODE>Term={'EXIT',Reason}</CODE>.
         The old handler will be deleted even if <CODE>Module2:init/1</CODE>
         fails.
<P>If there was a supervised connection between <CODE>Handler1</CODE> and
         a process <CODE>Pid</CODE>, there will be a supervised connection
         between <CODE>Handler2</CODE> and <CODE>Pid</CODE> instead.
<P>If <CODE>Module2:init/1</CODE> returns a correct value, this function
         returns <CODE>ok</CODE>. If <CODE>Module2:init/1</CODE> fails with
         <CODE>Reason</CODE> or returns an unexpected value <CODE>Term</CODE>, this
         this function returns <CODE>{error,{'EXIT',Reason}}</CODE> or
         <CODE>{error,Term}</CODE>, respectively.
</DIV>

<P><A NAME="swap_sup_handler/5"><STRONG><CODE>swap_sup_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2})
        -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Handler1 = Handler 2 = Module | {Module,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>
<STRONG><CODE>Args1 = Args2 = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = ok | {error,Error}</CODE></STRONG><BR>
<STRONG><CODE>Error = {'EXIT',Reason} | term()</CODE></STRONG><BR>
<STRONG><CODE>Reason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Replaces an event handler in the event manager <CODE>EventMgrRef</CODE>
         in the same way as <CODE>swap_handler/3</CODE> but will also supervise
         the connection between <CODE>Handler2</CODE> and the calling process.
<P>See <CODE>swap_handler/3</CODE> for a description of the arguments
         and return values.
</DIV>

<P><A NAME="which_handlers/1"><STRONG><CODE>which_handlers(EventMgrRef) -&#62; [Handler]</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>
<STRONG><CODE>Handler = Module | {Module,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a list of all event handlers installed in the event
         manager <CODE>EventMgrRef</CODE>.
<P>See <CODE>add_handler/3</CODE> for a description of <CODE>EventMgrRef</CODE>
         and <CODE>Handler</CODE>.
</DIV>

<P><A NAME="stop/1"><STRONG><CODE>stop(EventMgrRef) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</CODE></STRONG><BR>
<STRONG><CODE>Name = Node = atom()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Terminates the event manager <CODE>EventMgrRef</CODE>. Before
         terminating, the event manager will call
         <CODE>Module:terminate(stop,...)</CODE> for each installed event
         handler.
<P>See <CODE>add_handler/3</CODE> for a description of the argument.
</DIV>

<H3>CALLBACK FUNCTIONS</H3>
<DIV CLASS=REFBODY>

<P>The following functions should be exported from a <CODE>gen_event</CODE>
callback module.
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="Module:init/1"><STRONG><CODE>Module:init(InitArgs) -&#62; {ok,State}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>InitArgs = Args | {Args,Term}</CODE></STRONG><BR>
<STRONG><CODE>Args = Term = term()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Whenever a new event handler is added to an event manager,
         this function is called to initialize the event handler.
<P>If the event handler is added due to a call to
         <CODE>gen_event:add_handler/3</CODE> or
         <CODE>gen_event:add_sup_handler/3</CODE>, <CODE>InitArgs</CODE> is
         the <CODE>Args</CODE> argument of these functions.
<P>If the event handler is replacing another event handler due to
         a call to <CODE>gen_event:swap_handler/3</CODE> or
         <CODE>gen_event:swap_sup_handler/3</CODE>, or due to a <CODE>swap</CODE>
         return tuple from one of the other callback functions,
         <CODE>InitArgs</CODE> is a tuple <CODE>{Args,Term}</CODE> where <CODE>Args</CODE> is
         the argument provided in the function call/return tuple and
         <CODE>Term</CODE> is the result of terminating the old event handler,
         see <CODE>gen_event:swap_handler/3</CODE>.
<P>The function should return <CODE>{ok,State}</CODE> where <CODE>State</CODE>
         is the initial internal state of the event handler.
</DIV>

<P><A NAME="Module:handle_event/2"><STRONG><CODE>Module:handle_event(Event, State) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Event = term()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,NewState}</CODE></STRONG><BR>
<STRONG><CODE>| {swap_handler,Args1,NewState,Handler2,Args2} |
         remove_handler</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Args1 = Args2 = term()</CODE></STRONG><BR>
<STRONG><CODE>Handler2 = Module2 | {Module2,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module2 = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Whenever an event manager receives an event sent using
         <CODE>gen_event:notify/2</CODE> or <CODE>gen_event:sync_notify/2</CODE>, this
         function is called for each installed event handler to handle
         the event.
<P><CODE>Event</CODE> is the <CODE>Event</CODE> argument of
         <CODE>notify</CODE>/<CODE>sync_notify</CODE>.
<P><CODE>State</CODE> is the internal state of the event handler.
<P>If the function returns <CODE>{ok,NewState}</CODE> the event handler
         will remain in the event manager with the possible updated
         internal state <CODE>NewState</CODE>.
<P>If the function returns
         <CODE>{swap_handler,Args1,NewState,Handler2,Args2}</CODE> the event
         handler will be replaced by <CODE>Handler2</CODE> by first calling
         <CODE>Module:terminate(Args1,NewState)</CODE> and then
         <CODE>Module2:init({Args2,Term})</CODE> where <CODE>Term</CODE> is the return
         value of <CODE>Module:terminate/2</CODE>.
         See <CODE>gen_event:swap_handler/3</CODE> for more information.
<P>If the function returns <CODE>remove_handler</CODE> the event handler
         will be deleted by calling
         <CODE>Module:terminate(remove_handler,State)</CODE>.
</DIV>

<P><A NAME="Module:handle_call/2"><STRONG><CODE>Module:handle_call(Request, State) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Request = term()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,Reply,NewState}</CODE></STRONG><BR>
<STRONG><CODE>| {swap_handler,Reply,Args1,NewState,Handler2,Args2}</CODE></STRONG><BR>
<STRONG><CODE>| {remove_handler, Reply}</CODE></STRONG><BR>
<STRONG><CODE>Reply = term()</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Args1 = Args2 = term()</CODE></STRONG><BR>
<STRONG><CODE>Handler2 = Module2 | {Module2,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module2 = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Whenever an event manager receives a request sent using
         <CODE>gen_event:call/3,4</CODE>, this function is called for
         the specified event handler to handle the request.
<P><CODE>Request</CODE> is the <CODE>Request</CODE> argument of <CODE>call</CODE>.
<P><CODE>State</CODE> is the internal state of the event handler.
<P>The return values are the same as for <CODE>handle_event/2</CODE>
         except they also contain a term <CODE>Reply</CODE> which is the reply
         given back to the client as the return value of <CODE>call</CODE>.
</DIV>

<P><A NAME="Module:handle_info/2"><STRONG><CODE>Module:handle_info(Info, State) -&#62; Result</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Info = term()</CODE></STRONG><BR>
<STRONG><CODE>State = term()</CODE></STRONG><BR>
<STRONG><CODE>Result = {ok,NewState}</CODE></STRONG><BR>
<STRONG><CODE>| {swap_handler,Args1,NewState,Handler2,Args2} |
         remove_handler</CODE></STRONG><BR>
<STRONG><CODE>NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Args1 = Args2 = term()</CODE></STRONG><BR>
<STRONG><CODE>Handler2 = Module2 | {Module2,Id}</CODE></STRONG><BR>
<STRONG><CODE>Module2 = atom()</CODE></STRONG><BR>
<STRONG><CODE>Id = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function is called for each installed event handler when
         an event manager receives any other message than an event or
         a synchronous request (or a system message).
<P><CODE>Info</CODE> is the received message.
<P>See <CODE>Module:handle_event/2</CODE> for a description of State
         and possible return values.
</DIV>

<P><A NAME="Module:terminate/2"><STRONG><CODE>Module:terminate(Arg, State) -&#62; term()</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Arg = Args | {stop,Reason} | stop | remove_handler</CODE></STRONG><BR>
<STRONG><CODE>| {error,{'EXIT',Reason}} | {error,Term}</CODE></STRONG><BR>
<STRONG><CODE>Args = Reason = Term = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Whenever an event handler is deleted from an event manager,
         this function is called. It should be the opposite of
         <CODE>Module:init/1</CODE> and do any necessary cleaning up.
<P>If the event handler is deleted due to a call to
         <CODE>gen_event:delete_handler</CODE>, <CODE>gen_event:swap_handler/3</CODE>
         or <CODE>gen_event:swap_sup_handler/3</CODE>, <CODE>Arg</CODE> is
         the <CODE>Args</CODE> argument of this function call.
<P><CODE>Arg={stop,Reason}</CODE> if the event handler has a supervised
         connection to a process which has terminated with reason
         <CODE>Reason</CODE>.
<P><CODE>Arg=stop</CODE> if the event handler is deleted because
         the event manager is terminating.
<P><CODE>Arg=remove_handler</CODE> if the event handler is deleted because
         another callback function has returned <CODE>remove_handler</CODE> or
         <CODE>{remove_handler,Reply}</CODE>.
<P><CODE>Arg={error,Term}</CODE> if the event handler is deleted because
         a callback function returned an unexpected value <CODE>Term</CODE>,
         or <CODE>Arg={error,{'EXIT',Reason}}</CODE> if a callback function
         failed.
<P><CODE>State</CODE> is the internal state of the event handler.
<P>The function may return any term. If the event handler is
         deleted due to a call to <CODE>gen_event:delete_handler</CODE>,
         the return value of that function will be the return value of this
         function. If the event handler is to be replaced with another event
         handler due to a swap, the return value will be passed to
         the <CODE>init</CODE> function of the new event handler. Otherwise
         the return value is ignored.
</DIV>

<P><A NAME="Module:code_change/3"><STRONG><CODE>Module:code_change(OldVsn, State, Extra) -&#62; {ok, NewState}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>OldVsn = Vsn | {down, Vsn}</CODE></STRONG><BR>
<STRONG><CODE>Vsn = term()</CODE></STRONG><BR>
<STRONG><CODE>State = NewState = term()</CODE></STRONG><BR>
<STRONG><CODE>Extra = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>This function is called for an installed event handler which
         should update its internal state during a release
         upgrade/downgrade, i.e. when the instruction
         <CODE>{update,Module,Change,...}</CODE> where
         <CODE>Change={advanced,Extra}</CODE> is given in the <CODE>.appup</CODE>
         file. See <STRONG>OTP Design Principles</STRONG> for more
         information.
<P>In the case of an upgrade, <CODE>OldVsn</CODE> is <CODE>Vsn</CODE>, and
         in the case of a downgrade, <CODE>OldVsn</CODE> is
         <CODE>{down,Vsn}</CODE>. <CODE>Vsn</CODE> is defined by the <CODE>vsn</CODE>
         attribute(s) of the old version of the callback module
         <CODE>Module</CODE>. If no such attribute is defined, the version
         is the checksum of the BEAM file.
<P><CODE>State</CODE> is the internal state of the event handler.
<P><CODE>Extra</CODE> is passed as-is from the <CODE>{advanced,Extra}</CODE>
         part of the update instruction.
<P>The function should return the updated internal state.
</DIV>

<H3>SEE ALSO</H3>
<DIV CLASS=REFBODY>

<P><A HREF="supervisor.html">supervisor(3)</A>, 
<A HREF="sys.html">sys(3)</A>
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Gunilla Arendt - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>stdlib 1.14.2<BR>
Copyright &copy; 1991-2006
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>