C++ C Other
Clone or download
Permalink
Failed to load latest commit information.
cmake cmake: also include required libraries for Dasynq target. Mar 5, 2018
doc Update TODO. Mar 29, 2018
extra btree_queue: renaming, comment improvements, minor fixes. Mar 8, 2018
makefiles Split makefiles up by platform. Nov 15, 2017
tests tests: add another test (timer/signal interaction). Mar 12, 2018
.gitignore Add CMake files, installed via "make install". Feb 25, 2018
LICENSE Update README for 0.9; add LICENSE. May 1, 2017
Makefile.common Up version to 1.1.4. Mar 29, 2018
README.md Up version to 1.1.4. Mar 29, 2018
dasynq-basewatchers.h Refactoring/cleanup. Feb 8, 2018
dasynq-btree_set.h Remove unused include. Dec 11, 2017
dasynq-childproc.h Fix FreeBSD/OpenBSD build. Feb 9, 2018
dasynq-config.h Refactoring; move common functionality into timer_base. Mar 13, 2018
dasynq-daryheap.h Minor heap implementation cleanups. Dec 23, 2017
dasynq-epoll.h Build fixes for epoll. Jan 30, 2018
dasynq-flags.h timerfd: wall-clock timer support Mar 19, 2017
dasynq-interrupt.h Properly support non-oneshot fd watchers in select/kqueue. Jan 29, 2018
dasynq-itimer.h Refactoring, and fix case of two clocks in itimer. Mar 15, 2018
dasynq-kqueue-macos.h Refactoring; move common functionality into timer_base. Mar 13, 2018
dasynq-kqueue.h Refactoring; move common functionality into timer_base. Mar 13, 2018
dasynq-mutex.h Introduce traits parameter to event_loop template. Dec 6, 2017
dasynq-posixtimer.h POSIX timer: don't set monotonic timer if we're not providing it. Apr 1, 2018
dasynq-pselect.h Refactoring; move common functionality into timer_base. Mar 13, 2018
dasynq-select.h Refactoring; move common functionality into timer_base. Mar 13, 2018
dasynq-signal.h select, pselect: implement monotonic timer via event call timeout Mar 12, 2018
dasynq-stableheap.h Use a stable priority queue to avoid starvation. Dec 16, 2017
dasynq-svec.h svector: fix to avoid constructing reserved-but-not-allocated elements. Jan 30, 2018
dasynq-timerbase.h Refactoring, and fix case of two clocks in itimer. Mar 15, 2018
dasynq-timerfd.h Build fixes for epoll. Jan 30, 2018
dasynq-util.h Organise dasynq-config.h, add in-line documentation. Dec 4, 2017
dasynq.h Posix timer: build fixes. Mar 29, 2018

README.md

Dasynq

Version 1.1.4

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, meaning that it should also work on nearly all other POSIX-compliant systems.

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.

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). Currently either epoll or kqueue are required; in many BSD variants it may be possible to build by defining DASYNQ_HAVE_KQUEUE to 1.

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.1.4)

# 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.