8.1. Time API

8.1.1. Overview

Anjay Lite uses a POSIX-compatible time implementation based on clock_gettime() by default. If your platform doesn’t support the POSIX time API, you need to disable POSIX compatibility and provide your own time functions.

8.1.2. List of functions to implement

To disable POSIX compatibility and use a custom implementation:

  1. Configure CMake with -DANJ_WITH_TIME_POSIX_COMPAT=OFF.

  2. Implement the following functions:

Function

Purpose

anj_time_monotonic_now()

Returns the current monotonic time.

anj_time_real_now()

Returns the current real time (Unix epoch).

Note

For function signatures and detailed descriptions, see include_public/anj/compat/time.h.

Important

For information about time types, units, arithmetic, and string helpers used throughout Anjay Lite, see Doxygen comments in include_public/anj/time.h.

8.1.3. Reference implementation

The default implementation in src/anj/compat/posix/anj_time.c uses the POSIX clock_gettime() API and can be used as a reference for your integration.

8.1.3.1. anj_time_monotonic_now()

The anj_time_monotonic_now() function must return the current monotonic time as anj_time_monotonic_t.

Monotonic time:

  • Represents time elapsed since an arbitrary epoch (typically system boot).

  • Must not be affected by wall-clock adjustments (NTP synchronization, manual edits, or time zone changes).

  • Must never stop and must never go backwards. It needs to be a continuously advancing time base even if the system enters sleep/suspend.

If the platform’s default monotonic clock stops across suspend, use a clock source that continues counting, or implement compensation using the platform’s power-management hooks.

In the POSIX reference implementation, anj_time_monotonic_now() prefers CLOCK_MONOTONIC if available; otherwise it falls back to CLOCK_REALTIME.

/* Get the current time in microseconds from selected clock type */
static int64_t get_time(clockid_t clk_id) {
    struct timespec res;
    if (clock_gettime(clk_id, &res)) {
        return 0;
    }
    return (int64_t) res.tv_sec * 1000 * 1000 + (int64_t) res.tv_nsec / 1000;
}

anj_time_monotonic_t anj_time_monotonic_now(void) {
#    ifdef CLOCK_MONOTONIC
    return anj_time_monotonic_new(get_time(CLOCK_MONOTONIC), ANJ_TIME_UNIT_US);
#    else  /* CLOCK_MONOTONIC */
    return anj_time_monotonic_new(get_time(CLOCK_REALTIME), ANJ_TIME_UNIT_US);
#    endif /* CLOCK_MONOTONIC */
}

8.1.3.1.1. Resolution, precision, and drift

The resolution and precision of the monotonic clock are platform-dependent. All internal scheduling in Anjay Lite (notifications, retransmissions, registration lifetime handling, etc.) relies on monotonic time.

Your integration should therefore:

  • provide sufficient resolution for your use case (millisecond-level resolution is typically sufficient),

  • keep clock drift under control and take it into account especially for long intervals (e.g., operations scheduled once per day), where small errors may accumulate over time.

8.1.3.2. anj_time_real_now()

The anj_time_real_now() function must return the current real (wall-clock) time since the Unix epoch (00:00:00 UTC on 1970-01-01) as anj_time_real_t.

Important

Within the Anjay Lite library, the real-time clock is used for: the LwM2M Send Operation timestamping and X.509 certificate validity period checks.

Integrations that do not use these features and do not require real-time functionality may return a constant value (e.g., zero) from this function, or map it to the monotonic clock.

In the POSIX reference implementation, this function wraps CLOCK_REALTIME.

anj_time_real_t anj_time_real_now(void) {
    return anj_time_real_new(get_time(CLOCK_REALTIME), ANJ_TIME_UNIT_US);
}

Note

Real-time clock can be synchronized by Anjay Lite’s Time Synchronization module. Check the NTP-based time synchronization for details.