NAME

quark_update_boottime — refetch the boottime epoch used for wallclock translation

SYNOPSIS

#include <quark.h>

int
quark_update_boottime(void);

DESCRIPTION

All times handed out by quark are expressed in nanoseconds since boot: time of quark_event, proc_time_boot and exit_time_event of quark_process, as well as established_time and close_time of quark_socket. Translation to wallclock is done at the last moment via quark_time_to_wallclock(3), which adds an internal boottime epoch: the wallclock time of boot, fetched from the btime field of /proc/stat when the first queue is opened.

btime is derived from the current system clock, so it moves if the clock is stepped, as when NTP corrects a clock that was wrong at boot. Since quark has no event loop, it can not detect a step on its own: the user should call quark_update_boottime, which refetches btime, whenever the clock might have changed. As quark never bakes the epoch into the times it stores or hands out, an update also corrects the translation of times acquired before the step.

Two common ways of detecting a step:

• Poll the delta of CLOCK_REALTIME minus CLOCK_BOOTTIME: slewing adjusts both clocks at the same rate, so the delta only moves when the clock is stepped.
• Wait on a timerfd_create(2) descriptor of CLOCK_REALTIME armed with TFD_TIMER_CANCEL_ON_SET, which becomes readable when the clock is stepped.

The boottime epoch is shared by every queue in the process. quark_update_boottime, quark_get_boottime(3) and quark_time_to_wallclock(3) may be called from any thread without synchronization: the epoch is updated atomically and a concurrent reader observes either the previous or the new value.

RETURN VALUES

Returns 0 on success, -1 if btime could not be refetched, in which case the previous epoch is retained and errno is set.

SEE ALSO

quark_event_dump(3), quark_get_boottime(3), quark_process_iter(3), quark_process_lookup(3), quark_queue_block(3), quark_queue_close(3), quark_queue_default_attr(3), quark_queue_get_epollfd(3), quark_queue_get_event(3), quark_queue_get_stats(3), quark_queue_open(3), quark_time_to_wallclock(3), quark(7), quark-btf(8), quark-mon(8), quark-test(8)

HISTORY

quark_update_boottime appeared in quark 0.8, when all times handed out by quark switched from nanoseconds since the Unix epoch to nanoseconds since boot.