µEv | Simple event loop for Linux

• Introduction
• API
  • Create an Event Context
  • Register an Event Watcher
  • Start Event Loop
  • Summary
• Using -luev
• Joystick Example
• Build & Install
• Origin & References

NOTE: Incompatible failure mode changes in v2.0 compared to v1.x!

Introduction

libuEv is a small event loop that wraps the Linux epoll() family of APIs. It is similar to the more established libevent, libev and the venerable Xt(3) event loop. The µ in the name refers to both its limited feature set and the size impact of the library.

Linux APIs supported and wrapped for ease-of-use:

• epoll(2)
• eventfd(2)
• signalfd(2)
• timerfd(2)

Failure mode changes introduced in v2.0 may affect users of v1.x, See the ChangeLog for the full details.

The API documentation is available as a separate document.

Example

Notice how watcher conditions like UEV_ERROR must be handled by each callback. I/O watchers must also check for UEV_HUP. Both errors are usually fatal, libuEv makes sure to stop each watcher before a callback runs, leaving it up to the callback to take appropriate action.

/* Set up a timer watcher to call cb() every other second */
#include <stdio.h>
#include <uev/uev.h>

static void cb(uev_t *w, void *arg, int events)
{
        if (UEV_ERROR == events) {
            puts("Problem with timer, attempting to restart.");
            uev_timer_start(w);
            return;
        }

        puts("Every other second");
}

int main(void)
{
        uev_ctx_t ctx;
        uev_t timer;

        uev_init(&ctx);
        uev_timer_init(&ctx, &timer, cb, NULL, 2 * 1000, 2 * 1000);

        return uev_run(&ctx, 0);
}

Build & Install

libuEv use the GNU configure and build system. To try out the bundled examples, use the --enable-examples switch to the configure script. There is also a limited unit test suite that can be useful to learn how the library works.

./configure
make -j5
make check
sudo make install-strip
sudo ldconfig

The resulting .so library is ~23 kiB.

To build from GIT sources; clone the repository and run the autogen.sh script. This requires GNU automake, autoconf amd libtool to be installed on your system. (If you build from a released tarball you do not need them.)

Origin & References

libuEv is developed and maintained by Joachim Wiberg on GitHub. It is primarily built for and developed on GNU/Linux systems, patches to support the BSD kqueue interface are most welcome.

Originally based on LibUEvent by Flemming Madsen, uEv has since evolved to support all of the Linux epoll() family APIs. It is now more similar to the excellent libev by Mark Lehmann, with some inspiration also from picoev by Oku Kazuho.

Copyright (c) 2012       Flemming Madsen <flemming!madsen()madsensoft!dk>
Copyright (c) 2013-2024  Joachim Wiberg <troglobit()gmail!com>

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

Contributing to the Project

Thank you for considering contributing back to Free Software!

There are a few things we would like you to consider when filing an issue or pull request with this project:

1. If you are filing a bug report or feature request

   Please take the time to check if an issue already has been filed matching your problem

2. What version are you running, have you tried the latest release?

   UNIX distributions often package and test software for their particular brand. If you are using a pre-packaged version, then please file a bug with that distribution instead.

3. Coding Style

   Lines are allowed to be longer than 72 characters these days, there is no enforced max. length.

Tip: Always submit code that follows the style of surrounding code!

The coding style itself is strictly Linux KNF, like GIT it is becoming a de facto standard for C programming

https://www.kernel.org/doc/Documentation/CodingStyle

4. Logical Change Sets

   Changes should be broken down into logical units that add a feature or fix a bug. Keep changes separate from each other and do not mix a bug fix with a whitespace cleanup or a new feature addition.

   This is important not only for readilibity, or for the possibility of maintainers to revert changes, but does also increase your chances of having a change accepted.

5. Commit messages

   Commit messages exist to track why a change was made. Try to be as clear and concise as possible in your commit messages, and always, be proud of your work and set up a proper GIT identity for your commits:

    git config --global user.name "J. Random Hacker"
    git config --global user.email random.j.hacker@example.com
   

   See this helpful guide for how to write simple, readable commit messages, or have at least a look at the below example.

   http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html

Example

Example commit message from the Pro Git online book, notice how git commit -s is used to automatically add a Signed-off-by:

Capitalized, short (50 chars or less) summary

More detailed explanatory text, if necessary.  Wrap it to about 72
characters or so.  In some contexts, the first line is treated as the
subject of an email and the rest of the text as the body.  The blank
line separating the summary from the body is critical (unless you omit
the body entirely); tools like rebase can get confused if you run the
two together.

Write your commit message in the imperative: "Fix bug" and not "Fixed bug"
or "Fixes bug."  This convention matches up with commit messages generated
by commands like git merge and git revert.

Further paragraphs come after blank lines.

- Bullet points are okay, too

- Typically a hyphen or asterisk is used for the bullet, followed by a
  single space, with blank lines in between, but conventions vary here

- Use a hanging indent

Signed-off-by: J. Random Hacker <random.j.hacker@example.com>

Security Policy

Supported Versions

libuEv is a small project, as such we have no possibility to support older versions. The only supported version is the latest released on GitHub:

https://github.com/troglobit/libuev/releases

Reporting a Vulnerability

Contact the project's main author and owner to report and discuss vulnerabilities.