dasynq namespace

#include "dasynq.h"

namespace dasynq {

    // "null mutex", i.e. a no-op mutex "implementation" suitable for use in a single-threaded application
    class null_mutex; 

    // generic event loop
    template <typename T_Mutex> class event_loop;
    typedef event_loop<null_mutex> event_loop_n;
    typedef event_loop<std::mutex> event_loop_th;
    
    // event loop delay initialisation tag
    class delayed_init;
    
    // rearm codes
    enum class rearm
    {
        /** Re-arm the event watcher so that it receives further events */
        REARM,
        /** Disarm the event watcher so that it receives no further events, until it is re-armed explicitly */
        DISARM,
        /** Leave in current armed/disarmed state */
        NOOP,
        /** Remove the event watcher (and call "removed" callback) */
        REMOVE,
        /** The watcher has been removed explicitly */
        REMOVED,
        /** RE-queue the watcher to have its notification called again */
        REQUEUE
    };
    
    // clock types
    enum class clock_type
    {
        SYSTEM,    // wall-time clock, time may jump if set by user
        MONOTONIC  // monotonically increasing clock without jumps
    };
    
    // clock time
    class time_val;
    
    // time_val operators
    time_val operator-(const time_val &t1, const time_val &t2) noexcept;
    time_val operator+(const time_val &t1, const time_val &t2) noexcept;
    time_val &operator+=(time_val &t1, const time_val &t2) noexcept;
    time_val &operator-=(time_val &t1, const time_val &t2) noexcept;
    int operator/(const time_val &t1, const time_val &t2) noexcept;
    
    bool operator<(const time_val &t1, const time_val &t2) noexcept;
    bool operator==(const time_val &t1, const time_val &t2) noexcept;
    bool operator<=(const time_val &t1, const time_val &t2) noexcept;
    bool operator!=(const time_val &t1, const time_val &t2) noexcept;
    bool operator>(const time_val &t1, const time_val &t2) noexcept;
    bool operator>=(const time_val &t1, const time_val &t2) noexcept;
    
    time_val &operator<<=(time_val &t, int n) noexcept;
    time_val &operator>>=(time_val &t, int n) noexcept;
    time_val operator<<(time_val &t, int n) noexcept;
    time_val operator>>(time_val &t, int n) noexcept;
    
    // event watch flags
    constexpr unsigned int IN_EVENTS;
    constexpr unsigned int OUT_EVENTS;
}

clock_type

#include "dasynq.h"

namespace dasynq {
    enum class clock_type
    {
        SYSTEM,    // wall-time clock, time may jump if set by user
        MONOTONIC  // monotonically increasing clock without jumps
    };
}

Brief: The clock_type enumeration is used to differentiate between two different types of clock: the system clock, which represents an adjustable "wall clock" time, or the monotonic clock, a non-adjustable clock tracking time elapsed since some fixed (but arbitrary) point in time.

Details

Not all systems support the monotonic clock. In Dasynq, using the MONOTONIC clock on such systems will instead refer to the SYSTEM clock.

time_val

#include "dasynq.h"

namespace dasynq {
    class time_val;
}

Brief: The time_val class represents high-precision clock times, and supports arithmetic operations on them. It acts as a wrapper to a struct timespec object, so that times are represented as a combination of seconds and nanoseconds. In addition to the public members listed below, a number of arithmetic and comparison operators are defined as non-member functions. Noe that time_val cannot be used to represent negative time intervals.

Public members

rearm — dasynq::rearm

#include "dasynq.h"

namespace dasynq {
    enum class rearm
    {
        /** Re-arm the event watcher so that it receives further events */
        REARM,
        /** Disarm the event watcher so that it receives no further events, until it is re-armed explicitly */
        DISARM,
        /** Leave in current armed/disarmed state */
        NOOP,
        /** Remove the event watcher (and call "removed" callback) */
        REMOVE,
        /** The watcher has been removed explicitly */
        REMOVED,
        /** Re-queue the watcher to have its callback called again */
        REQUEUE
    };
}

Brief: The rearm enumeration specifies various watcher actions that can be applied automatically on return from the callback function.

Details

A watcher that has been added to an event loop can be enabled or disabled. If enabled, the watcher may be queued for processing by the event loop; at the processing stage, the callback function of a queued watcher will be called. See the event_loop documentation for a detailed discussion. A watcher is disabled when it is queued and must be re-enabled after processing in order to receive further events; an easy way to accomplish this is to return the rearm::REARM value from the callback.
Note: a multi-threaded event loop has the limitation that the watcher should normally not be re-enabled while the callback is being executed. Returning rearm::REARM from the callback is a convenient way to get around this limitation.

In the case of a single-threaded event loop where a watcher has been re-enabled explicitly while the callback function is executing, the rearm::DISARM code can be returned in order to disable it again (this has no effect if the watcher is already disabled).

Other return codes are largely self-explanatory. Note that rearm::REMOVED code must be returned if the watcher has been scheduled for removal from the loop (de-registered) via the watcher's deregister function.

Note that a watcher that continuously requeues itself by returning REQUEUE potentially starves other, lower-priority, watchers from processing.