Erlang -- gen_event Behaviour

OTP Design Principles

User's Guide

Version 10.7

- User's Guide
- PDF
- Top

- Expand All
- Contract All

### Chapters

- Overview
  - Top of chapter
  - Supervision Trees
  - Behaviours
  - Applications
  - Releases
  - Release Handling
- gen_server Behaviour
  - Top of chapter
  - Client-Server Principles
  - Example
  - Starting a Gen_Server
  - Synchronous Requests - Call
  - Asynchronous Requests - Cast
  - Stopping
  - Handling Other Messages
- gen_statem Behaviour
  - Top of chapter
  - Event-Driven State Machines
  - When to use gen_statem
  - Callback Module
  - Callback Modes
  - State Callback
  - Transition Actions
  - Event Types and Event Content
  - State Enter Calls
  - Time-Outs
  - Example
  - Starting gen_statem
  - Handling Events
  - State Time-Outs
  - All State Events
  - One State Callback
  - Stopping
  - Event Time-Outs
  - Generic Time-Outs
  - Erlang Timers
  - Postponing Events
  - State Enter Actions
  - Inserted Events
  - Example Revisited
  - Filter the State
  - Complex State
  - Hibernation
- gen_event Behaviour
  - Top of chapter
  - Event Handling Principles
  - Example
  - Starting an Event Manager
  - Adding an Event Handler
  - Notifying about Events
  - Deleting an Event Handler
  - Stopping
  - Handling Other Messages
- Supervisor Behaviour
  - Top of chapter
  - Supervision Principles
  - Example
  - Supervisor Flags
  - Restart Strategy
  - Maximum Restart Intensity
  - Child Specification
  - Starting a Supervisor
  - Adding a Child Process
  - Stopping a Child Process
  - Simplified one_for_one Supervisors
  - Stopping
- sys and proc_lib
  - Top of chapter
  - Simple Debugging
  - Special Processes
  - User-Defined Behaviours
- Applications
  - Top of chapter
  - Application Concept
  - Application Callback Module
  - Application Resource File
  - Directory Structure
  - Application Controller
  - Loading and Unloading Applications
  - Starting and Stopping Applications
  - Configuring an Application
  - Application Start Types
- Included Applications
  - Top of chapter
  - Introduction
  - Specifying Included Applications
  - Synchronizing Processes during Startup
- Distributed Applications
  - Top of chapter
  - Introduction
  - Specifying Distributed Applications
  - Starting and Stopping Distributed Applications
  - Failover
  - Takeover
- Releases
  - Top of chapter
  - Release Concept
  - Release Resource File
  - Generating Boot Scripts
  - Creating a Release Package
  - Directory Structure
- Release Handling
  - Top of chapter
  - Release Handling Principles
  - Requirements
  - Distributed Systems
  - Release Handling Instructions
  - Application Upgrade File
  - Release Upgrade File
  - Installing a Release
  - Updating Application Specifications
- Appup Cookbook
  - Top of chapter
  - Changing a Functional Module
  - Changing a Residence Module
  - Changing a Callback Module
  - Changing Internal State
  - Module Dependencies
  - Changing Code for a Special Process
  - Changing a Supervisor
  - Adding or Deleting a Module
  - Starting or Terminating a Process
  - Adding or Removing an Application
  - Restarting an Application
  - Changing an Application Specification
  - Changing Application Configuration
  - Changing Included Applications
  - Changing Non-Erlang Code
  - Emulator Restart and Upgrade
  - Emulator Upgrade From Pre OTP R15

# 4 gen_event Behaviour

This section is to be read with the gen_event(3) manual page in STDLIB, where all interface functions and callback functions are described in detail.

### 4.1 Event Handling Principles

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

In the event manager, zero, one, or many event handlers are installed. When the event manager is notified about an event, the event is 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 is to be saved to a file as well, the user adds another event handler that does this. When logging to the 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 is the internal state of that event handler.

### 4.2 Example

The callback module for the event handler writing error messages to the terminal can look as follows:

    -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 can look as follows:

    -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 previous example, call the following function:

    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. The event manager is then locally registered as error_man.

If the name is omitted, the event manager is not registered. Instead its pid must be used. The name can 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, that is, started by a supervisor. There is another function, gen_event:start, to start a standalone event manager, that is, an event manager that is not part of a supervision tree.

### 4.4 Adding an Event Handler

The following example shows how to start an event manager and add an event handler to it by using the shell:

    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 calls 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 of the event handler.

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

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

    init(File) ->
        {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:

    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 calls the callback function terminal_logger:terminate([], State), where the argument [] is the third argument to delete_handler. terminate is to be the opposite of init and do any necessary cleaning up. Its return value is ignored.

For terminal_logger, no cleaning up is necessary:

    terminate(_Args, _State) ->
        ok.

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

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

### 4.7 Stopping

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

#### In a Supervision Tree

If the event manager is part of a supervision tree, no stop function is needed. The event manager is automatically terminated by its supervisor. Exactly how this is done is defined by a shutdown strategy set in the supervisor.

#### Standalone Event Managers

An event manager can also be stopped by calling:

    > gen_event:stop(error_man).
    ok

### 4.8 Handling Other Messages

If the gen_event is to be able to receive other messages than events, the callback function handle_info(Info, StateName, StateData) must be implemented to handle them. Examples of other messages are exit messages, if the gen_event is linked to other processes (than the supervisor) and trapping exit signals.

    handle_info({'EXIT', Pid, Reason}, State) ->
        ..code to handle exits here..
        {ok, NewState}.

The code_change method must also be implemented.

    code_change(OldVsn, State, Extra) ->
        ..code to convert state (and more) during code change
        {ok, NewState}