The R13B03 release.OTP_R13B03

1 files changed, 221 insertions, 0 deletions

diff --git a/system/doc/design_principles/events.xml b/system/doc/design_principles/events.xml
new file mode 100644
index 0000000000..5579f1e459
--- /dev/null
+++ b/system/doc/design_principles/events.xml
@@ -0,0 +1,221 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+  <header>
+    <copyright>
+      <year>1997</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 Behaviour</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+    <file>events.xml</file>
+  </header>
+  <marker id="gen_event"></marker>
+  <p>This chapter should be read in conjunction with
+    <c>gen_event(3)</c>, where all interface functions and callback
+    functions are described in detail.</p>
+
+  <section>
+    <title>Event Handling Principles</title>
+    <p>In OTP, an <em>event manager</em> is a named object to which
+      events can be sent. An <em>event</em> could be, for example,
+      an error, an alarm or some information that should be logged.</p>
+    <p>In the event manager, zero, one or several <em>event handlers</em> are installed. When the event manager is notified
+      about an event, the event will be processed by all the installed
+      event handlers. For example, an event manager for handling errors
+      can by default have a handler installed which writes error
+      messages to the terminal. If the error messages during a certain
+      period should be saved to a file as well, the user adds another
+      event handler which does this. When logging to file is no longer
+      necessary, this event handler is deleted.</p>
+    <p>An event manager is implemented as a process and each event
+      handler is implemented as a callback module.</p>
+    <p>The event manager essentially maintains a list of
+      <c>{Module, State}</c> pairs, where each <c>Module</c> is an
+      event handler, and <c>State</c> the internal state of that event
+      handler.</p>
+  </section>
+
+  <section>
+    <title>Example</title>
+    <p>The callback module for the event handler writing error messages
+      to the terminal could look like:</p>
+    <code type="none">
+-module(terminal_logger).
+-behaviour(gen_event).
+
+-export([init/1, handle_event/2, terminate/2]).
+
+init(_Args) ->
+    {ok, []}.
+
+handle_event(ErrorMsg, State) ->
+    io:format("***Error*** ~p~n", [ErrorMsg]),
+    {ok, State}.
+
+terminate(_Args, _State) ->
+    ok.</code>
+    <p>The callback module for the event handler writing error messages
+      to a file could look like:</p>
+    <code type="none">
+-module(file_logger).
+-behaviour(gen_event).
+
+-export([init/1, handle_event/2, terminate/2]).
+
+init(File) ->
+    {ok, Fd} = file:open(File, read),
+    {ok, Fd}.
+
+handle_event(ErrorMsg, Fd) ->
+    io:format(Fd, "***Error*** ~p~n", [ErrorMsg]),
+    {ok, Fd}.
+
+terminate(_Args, Fd) ->
+    file:close(Fd).</code>
+    <p>The code is explained in the next sections.</p>
+  </section>
+
+  <section>
+    <marker id="mgr"></marker>
+    <title>Starting an Event Manager</title>
+    <p>To start an event manager for handling errors, as described in
+      the example above, call the following function:</p>
+    <code type="none">
+gen_event:start_link({local, error_man})</code>
+    <p>This function spawns and links to a new process, an event
+      manager.</p>
+    <p>The argument, <c>{local, error_man}</c> specifies the name. In
+      this case, the event manager will be locally registered as
+      <c>error_man</c>.</p>
+    <p>If the name is omitted, the event manager is not registered.
+      Instead its pid must be used. The name could also be given
+      as <c>{global, Name}</c>, in which case the event manager is
+      registered using <c>global:register_name/2</c>.</p>
+    <p><c>gen_event:start_link</c> must be used if the event manager is
+      part of a supervision tree, i.e. is started by a supervisor.
+      There is another function <c>gen_event:start</c> to start a
+      stand-alone event manager, i.e. an event manager which is not
+      part of a supervision tree.</p>
+  </section>
+
+  <section>
+    <title>Adding an Event Handler</title>
+    <p>Here is an example using the shell on how to start an event
+      manager and add an event handler to it:</p>
+    <pre>
+1> <input>gen_event:start({local, error_man}).</input>
+{ok,&lt;0.31.0>}
+2> <input>gen_event:add_handler(error_man, terminal_logger, []).</input>
+ok</pre>
+    <p>This function sends a message to the event manager registered as
+      <c>error_man</c>, telling it to add the event handler
+      <c>terminal_logger</c>. The event manager will call the callback
+      function <c>terminal_logger:init([])</c>, where the argument []
+      is the third argument to <c>add_handler</c>. <c>init</c> is
+      expected to return <c>{ok, State}</c>, where <c>State</c> is
+      the internal state of the event handler.</p>
+    <code type="none">
+init(_Args) ->
+    {ok, []}.</code>
+    <p>Here, <c>init</c> does not need any input data and ignores its
+      argument. Also, for <c>terminal_logger</c> the internal state is
+      not used. For <c>file_logger</c>, the internal state is used
+      to save the open file descriptor.</p>
+    <code type="none">
+init(File) ->
+    {ok, Fd} = file:open(File, read),
+    {ok, Fd}.</code>
+  </section>
+
+  <section>
+    <title>Notifying About Events</title>
+    <pre>
+3> <input>gen_event:notify(error_man, no_reply).</input>
+***Error*** no_reply
+ok</pre>
+    <p><c>error_man</c> is the name of the event manager and
+      <c>no_reply</c> is the event.</p>
+    <p>The event is made into a message and sent to the event manager.
+      When the event is received, the event manager calls
+      <c>handle_event(Event, State)</c> for each installed event
+      handler, in the same order as they were added. The function is
+      expected to return a tuple <c>{ok, State1}</c>, where
+      <c>State1</c> is a new value for the state of the event handler.</p>
+    <p>In <c>terminal_logger</c>:</p>
+    <code type="none">
+handle_event(ErrorMsg, State) ->
+    io:format("***Error*** ~p~n", [ErrorMsg]),
+    {ok, State}.</code>
+    <p>In <c>file_logger</c>:</p>
+    <code type="none">
+handle_event(ErrorMsg, Fd) ->
+    io:format(Fd, "***Error*** ~p~n", [ErrorMsg]),
+    {ok, Fd}.</code>
+  </section>
+
+  <section>
+    <title>Deleting an Event Handler</title>
+    <pre>
+4> <input>gen_event:delete_handler(error_man, terminal_logger, []).</input>
+ok</pre>
+    <p>This function sends a message to the event manager registered as
+      <c>error_man</c>, telling it to delete the event handler
+      <c>terminal_logger</c>. The event manager will call the callback
+      function <c>terminal_logger:terminate([], State)</c>, where
+      the argument [] is the third argument to <c>delete_handler</c>.
+      <c>terminate</c> should be the opposite of <c>init</c> and do any
+      necessary cleaning up. Its return value is ignored.</p>
+    <p>For <c>terminal_logger</c>, no cleaning up is necessary:</p>
+    <code type="none">
+terminate(_Args, _State) ->
+    ok.</code>
+    <p>For <c>file_logger</c>, the file descriptor opened in <c>init</c>
+      needs to be closed:</p>
+    <code type="none">
+terminate(_Args, Fd) ->
+    file:close(Fd).</code>
+  </section>
+
+  <section>
+    <title>Stopping</title>
+    <p>When an event manager is stopped, it will give each of
+      the installed event handlers the chance to clean up by calling
+      <c>terminate/2</c>, the same way as when deleting a handler.</p>
+
+    <section>
+      <title>In a Supervision Tree</title>
+      <p>If the event manager is part of a supervision tree, no stop
+        function is needed. The event manager will automatically be
+        terminated by its supervisor. Exactly how this is done is
+        defined by a <seealso marker="sup_princ#shutdown">shutdown strategy</seealso> set in the supervisor.</p>
+    </section>
+
+    <section>
+      <title>Stand-Alone Event Managers</title>
+      <p>An event manager can also be stopped by calling:</p>
+      <pre>
+> <input>gen_event:stop(error_man).</input>
+ok</pre>
+    </section>
+  </section>
+</chapter>
+