OTP设计原则:Gen_Event 行为

4 Gen_Event 行为

这一章应该与gen_event(3)结合起来看,gen_event(3)对所有接口函数和回调函数都有详细描述. 

4.1 事件处理原则

在OTP中, an event manager is a named object to which events can be sent. An event could be, for example, an error, an alarm or some information that should be logged.

In the event manager, zero, one or several event handlers 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.

An event manager is implemented as a process and each event handler is implemented as a callback module.

The event manager essentially maintains a list of {Module, State} pairs, where each Module is an event handler, and State the internal state of that event handler.

4.2 Example

The callback module for the event handler writing error messages to the terminal could look like:

java 代码
-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.

    

The callback module for the event handler writing error messages to a file could look like:

java 代码
-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).

The code is explained in the next sections.

4.3 Starting an Event Manager

To start an event manager for handling errors, as described in the example above, call the following function:

java 代码
gen_event:start_link({local, error_man})

    

This function spawns and links to a new process, an event manager.

The argument, {local, error_man} specifies the name. In this case, the event manager will be locally registered as error_man.

If the name is omitted, the event manager is not registered. Instead its pid must be used. The name could also be given as {global, Name}, in which case the event manager is registered using global:register_name/2.

gen_event:start_link must be used if the event manager is part of a supervision tree, i.e. is started by a supervisor. There is another function gen_event:start to start a stand-alone event manager, i.e. an event manager which is not part of a supervision tree.

4.4 Adding an Event Handler

Here is an example using the shell on how to start an event manager and add an event handler to it:

1> gen_event:start({local, error_man}).
{ok,<0.31.0>}
2> gen_event:add_handler(error_man, terminal_logger, []).
ok
    

This function sends a message to the event manager registered as error_man, telling it to add the event handler terminal_logger. The event manager will call the callback function terminal_logger:init([]), where the argument [] is the third argument to add_handler. init is expected to return {ok, State}, where State is the internal state fo the event handler.

java 代码
init(_Args) ->
    {ok, []}.

    

Here, init does not need any indata and ignores its argument. Also, for terminal_logger the internal state is not used. For file_logger, the internal state is used to save the open file descriptor.

java 代码
init(_Args) ->
    {ok, Fd} = file:open(File, read),
    {ok, Fd}.

4.5 Notifying About Events

3> gen_event:notify(error_man, no_reply).
***Error*** no_reply
ok
    

error_man is the name of the event manager and no_reply is the event.

The event is made into a message and sent to the event manager. When the event is received, the event manager calls handle_event(Event, State) for each installed event handler, in the same order as they were added. The function is expected to return a tuple {ok, State1}, where State1 is a new value for the state of the event handler.

In terminal_logger:

java 代码

handle_event(ErrorMsg, State) ->
    io:format("***Error*** ~p~n", [ErrorMsg]),
    {ok, State}.


In file_logger:

handle_event(ErrorMsg, Fd) ->
    io:format(Fd, "***Error*** ~p~n", [ErrorMsg]),
    {ok, Fd}.

4.6 Deleting an Event Handler

4> gen_event:delete_handler(error_man, terminal_logger, []).
ok
    

This function sends a message to the event manager registered as error_man, telling it to delete the event handler terminal_logger. The event manager will call the callback function terminal_logger:terminate([], State), where the argument [] is the third argument to delete_handler. terminate should be the opposite of init and do any necessary cleaning up. Its return value is ignored.

For terminal_logger, no cleaning up is necessary:

  
java 代码
terminate(_Args, Fd) ->
    file:close(Fd).

    

For file_logger, the file descriptor opened in init needs to be closed:

java 代码
terminate(_Args, Fd) ->
    file:close(Fd).
    

4.7 Stopping

When an event manager is stopped, it will give each of the installed event handlers the chance to clean up by calling terminate/2, the same way as when deleting a handler.

4.7.1 In a Supervision Tree

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 shutdown strategy set in the supervisor.

4.7.2 Stand-Alone Event Managers

An event manager can also be stopped by calling:

> gen_event:stop(error_man).
ok