Thread-safe cross-platform event loop library in C++

Overview

Dasynq

Version 1.2.2

Dasynq is an event loop library similar to libevent, libev and libuv. Like other such libraries, it is crossplatform / portable. Unlike most other such libraries, it is intended to be completely usable in a multi-threaded client program, and it is written in C++; furthermore the API is designed to allow the creation of extremely robust clients, by allowing allocation of resources up front (before they are needed in critical sections). However, it is also designed to be lightweight, and it does not require the use of threads (and so does not require linking against a thread library).

The existing backends include epoll and kqueue, meaning that it works on Linux and various BSDs (at least OpenBSD and FreeBSD) as well as Mac OS X ("macOS" as it is now called). There is also a less efficient backend based on pselect, and an even less efficient backend based on select, meaning that it should also work on nearly all other POSIX-compliant systems (with minor caveats).

Dasynq is distributed under the terms of the Apache License, version 2.0, as found in the LICENSE file.

Dasynq is written in C++11, using POSIX functions and some OS-specific system calls.

See the web site for more information.

Event loops

An event loop library provides a means for waiting on events that occur asynchronously. One good example is network input/output; in a server with multiple client connections, a mechanism is needed to wait until data is available, or until it is possible to write data, to one or more of the current connections (and to be able to identify which connections are ready). Dasynq is a multi-platform, thread-safe C++ library which provides such functionality.

Note that an event loop generally supports managing various different kinds of event. Dasynq can be used for detecting:

  • read/write readiness on sockets, pipes, and certain devices including terminals and serial lines;
  • connections to listening sockets;
  • reception of POSIX signals (such as SIGTERM); and
  • child process status notification (termination etc).

It also supports one-shot and periodic timers, against both a monotonic and adjustable system clock (on systems where this is possible).

Dasynq is fully thread-safe, allowing events to be polled and processed on any thread, unlike nearly every other event loop library (some of which are thread-safe, but require that events be polled from a single thread).

There are some limitations on the use the Dasynq API in a multi-threaded application. However, when used in a single-thread application, the API is just about as straight-forward as the API of most other event loop libraries.

Dasynq is also intended to allow development of extremely robust client applications. Where possible, it allows pre-allocation of resources to prevent allocation failures from occurring at inopportune moments during program execution.

Using Dasynq

See doc/USAGE.md for a quick guide on how to use the Dasynq API. A full reference manual can be found in the doc/html folder of the repository / source bundle, or online.

GNU make is required to run the test suite / automated install, or you can try the contributed meson-based build.

To build with GNU make:

Find or create an appropriate makefile in the makefiles directory and edit it to your liking. Either copy/link it to "Makefile" in the root of the source tree, or supply it via the -f argument to the make (or gmake) command. Use the check target to run the test suite, or install to install the library. The DESTDIR variable can be used to install to an alternative root (for packaging purposes etc).

make -f makefiles/Makefile.linux  check
make -f makefiles/Makefile.linux  install  DESTDIR=/tmp/dasynq

On OpenBSD, you must install "eg++" or llvm; the g++ from the base system is too old (4.2 in OpenBSD 6.1; 4.9+ is required). The existing makefile sample (Makefile.openbsd) has appropriate settings.

