Introduction

The Event Dispatcher library is a low level C++ library used to communicate between local and remote services.

For communication, the library supports TCP, UDP (direct and broadcast), Unix pipes.

The event part also supports events from Unix signals and the File System.

Each one of these objects can also be given a timeout date or an elapse time to generate ticks.

Most of the components of the Event Dispatcher library were developed in the libsnapwebsites library. It was detached from that library so we could make use of its powerful features in other projects.

Features

The features in more details:

TCP

The library supports servers and clients using the TCP protocol through a socket.

We also include support for TLS encryption.

UDP

The library supports servers and clients using the UDP protocol through a socket.

The UDP protocol can be used to send one message to a specific destination (like a PING for instance). It also supports the broadcast feature of UDP to send message to a group of listening servers.

Unix Pipes

If you are using the fork() command and still want to communicate efficiently with the child process, you can use Unix Pipes. This is a simple two way (read/write) pipe mechanism which is created by the parent before you create the child.

Just like with TCP and UDP, pipe file descriptors generate events whenever a messsage is sent or room is made available to send another message so the handling of the pipes is also 100% driven.

Unix Signals

Linux offers a way to open a file descriptor which is used to listen for Unix Signals. This feature of the library offers that functionality.

Note that the library automatically blocks the signal. Whenever you receive a signal you are listening to, you will only receive an event and no Unix signal callback gets called.

(As a side note, you should not use this feature to capture signals such as SIGSEGV and SIGILL, such errors should terminate your program anyway.)

File System Changes

Linux supports the SGI library offering a way to listen for changes to the file system. This feature allows you to know whenever a file changes and if required to reload it. For example, you may want to listen on your configuration file(s). On a change, initiate a reload of the file.

The supported events are:

• Change of attributes
• Someone read from the file
• Someone wrote to the file
• Someone created a file
• Someone deleted the file
• Someone accessed the file

The system also tells us when a mount point gets unmounted.

Timers

All the objects include a timer so you can force a wakeup call once in a while and act on it.

You may also create timer specific objects without any other purposes. For example, if you want to run a task once every 5 min., you set a time to send you ticks once every 300 seconds.

Enable/Disable

Once in a while, a connection should be ignored. Although it could be added/removed from the list, that can be tedious, especially when you manage many such connections.

Instead, the library supports a state. When disabled, the object is completely ignored.

Poll

The library uses the poll() command.

This means you are not limited to the low 256 file descriptors which can be very limiting to some applications (like our snapcommunicator which may get thousands of connections.)

Event Loop

The library manages your event loop. It can include any type of file descriptor you can listen to (including connections like the X-Windows file descriptor.)

Download

The source is available on github in our project git.

On Ubuntu, you may want to install it from our Snap! C++ Launchpad PPA. In that case, add the repository this way:

sudo add-apt-repository ppa:snapcpp/ppa
sudo apt-get update

Then install one of the library packages with the install command:

sudo apt-get install eventdispatcher
sudo apt-get install eventdispatcher-dev
sudo apt-get install eventdispatcher-doc

List of currently available Snap! C++ packages.

Support

You got a problem with the library? An idea to improve it? Please post a ticket in the Support area of Github.

Changes

List of changes by version

• 1.0.0 -- moved from libsnapwebsites and broken up in separate files.

Coverage Test Results

Access full page here.

The library has a test suite that covers some of the code, making it a little more likely that it works as expected.