Introduction

Warning: This project is not maintained anymore, it is kept alive just to historical/educational reasons.

libevent is a popular API that provides a mechanism to execute a callback function when a specific event occurs on a file descriptor or after a timeout has been reached. Furthermore, libevent also support callbacks due to signals or regular timeouts.

eventxx is a simple, direct, one-header inline C++ wrapper for libevent. Yes, it's just one header file, so if you want to use it you can just copy the file to your project and you are set (well, you'll need to link to libevent too ;).

It's designed to be as close to use to libevent (without compromising modern C++ programming techniques) and efficient (since all implementation is trivial and inline, theoretically, it imposes no overhead at all) as possible.

Please, visit the eventxx website for the latest version of this documentation.

Download

You can always get the current release from the release directory or grab the most up to date sources from the git repository.

You can also take a look the the eventxx gitweb interface to see the latest changes online or subscribe to its Atom feed to follow the development.

Usage

You probably should read libevent documentation to get started or at least just for reference, although eventxx is pretty simple so you can jump right into the Example section (or the example list) and write a working program without much trouble.

This wrapper was designed to be used just like libevent, but with C++ style syntax sugar (or poison, depends on your point of view ;) and goodies. The main difference to libevent is you always have to instance a eventxx::dispatcher to get an event loop. There is no implicit global event loop. This adds just an extra line of code for single threaded applications and makes things much more simpler, so I hope nobody complains about it ;). See eventxx::dispatcher documentation for more details.

You can use use the same plain functions callbacks libevent use or the other kind of function objects (see Events section for details on event types).

eventxx uses Exceptions to report errors. All functions have exception specifications, so it's easy to find out what to expect. See Exceptions section for more detail.

A timespec abstraction is provided as eventxx::time for convenient argument passing. Even more, it's a timespec itself, with some convenient methods for accessing the attributes with pritier names. And even more, eventxx is such a direct mapping that all eventxx::event's are libevent event structs too, so theoretically you can pass a eventxx::event to libevent C functions without much trouble. eventxx::dispatcher is the only class that is not derived from libevent struct (event_base) because this struct it's not defined on the libevent header (just declared).

Maybe you shouldn't know this implementation details to keep the abstraction, but this is a basic design goal of this wrapper so there is not much chance that this changes in the future (but use this knowledge with care, you have been warned ;).

Example

#include <eventxx>
#include <iostream>
#include <csignal>
 
struct handler
{
        eventxx::dispatcher& d;
        int i;
        handler(eventxx::dispatcher& d): d(d), i(0) {}
        void operator() (int signum, eventxx::type event)
        {
                std::cout << ++i << " interrupts, ";
                if (i < 5) std::cout << "keep going...\n";
                else
                {
                        std::cout << "done!\n";
                        d.exit();
                }
        }
};
 
void timer_handler(int, short, void*)
{
        std::cout << "Press Ctrl-C 5 times to quit.\n";
}
 
int main()
{
        eventxx::dispatcher d;
        handler h(d);
        eventxx::ctimer t(timer_handler);
        eventxx::signal< handler > e(SIGINT, h);
        d.add(t, eventxx::time(1)); // 1 second
        d.add(e);
        d.dispatch();
        return 0;
}

You can see more examples on the test directory of the distribution or on the examples related page.

Status

I think the library is stable now. The library has no support for buffered events yet, but patches are welcome. It doesn't support the HTTP stuff, and probably never will because that has nothing to do with event handling.

libevent had a memory leak before version 1.3b (before 1.2 it didn't even had a way free that memory, from version 1.2 to 1.3a, if you tried to free the memory the program abort() because a failed assertion). Because of that, there is a way to disable the dispatcher destructor (which calls the inexistent/broken event_base_free() function in the broken versions). So if you use a libevent version previous to 1.3b, you have to compile your programs defining the EVENTXX_NO_EVENT_BASE_FREE macro.

If something is broken it would be really easy to fix because eventxx is just a simple wrapper around libevent. So, please try it out, and if you have any problems, drop me an e-mail and and I'll fix it ASAP (or provide a patch and you will be my best friend ;).

If you use this library, please drop me an e-mail with your thoughts, or simply saying "I use it", so I can keep track of how many people really use it.

Author: Leandro Lucarella lluca.nosp@m.x+ev.nosp@m.entxx.nosp@m.@gma.nosp@m.il.co.nosp@m.m

Version: 1.0.1

License: This program is under the BOLA License (see the license website or the LICENSE file itself for more details, it's very short and it basically says it's Public Domain).