diff options
Diffstat (limited to 'lib/stdlib/doc/src/gen_event.xml')
| -rw-r--r-- | lib/stdlib/doc/src/gen_event.xml | 641 |
1 files changed, 641 insertions, 0 deletions
diff --git a/lib/stdlib/doc/src/gen_event.xml b/lib/stdlib/doc/src/gen_event.xml new file mode 100644 index 0000000000..df09294de6 --- /dev/null +++ b/lib/stdlib/doc/src/gen_event.xml @@ -0,0 +1,641 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1996</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + </legalnotice> + + <title>gen_event</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>gen_event</module> + <modulesummary>Generic Event Handling Behaviour</modulesummary> + <description> + <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> + <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 <em>OTP Design Principles</em> for more information.</p> + <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:</p> + <pre> +gen_event module Callback module +---------------- --------------- +gen_event:start_link -----> - + +gen_event:add_handler +gen_event:add_sup_handler -----> Module:init/1 + +gen_event:notify +gen_event:sync_notify -----> Module:handle_event/2 + +gen_event:call -----> Module:handle_call/2 + +- -----> Module:handle_info/2 + +gen_event:delete_handler -----> Module:terminate/2 + +gen_event:swap_handler +gen_event:swap_sup_handler -----> Module1:terminate/2 + Module2:init/1 + +gen_event:which_handlers -----> - + +gen_event:stop -----> Module:terminate/2 + +- -----> 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 <c>gen_event</c> is more tolerant of callback + module errors than the other behaviours. If a callback function for + an installed event handler fails with <c>Reason</c>, or returns a + bad value <c>Term</c>, the event manager will not fail. It will delete + the event handler by calling the callback function + <c>Module:terminate/2</c> (see below), giving as argument + <c>{error,{'EXIT',Reason}}</c> or <c>{error,Term}</c>, respectively. + No other event handler will be affected.</p> + <p>A gen_event process handles system messages as documented in + <seealso marker="sys">sys(3)</seealso>. The <c>sys</c> module + can be used for debugging an event manager.</p> + <p>Note that an event manager <em>does</em> trap exit signals + automatically.</p> + <p>The gen_event process can go into hibernation + (see <seealso marker="erts:erlang#erlang:hibernate/3">erlang(3)</seealso>) if a callback + function in a handler module specifies <c>'hibernate'</c> in its return value. + This might be useful if the server is expected to be idle for a long + time. However this feature should be used with care as hibernation + implies at least two garbage collections (when hibernating and + shortly after waking up) and is not something you'd want to do + between each event handled by a busy event manager.</p> + + <p>It's also worth noting that when multiple event handlers are + invoked, it's sufficient that one single event handler returns a + <c>'hibernate'</c> request for the whole event manager to go into + hibernation.</p> + + <p>Unless otherwise stated, all functions in this module fail if + the specified event manager does not exist or if bad arguments are + given.</p> + </description> + <funcs> + <func> + <name>start_link() -> Result</name> + <name>start_link(EventMgrName) -> Result</name> + <fsummary>Create a generic event manager process in a supervision tree.</fsummary> + <type> + <v>EventMgrName = {local,Name} | {global,Name}</v> + <v> Name = atom()</v> + <v>Result = {ok,Pid} | {error,{already_started,Pid}}</v> + <v> Pid = pid()</v> + </type> + <desc> + <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> + <p>If <c>EventMgrName={local,Name}</c>, the event manager is + registered locally as <c>Name</c> using <c>register/2</c>. + If <c>EventMgrName={global,Name}</c>, the event manager is + registered globally as <c>Name</c> using + <c>global:register_name/2</c>. If no name is provided, + the event manager is not registered.</p> + <p>If the event manager is successfully created the function + returns <c>{ok,Pid}</c>, where <c>Pid</c> is the pid of + the event manager. If there already exists a process with + the specified <c>EventMgrName</c> the function returns + <c>{error,{already_started,Pid}}</c>, where <c>Pid</c> is + the pid of that process.</p> + </desc> + </func> + <func> + <name>start() -> Result</name> + <name>start(EventMgrName) -> Result</name> + <fsummary>Create a stand-alone event manager process.</fsummary> + <type> + <v>EventMgrName = {local,Name} | {global,Name}</v> + <v> Name = atom()</v> + <v>Result = {ok,Pid} | {error,{already_started,Pid}}</v> + <v> Pid = pid()</v> + </type> + <desc> + <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> + <p>See <c>start_link/0,1</c> for a description of arguments and + return values.</p> + </desc> + </func> + <func> + <name>add_handler(EventMgrRef, Handler, Args) -> Result</name> + <fsummary>Add an event handler to a generic event manager.</fsummary> + <type> + <v>EventMgr = Name | {Name,Node} | {global,Name} | pid()</v> + <v> Name = Node = atom()</v> + <v>Handler = Module | {Module,Id}</v> + <v> Module = atom()</v> + <v> Id = term()</v> + <v>Args = term()</v> + <v>Result = ok | {'EXIT',Reason} | term()</v> + <v> Reason = term()</v> + </type> + <desc> + <p>Adds a new event handler to the event manager <c>EventMgrRef</c>. + The event manager will call <c>Module:init/1</c> to initiate + the event handler and its internal state.</p> + <p><c>EventMgrRef</c> can be:</p> + <list type="bulleted"> + <item>the pid,</item> + <item><c>Name</c>, if the event manager is locally registered,</item> + <item><c>{Name,Node}</c>, if the event manager is locally + registered at another node, or</item> + <item><c>{global,Name}</c>, if the event manager is globally + registered.</item> + </list> + <p><c>Handler</c> is the name of the callback module <c>Module</c> or + a tuple <c>{Module,Id}</c>, where <c>Id</c> is any term. + The <c>{Module,Id}</c> representation makes it possible to + identify a specific event handler when there are several event + handlers using the same callback module.</p> + <p><c>Args</c> is an arbitrary term which is passed as the argument + to <c>Module:init/1</c>.</p> + <p>If <c>Module:init/1</c> returns a correct value, the event + manager adds the event handler and this function returns + <c>ok</c>. If <c>Module:init/1</c> fails with <c>Reason</c> or + returns an unexpected value <c>Term</c>, the event handler is + ignored and this function returns <c>{'EXIT',Reason}</c> or + <c>Term</c>, respectively.</p> + </desc> + </func> + <func> + <name>add_sup_handler(EventMgrRef, Handler, Args) -> Result</name> + <fsummary>Add a supervised event handler to a generic event manager.</fsummary> + <type> + <v>EventMgr = Name | {Name,Node} | {global,Name} | pid()</v> + <v> Name = Node = atom()</v> + <v>Handler = Module | {Module,Id}</v> + <v> Module = atom()</v> + <v> Id = term()</v> + <v>Args = term()</v> + <v>Result = ok | {'EXIT',Reason} | term()</v> + <v> Reason = term()</v> + </type> + <desc> + <p>Adds a new event handler in the same way as <c>add_handler/3</c> + but will also supervise the connection between the event handler + and the calling process.</p> + <list type="bulleted"> + <item>If the calling process later terminates with <c>Reason</c>, + the event manager will delete the event handler by calling + <c>Module:terminate/2</c> with <c>{stop,Reason}</c> as argument.</item> + <item> + <p>If the event handler later is deleted, the event manager + sends a message<c>{gen_event_EXIT,Handler,Reason}</c> to + the calling process. <c>Reason</c> is one of the following:</p> + <list type="bulleted"> + <item><c>normal</c>, if the event handler has been removed due to a + call to <c>delete_handler/3</c>, or <c>remove_handler</c> + has been returned by a callback function (see below).</item> + <item><c>shutdown</c>, if the event handler has been removed + because the event manager is terminating.</item> + <item><c>{swapped,NewHandler,Pid}</c>, if the process <c>Pid</c> + has replaced the event handler with another event handler + <c>NewHandler</c> using a call to <c>swap_handler/3</c> or + <c>swap_sup_handler/3</c>.</item> + <item>a term, if the event handler is removed due to an error. + Which term depends on the error.</item> + </list> + </item> + </list> + <p>See <c>add_handler/3</c> for a description of the arguments + and return values.</p> + </desc> + </func> + <func> + <name>notify(EventMgrRef, Event) -> ok</name> + <name>sync_notify(EventMgrRef, Event) -> ok</name> + <fsummary>Notify an event manager about an event.</fsummary> + <type> + <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v> Name = Node = atom()</v> + <v>Event = term()</v> + </type> + <desc> + <p>Sends an event notification to the event manager + <c>EventMgrRef</c>. The event manager will call + <c>Module:handle_event/2</c> for each installed event handler to + handle the event.</p> + <p><c>notify</c> is asynchronous and will return immediately after + the event notification has been sent. <c>sync_notify</c> is + synchronous in the sense that it will return <c>ok</c> after + the event has been handled by all event handlers.</p> + <p>See <c>add_handler/3</c> for a description of <c>EventMgrRef</c>.</p> + <p><c>Event</c> is an arbitrary term which is passed as one of + the arguments to <c>Module:handle_event/2</c>.</p> + <p><c>notify</c> will not fail even if the specified event manager + does not exist, unless it is specified as <c>Name</c>.</p> + </desc> + </func> + <func> + <name>call(EventMgrRef, Handler, Request) -> Result</name> + <name>call(EventMgrRef, Handler, Request, Timeout) -> Result</name> + <fsummary>Make a synchronous call to a generic event manager.</fsummary> + <type> + <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v> Name = Node = atom()</v> + <v>Handler = Module | {Module,Id}</v> + <v> Module = atom()</v> + <v> Id = term()</v> + <v>Request = term()</v> + <v>Timeout = int()>0 | infinity</v> + <v>Result = Reply | {error,Error}</v> + <v> Reply = term()</v> + <v> Error = bad_module | {'EXIT',Reason} | term()</v> + <v> Reason = term()</v> + </type> + <desc> + <p>Makes a synchronous call to the event handler <c>Handler</c> + installed in the event manager <c>EventMgrRef</c> by sending a + request and waiting until a reply arrives or a timeout occurs. + The event manager will call <c>Module:handle_call/2</c> to handle + the request.</p> + <p>See <c>add_handler/3</c> for a description of <c>EventMgrRef</c> + and <c>Handler</c>.</p> + <p><c>Request</c> is an arbitrary term which is passed as one of + the arguments to <c>Module:handle_call/2</c>.</p> + <p><c>Timeout</c> is an integer greater than zero which specifies + how many milliseconds to wait for a reply, or the atom + <c>infinity</c> to wait indefinitely. Default value is 5000. + If no reply is received within the specified time, the function + call fails.</p> + <p>The return value <c>Reply</c> is defined in the return value of + <c>Module:handle_call/2</c>. If the specified event handler is not + installed, the function returns <c>{error,bad_module}</c>. If + the callback function fails with <c>Reason</c> or returns an + unexpected value <c>Term</c>, this function returns + <c>{error,{'EXIT',Reason}}</c> or <c>{error,Term}</c>, + respectively.</p> + </desc> + </func> + <func> + <name>delete_handler(EventMgrRef, Handler, Args) -> Result</name> + <fsummary>Delete an event handler from a generic event manager.</fsummary> + <type> + <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v> Name = Node = atom()</v> + <v>Handler = Module | {Module,Id}</v> + <v> Module = atom()</v> + <v> Id = term()</v> + <v>Args = term()</v> + <v>Result = term() | {error,module_not_found} | {'EXIT',Reason}</v> + <v> Reason = term()</v> + </type> + <desc> + <p>Deletes an event handler from the event manager + <c>EventMgrRef</c>. The event manager will call + <c>Module:terminate/2</c> to terminate the event handler.</p> + <p>See <c>add_handler/3</c> for a description of <c>EventMgrRef</c> + and <c>Handler</c>.</p> + <p><c>Args</c> is an arbitrary term which is passed as one of + the arguments to <c>Module:terminate/2</c>.</p> + <p>The return value is the return value of <c>Module:terminate/2</c>. + If the specified event handler is not installed, the function + returns <c>{error,module_not_found}</c>. If the callback function + fails with <c>Reason</c>, the function returns + <c>{'EXIT',Reason}</c>.</p> + </desc> + </func> + <func> + <name>swap_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result</name> + <fsummary>Replace an event handler in a generic event manager.</fsummary> + <type> + <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v> Name = Node = atom()</v> + <v>Handler1 = Handler2 = Module | {Module,Id}</v> + <v> Module = atom()</v> + <v> Id = term()</v> + <v>Args1 = Args2 = term()</v> + <v>Result = ok | {error,Error}</v> + <v> Error = {'EXIT',Reason} | term()</v> + <v> Reason = term()</v> + </type> + <desc> + <p>Replaces an old event handler with a new event handler in + the event manager <c>EventMgrRef</c>.</p> + <p>See <c>add_handler/3</c> for a description of the arguments.</p> + <p>First the old event handler <c>Handler1</c> is deleted. + The event manager calls <c>Module1:terminate(Args1, ...)</c>, + where <c>Module1</c> is the callback module of <c>Handler1</c>, + and collects the return value.</p> + <p>Then the new event handler <c>Handler2</c> is added and initiated + by calling <c>Module2:init({Args2,Term})</c>, where <c>Module2</c> + is the callback module of <c>Handler2</c> and <c>Term</c> + the return value of <c>Module1:terminate/2</c>. This makes it + possible to transfer information from <c>Handler1</c> to + <c>Handler2</c>.</p> + <p>The new handler will be added even if the the specified old event + handler is not installed in which case <c>Term=error</c>, or if + <c>Module1:terminate/2</c> fails with <c>Reason</c> in which case + <c>Term={'EXIT',Reason}</c>. + The old handler will be deleted even if <c>Module2:init/1</c> + fails.</p> + <p>If there was a supervised connection between <c>Handler1</c> and + a process <c>Pid</c>, there will be a supervised connection + between <c>Handler2</c> and <c>Pid</c> instead.</p> + <p>If <c>Module2:init/1</c> returns a correct value, this function + returns <c>ok</c>. If <c>Module2:init/1</c> fails with + <c>Reason</c> or returns an unexpected value <c>Term</c>, this + this function returns <c>{error,{'EXIT',Reason}}</c> or + <c>{error,Term}</c>, respectively.</p> + </desc> + </func> + <func> + <name>swap_sup_handler(EventMgrRef, {Handler1,Args1}, {Handler2,Args2}) -> Result</name> + <fsummary>Replace an event handler in a generic event manager.</fsummary> + <type> + <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v> Name = Node = atom()</v> + <v>Handler1 = Handler 2 = Module | {Module,Id}</v> + <v> Module = atom()</v> + <v> Id = term()</v> + <v>Args1 = Args2 = term()</v> + <v>Result = ok | {error,Error}</v> + <v> Error = {'EXIT',Reason} | term()</v> + <v> Reason = term()</v> + </type> + <desc> + <p>Replaces an event handler in the event manager <c>EventMgrRef</c> + in the same way as <c>swap_handler/3</c> but will also supervise + the connection between <c>Handler2</c> and the calling process.</p> + <p>See <c>swap_handler/3</c> for a description of the arguments + and return values.</p> + </desc> + </func> + <func> + <name>which_handlers(EventMgrRef) -> [Handler]</name> + <fsummary>Return all event handlers installed in a generic event manager.</fsummary> + <type> + <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v> Name = Node = atom()</v> + <v>Handler = Module | {Module,Id}</v> + <v> Module = atom()</v> + <v> Id = term()</v> + </type> + <desc> + <p>Returns a list of all event handlers installed in the event + manager <c>EventMgrRef</c>.</p> + <p>See <c>add_handler/3</c> for a description of <c>EventMgrRef</c> + and <c>Handler</c>.</p> + </desc> + </func> + <func> + <name>stop(EventMgrRef) -> ok</name> + <fsummary>Terminate a generic event manager.</fsummary> + <type> + <v>EventMgrRef = Name | {Name,Node} | {global,Name} | pid()</v> + <v>Name = Node = atom()</v> + </type> + <desc> + <p>Terminates the event manager <c>EventMgrRef</c>. Before + terminating, the event manager will call + <c>Module:terminate(stop,...)</c> for each installed event + handler.</p> + <p>See <c>add_handler/3</c> for a description of the argument.</p> + </desc> + </func> + </funcs> + + <section> + <title>CALLBACK FUNCTIONS</title> + <p>The following functions should be exported from a <c>gen_event</c> + callback module.</p> + </section> + <funcs> + <func> + <name>Module:init(InitArgs) -> {ok,State} | {ok,State,hibernate}</name> + <fsummary>Initialize an event handler.</fsummary> + <type> + <v>InitArgs = Args | {Args,Term}</v> + <v> Args = Term = term()</v> + <v>State = term()</v> + </type> + <desc> + <p>Whenever a new event handler is added to an event manager, + this function is called to initialize the event handler.</p> + <p>If the event handler is added due to a call to + <c>gen_event:add_handler/3</c> or + <c>gen_event:add_sup_handler/3</c>, <c>InitArgs</c> is + the <c>Args</c> argument of these functions.</p> + <p>If the event handler is replacing another event handler due to + a call to <c>gen_event:swap_handler/3</c> or + <c>gen_event:swap_sup_handler/3</c>, or due to a <c>swap</c> + return tuple from one of the other callback functions, + <c>InitArgs</c> is a tuple <c>{Args,Term}</c> where <c>Args</c> is + the argument provided in the function call/return tuple and + <c>Term</c> is the result of terminating the old event handler, + see <c>gen_event:swap_handler/3</c>.</p> + <p>The function should return <c>{ok,State}</c> or <c>{ok,State, hibernate}</c> + where <c>State</c> is the initial internal state of the event handler.</p> + <p>If <c>{ok,State,hibernate}</c> is returned, the event + manager will go into hibernation (by calling <seealso + marker="proc_lib#hibernate/3">proc_lib:hibernate/3</seealso>), + waiting for the next event to occur.</p> + </desc> + </func> + <func> + <name>Module:handle_event(Event, State) -> Result</name> + <fsummary>Handle an event.</fsummary> + <type> + <v>Event = term()</v> + <v>State = term()</v> + <v>Result = {ok,NewState} | {ok,NewState,hibernate} </v> + <v> | {swap_handler,Args1,NewState,Handler2,Args2} | remove_handler</v> + <v> NewState = term()</v> + <v> Args1 = Args2 = term()</v> + <v> Handler2 = Module2 | {Module2,Id}</v> + <v> Module2 = atom()</v> + <v> Id = term()</v> + </type> + <desc> + <p>Whenever an event manager receives an event sent using + <c>gen_event:notify/2</c> or <c>gen_event:sync_notify/2</c>, this + function is called for each installed event handler to handle + the event.</p> + <p><c>Event</c> is the <c>Event</c> argument of + <c>notify</c>/<c>sync_notify</c>.</p> + <p><c>State</c> is the internal state of the event handler.</p> + <p>If the function returns <c>{ok,NewState}</c> or <c>{ok,NewState,hibernate}</c> + the event handler + will remain in the event manager with the possible updated + internal state <c>NewState</c>.</p> + <p>If <c>{ok,NewState,hibernate}</c> is returned, the event + manager will also go into hibernation (by calling <seealso + marker="proc_lib#hibernate/3">proc_lib:hibernate/3</seealso>), + waiting for the next event to occur. It is sufficient that one of the event + handlers return <c>{ok,NewState,hibernate}</c> for the whole event manager + process to hibernate.</p> + <p>If the function returns + <c>{swap_handler,Args1,NewState,Handler2,Args2}</c> the event + handler will be replaced by <c>Handler2</c> by first calling + <c>Module:terminate(Args1,NewState)</c> and then + <c>Module2:init({Args2,Term})</c> where <c>Term</c> is the return + value of <c>Module:terminate/2</c>. + See <c>gen_event:swap_handler/3</c> for more information.</p> + <p>If the function returns <c>remove_handler</c> the event handler + will be deleted by calling + <c>Module:terminate(remove_handler,State)</c>.</p> + </desc> + </func> + <func> + <name>Module:handle_call(Request, State) -> Result</name> + <fsummary>Handle a synchronous request.</fsummary> + <type> + <v>Request = term()</v> + <v>State = term()</v> + <v>Result = {ok,Reply,NewState} | {ok,Reply,NewState,hibernate}</v> + <v> | {swap_handler,Reply,Args1,NewState,Handler2,Args2}</v> + <v> | {remove_handler, Reply}</v> + <v> Reply = term()</v> + <v> NewState = term()</v> + <v> Args1 = Args2 = term()</v> + <v> Handler2 = Module2 | {Module2,Id}</v> + <v> Module2 = atom()</v> + <v> Id = term()</v> + </type> + <desc> + <p>Whenever an event manager receives a request sent using + <c>gen_event:call/3,4</c>, this function is called for + the specified event handler to handle the request.</p> + <p><c>Request</c> is the <c>Request</c> argument of <c>call</c>.</p> + <p><c>State</c> is the internal state of the event handler.</p> + <p>The return values are the same as for <c>handle_event/2</c> + except they also contain a term <c>Reply</c> which is the reply + given back to the client as the return value of <c>call</c>.</p> + </desc> + </func> + <func> + <name>Module:handle_info(Info, State) -> Result</name> + <fsummary>Handle an incoming message.</fsummary> + <type> + <v>Info = term()</v> + <v>State = term()</v> + <v>Result = {ok,NewState} | {ok,NewState,hibernate}</v> + <v> | {swap_handler,Args1,NewState,Handler2,Args2} | remove_handler</v> + <v> NewState = term()</v> + <v> Args1 = Args2 = term()</v> + <v> Handler2 = Module2 | {Module2,Id}</v> + <v> Module2 = atom()</v> + <v> Id = term()</v> + </type> + <desc> + <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> + <p><c>Info</c> is the received message.</p> + <p>See <c>Module:handle_event/2</c> for a description of State + and possible return values.</p> + </desc> + </func> + <func> + <name>Module:terminate(Arg, State) -> term()</name> + <fsummary>Clean up before deletion.</fsummary> + <type> + <v>Arg = Args | {stop,Reason} | stop | remove_handler</v> + <v> | {error,{'EXIT',Reason}} | {error,Term}</v> + <v> Args = Reason = Term = term()</v> + </type> + <desc> + <p>Whenever an event handler is deleted from an event manager, + this function is called. It should be the opposite of + <c>Module:init/1</c> and do any necessary cleaning up.</p> + <p>If the event handler is deleted due to a call to + <c>gen_event:delete_handler</c>, <c>gen_event:swap_handler/3</c> + or <c>gen_event:swap_sup_handler/3</c>, <c>Arg</c> is + the <c>Args</c> argument of this function call.</p> + <p><c>Arg={stop,Reason}</c> if the event handler has a supervised + connection to a process which has terminated with reason + <c>Reason</c>.</p> + <p><c>Arg=stop</c> if the event handler is deleted because + the event manager is terminating.</p> + <p>The event manager will terminate if it is part of a supervision + tree and it is ordered by its supervisor to terminate. + Even if it is <em>not</em> part of a supervision tree, it will + terminate if it receives an <c>'EXIT'</c> message from + its parent.</p> + <p><c>Arg=remove_handler</c> if the event handler is deleted because + another callback function has returned <c>remove_handler</c> or + <c>{remove_handler,Reply}</c>.</p> + <p><c>Arg={error,Term}</c> if the event handler is deleted because + a callback function returned an unexpected value <c>Term</c>, + or <c>Arg={error,{'EXIT',Reason}}</c> if a callback function + failed.</p> + <p><c>State</c> is the internal state of the event handler.</p> + <p>The function may return any term. If the event handler is + deleted due to a call to <c>gen_event:delete_handler</c>, + 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 <c>init</c> function of the new event handler. Otherwise + the return value is ignored.</p> + </desc> + </func> + <func> + <name>Module:code_change(OldVsn, State, Extra) -> {ok, NewState}</name> + <fsummary>Update the internal state during upgrade/downgrade.</fsummary> + <type> + <v>OldVsn = Vsn | {down, Vsn}</v> + <v> Vsn = term()</v> + <v>State = NewState = term()</v> + <v>Extra = term()</v> + </type> + <desc> + <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 + <c>{update,Module,Change,...}</c> where + <c>Change={advanced,Extra}</c> is given in the <c>.appup</c> + file. See <em>OTP Design Principles</em> for more + information.</p> + <p>In the case of an upgrade, <c>OldVsn</c> is <c>Vsn</c>, and + in the case of a downgrade, <c>OldVsn</c> is + <c>{down,Vsn}</c>. <c>Vsn</c> is defined by the <c>vsn</c> + attribute(s) of the old version of the callback module + <c>Module</c>. If no such attribute is defined, the version + is the checksum of the BEAM file.</p> + <p><c>State</c> is the internal state of the event handler.</p> + <p><c>Extra</c> is passed as-is from the <c>{advanced,Extra}</c> + part of the update instruction.</p> + <p>The function should return the updated internal state.</p> + </desc> + </func> + </funcs> + + <section> + <title>SEE ALSO</title> + <p><seealso marker="supervisor">supervisor(3)</seealso>, + <seealso marker="sys">sys(3)</seealso></p> + </section> +</erlref> + |