Linux, OpenBSD, FreeBSD and MacOS are supported "out of the box". For other systems you may need to edit the dasynq-config.h file (see instructions within). For full functionality either epoll or kqueue are required; in many BSD variants it may be possible to build by defining DASYNQ_HAVE_KQUEUE to 1. If epoll and kqueue are not available, Dasynq will fall back to using a pselect-based backend (or a plain select-based backend on some systems which don't have pselect).

After installation, you can use "pkg-config" to find the appropriate flags to compile against Dasynq, assuming you have pkg-config installed:

pkg-config --cflags dasynq
pkg-config --libs dasynq

There is also CMake support. You can add the following to your CMakeLists.txt file:

find_package(Dasynq 1.2.1)

# The "old way". Not sexy, but works without hitches.
#target_include_directories(testapp PRIVATE "${DASYNQ_INCLUDE_DIRS}")
#target_link_libraries(testapp PRIVATE ${DASYNQ_LINK_LIBS}")

# The "new way". Supposedly sexier, but harder to use properly:
target_link_libraries(yourapp
    PRIVATE Dasynq::Dasynq)

# Problematically, the "new way" adds the Dasynq include directory to the
# *system header* include path. On some platforms this may cause problems.
# You can prevent that with the following (this affects *all* imports for
# the 'yourapp' target):
set_target_properties(yourapp PROPERTIES
    NO_SYSTEM_FROM_IMPORTED true
)

It is also possible to simply copy the Dasynq headers directly into your own project.

You might also like...
Read-Compile-Run-Loop: tiny and powerful interactive C++ compiler (REPL)

Read-Compile-Run-Loop: tiny and powerful interactive C++ compiler (REPL) RCRL is a tiny engine for interactive C++ compilation and execution (implemen

Cppev is a C++ event driven library

Cppev is a C++ event driven library. Architecture Nonblock IO Support disk-file / pipe / fifo / socket. Support socket protocol-type tcp / udp, protoc

A cross platform shader language with multi-threaded offline compilation or platform shader source code generation
A cross platform shader language with multi-threaded offline compilation or platform shader source code generation

A cross platform shader language with multi-threaded offline compilation or platform shader source code generation. Output json reflection info and c++ header with your shaders structs, fx-like techniques and compile time branch evaluation via (uber-shader) "permutations".

Evasive shellcode loader for bypassing event-based injection detection (PoC)
Evasive shellcode loader for bypassing event-based injection detection (PoC)

(cleaned up version here: https://github.com/xinbailu/DripLoader-Ops) DripLoader (PoC) Evasive shellcode loader for bypassing event-based injection de

Team hashcat event writeups and tools

Team hashcat event writeups and tools We're a group of people participating in the yearly repeating password cracking contests. Achievements Competiti

Project in the field of Advanced Programming Techniques by prof. Brian Kernighan, inspired by real event that made Ken Thompson invent grep command

ed_to_grep Project in the field of Advanced Programming Techniques by prof. Brian Kernighan, inspired by real event that made Ken Thompson invent grep

ROS1 and ROS2 messages for event based image sensors

ROS package with array messages for event based cameras This package has definitions for messages created by event based sensors. The events are kept

Realtime Micro Kernel -- Event-driven Run-to-Completion RTOS with Active Objects, Timed Events, Memory Pools, and Message Queues

Realtime Micro Kernel Features Active Objects Message queues Variable sized, custom messages Periodic and single timed events Memory pools Supported P

Evasive shellcode loader for bypassing event-based injection detection (PoC)
Evasive shellcode loader for bypassing event-based injection detection (PoC)

DripLoader (PoC) Evasive shellcode loader for bypassing event-based injection detection, without necessarily suppressing event collection. The project

Comments
  • Modernize dasynq

    Modernize dasynq

    Hi Davin.

    This PR tries to standardize and modernize the library by using Meson, CI and clang-tidy. The examples are working too with Meson. Makefiles are working in my system for checking and installing dasynq.

    • [x] move headers in include and include/dasynq
    • [x] fixed include guars
    • [x] use modern c++ headers
    • [ ] add documentation about Meson build
    • [x] test CI builds

    Waiting for your feedback :)

    opened by concatime 16
  • Support for Windows

    Support for Windows

    Hello!

    I am searching for a more modern alternative to the available C-based event loop libraries, and dasynq looks very promising. I'm particularly impressed by the clean code and excellent documentation!

    It is mentioned in the documentation that dasynq is cross-platform, and as such I was hoping that this library may be used on Windows as well. I am however noticing that there is a hard dependency on the unistd.h header, which is unavailable on the Windows platform. Digging a little deeper, the functions used from this header have mostly to do with file descriptors, for which WinAPI alternatives might possibly be employed as well.

    Are there any plans to have dasynq support the Windows platform in the near future, or could some pointers be given of how to go about doing this manually?

    Kind regards, Maurits

    opened by mhjlam 2
  • Documentation: be more clear on limitation of only adding watchers once to one event loop

    Documentation: be more clear on limitation of only adding watchers once to one event loop

    You can only add a watcher to one loop (which is explicitly stated in the documentation), and you can only add it once (which isn't so clear). The documentation should be improved to make this more explicit.

    opened by davmac314 1
Releases(v1.2.2)
  • v1.2.2(Sep 6, 2021)

    This version includes a fix for a crash/memory leak that could happen when memory was (already) exhausted.

    It also uses a new directory structure. This should not affect any existing users. However it is now possible to install Dasynq so the main header, dasynq.h, can be included without requiring any additional compiler flags (i.e. by installing it directly in /usr/include). The ancillary headers are now installed into a subdirectory relative to the main header.

    Source code(tar.gz)
    Source code(zip)
    dasynq-1.2.2.tar.xz(92.55 KB)
  • v1.2.1(Jan 17, 2021)

    This version fixes a bug which triggered when an event loop was constructed with delayed initialisation and then never initialised before being destroyed. On systems using POSIX timers (such as FreeBSD), this could cause a crash.

    On Linux, eventfd is used as the mechanism to signal an event loop in another thread, rather than a pipe. This uses one less file descriptor and is more efficient generally.

    Some minor packaging issues have been resolved.

    Source code(tar.gz)
    Source code(zip)
  • v1.2.0(Jan 7, 2021)

    This version includes important bugfixes, including cases where the wrong exception type was thrown for certain errors with some event loop backends. Additionally, it fixes compilation issues with newer compilers.

    New feature: delayed event loop initialisation. An event loop can be constructed via a noexcept constructor and initialised later via an init() function. See the documentation for details.

    Source code(tar.gz)
    Source code(zip)
  • v1.1.7(Dec 22, 2019)

  • v1.1.6(May 23, 2019)

  • v1.1.5(Sep 14, 2018)

    This release just removes some constructs which technically provoke undefined behaviour, includes a tiny performance/memory use optimisation, and a little bit of refactoring.

    Source code(tar.gz)
    Source code(zip)
  • v1.1.4(Apr 2, 2018)

    This is a minor release with some fixes/updates to documentation, and the lambda-based "add_timer" function (previously undocumented) now takes const timespec & arguments (which allows using time_val values).

    • document the pre-existing "add_timer() with lambda" function
    • change "add_timer()" (with lambda) to accept const timespec & arguments (previously the parameter types were non-const).
    • fix broken timer example in introduction (USAGE.md)
    • various internal changes.
    Source code(tar.gz)
    Source code(zip)
    dasynq-1.1.4.tar.xz(85.00 KB)
  • v1.1.3(Mar 8, 2018)

    This is primarily a bugfix release, but includes CMake support files (installed alongside the library with "make install"). Note that CMake is not required to build.

    • fix timers not working on non-Linux systems
    • Includes CMake files (makes it easier for projects using CMake to use Dasynq)
    • build fixes for platforms without kqueue or epoll
    • install fixes for BSDs
    Source code(tar.gz)
    Source code(zip)
  • v1.1.2(Feb 9, 2018)

  • v1.1.1(Feb 9, 2018)

    This release fixes a bug which prevented "emulated" fd watches from working properly. It also includes a workaround for a MacOS kernel bug which prevented signals from being reliably detected using the kqueue backend on that platform.

    Source code(tar.gz)
    Source code(zip)
  • v1.1.0(Jan 30, 2018)

    This release includes bug fixes for multi-thread event loops using the kqueue backend, and also adds a new backend which uses pselect(2). Since pselect is mandated by POSIX this means Dasynq should work on nearly all mostly-POSIX-compliant systems.

    (Note however that pselect is probably not going to be great performance wise, and suffers from an inherent inability to deal with file descriptors beyond a certain number).

    Source code(tar.gz)
    Source code(zip)
  • v1.0.4(Jan 16, 2018)

    This release fixes a silly bug with subtraction of time values which gives the wrong result for times with exactly equal nanoseconds. While this probably would strike only rarely, it's a bug best squashed as early as possible, and so I'm drafting this release.

    Source code(tar.gz)
    Source code(zip)
  • v1.0.3(Dec 23, 2017)

  • v1.0.2(Dec 22, 2017)

    This is a bug-fix release, squashing a bug in the heap implementation which could cause watchers to fire out-of-sequence (according to priority) and timers to fire at the wrong times. The test suite is more complete and catches the bugs fixed since 1.0.

    Source code(tar.gz)
    Source code(zip)
  • v1.0.1(Dec 17, 2017)

  • v1.0(Dec 10, 2017)

  • v0.9(May 1, 2017)

    Dasynq is now complete and in a usable state. It has been minimally tested on Linux, OpenBSD, FreeBSD and Mac OS X. The API is stable and the documentation is quite complete.

    Before 1.0, the only expected change is the addition of some more tests to the testsuite, and of course bugfixes. (At the time of this release, there are no known bugs).

    Source code(tar.gz)
    Source code(zip)
  • v0.6(Mar 27, 2017)

    The API changed again just after v0.5 when I discovered a better way to avoid double dynamic dispatch using the "curiosly recurring template pattern" for watchers. This works well but feels awkward as an API, so a non-CRTP alternative may be added in the future; however, the current API is considered stable and should be supported in future versions, unless there are highly compelling reasons to break compatibility.

    For single-threaded event loops, Linux support is about complete; BSD and OS X -aka- MacOS do not have proper support for SYSTEM timers yet (timers will work incorrectly if the system time is changed). Multi-threaded event loop support is incomplete (in particular, timers are not thread-safe) and not well tested, but the API is available.

    USAGE.md file has been updated for the new API.

    Source code(tar.gz)
    Source code(zip)
  • v0.5(Mar 19, 2017)

Owner
Davin McCall
Computer scientist, software developer. I write code for fun and profit. Use open-source software, sometimes try to improve it. A BSD-friendly Linux user.
Davin McCall
"SaferCPlusPlus" is essentially a collection of safe data types intended to facilitate memory and data race safe C++ programming

A collection of safe data types that are compatible with, and can substitute for, common unsafe native c++ types.

null 329 Nov 24, 2022
A simple thread-safe implementation of runtime obfuscation for Win32 applications.

Thread-Safe Win32 Runtime Obfuscation A simple thread-safe implementation of runtime obfuscation for Win32 applications. The main use case for this is

Daniel 1 Mar 6, 2022
KeePassXC is a cross-platform community-driven port of the Windows application “Keepass Password Safe”.

KeePassXC KeePassXC is a modern, secure, and open-source password manager that stores and manages your most sensitive information. You can run KeePass

KeePassXC 14.7k Jan 2, 2023
The Leap Motion cross-format, cross-platform declarative serialization library

Introduction to LeapSerial LeapSerial is a cross-format, declarative, serialization and deserialization library written and maintained by Leap Motion.

Leap Motion (Ultraleap) 15 Jan 17, 2022
Loop is an object oriented programming language

Loop Loop is an object oriented programming language. How do I build and run loop? Make sure, you installed the requirements for clang and make: Debia

Loop 24 Aug 9, 2021
Path Tracking PID offers a tuneable PID control loop, decouling steering and forward velocity

path_tracking_pid Overview Path Tracking PID offers a tuneable PID control loop decouling steerting and forward velocity. The forward velocity is gene

Nobleo Technology 83 Dec 26, 2022
The QPEP-Enhanced Direct Sparse Odometry (DSO) with Loop Closure

QPEP-DSO: Quadratic Pose Estimation Problems (QPEP) Enhanced Direct Sparse Odometry with Loop Closure Code Arch The codes are motivated by DSO (https:

Jin Wu 8 Jun 23, 2022
Just loop forever, with sleep for specified seconds

loopever Just loop forever, with sleep for specified time Build & Install $ mkdkir build $ cd build $ cmake .. $ make $ make install Run $ loopever 0

Tomohito Nakayama 1 Oct 24, 2021
This is for interfacing rasberry-pi's (2 cards) with an arduino for sending raw data to form the close loop system to avoid motor heating by acting on a given temperature.

This is for interfacing rasberry-pi's (2 cards) with an arduino for sending raw data to form the close loop system to avoid motor heating by acting on a given temperature. Interface is explained through a master slave approach and client server approach. another camera is used with OPEN-CV platform to interface and collect data aswell.

Younes HAMZA 2 Oct 25, 2021
Tactile-Arcade-Games - Wrote a C program comprised of four separate games that run in a loop using the PSoC 5LP board and Cypress IDE.

Tactile-Arcade-Games - Wrote a C program comprised of four separate games that run in a loop using the PSoC 5LP board and Cypress IDE. Used two potentiometers, two ADCs to convert their voltages to digital values, a PWM to drive two servos, an 8x8 RGB LED matrix, 40 digital output pins and 8 power MOSFETS to control the matrix, and a character LCD display.

null 2 Dec 30, 2022