class sys.Timer

Overview

This class provides facilities to manage both peridodic(repetitive) and non-periodic(single-shot) timers. More…

import "sys_Timer.jnc"

class Timer {
    // construction

    construct();
    destruct();

    // methods

    bool errorcode start(
        void function* func(),
        uint64_t dueTime,
        uint_t interval
    );

    void stop();

    bool errorcode startDueTimer(
        void function* func(),
        uint64_t dueTime
    );

    bool errorcode startPeriodicTimer(
        void function* func(),
        uint_t interval
    );

    bool errorcode startSingleShotTimer(
        void function* func(),
        uint_t delay
    );

    // aliases

    alias dispose = stop;
};

Detailed Documentation

This class provides facilities to manage both peridodic(repetitive) and non-periodic(single-shot) timers.

Each instance of sys.Timer manages a single timer(either periodic, or single-shot). You start the timer with start, startDueTimer, startSingleShotTimer, startPeriodicTimer methods. When the timer is due, it will call the function you have supplied as an argument to one of aforementioned methods.

To stop the timer, invoke stop method. For local timers it is recommended to use disposable pattern [1].

Code sample:

import "sys_Timer.jnc"

onTimer(int param) {
    // ...
}

int main() {
    // ...

    disposable sys.Timer timer;
    timer.startPeriodic(onTimer ~(1, 2), 1000);

    // ...
} // <-- timer.stop will be called

Methods

bool errorcode start(
    void function* func(),
    uint64_t dueTime,
    uint_t interval
)

Starts a new peridodic or non-periodic timer.

The function accepts three arguments. The first one, timerFunc specifies the function pointer to the timer function to be called when the timer is due. The second one, dueTime, specifies the timestamp of the moment when the timer function should be first called. The last one, period, specifies the period in milliseconds for a periodic timer, or 0 if this is a single-shot timer.

Returns true on success. If the timer could not be started, error supplied by operating system is set and then the function returns false [2].

If the timer has been already started, start method stops the previous timer first.

void stop()

Stops a previously started timer, does nothing if the timer is not started. This function always succeeds.

For local timers it is recommended to use disposable pattern [1].

bool errorcode startDueTimer(
    void function* func(),
    uint64_t dueTime
)

Starts a non-periodic due timer, i.e. you specify the timestamp of the moment when your function should be called.

Technically calling startDueTimer is equivalent to calling start with the last interval argument set to 0.

bool errorcode startPeriodicTimer(
    void function* func(),
    uint_t interval
)

Starts a periodic timer, i.e. the timer will invoke your function each interval milliseconds.

This is probably the most common type of timer. Technically calling startDueTimer is equivalent to calling start with the dueTime argument calculated as sys.getTimestamp() + interval.

bool errorcode startSingleShotTimer(
    void function* func(),
    uint_t delay
)

Starts a single-shot non-periodic timer, i.e. you specify the delay in milliseconds after passing of which your function will be invoked.

Technically calling startDueTimer is equivalent to calling start with the dueTime argument calculated as sys.getTimestamp() + interval and interval set to 0.

Aliases

alias dispose = stop

Effectively makes sys.Timer a disposable class [1].

Footnotes