From 98d3a523be4fff36f65e71c37df8b9e127b12b83 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 7 Sep 2019 11:36:04 +0000 Subject: Update doc --- doc/libstddjb/tai.html | 33 ++++++++++++++++++++++++++++----- 1 file changed, 28 insertions(+), 5 deletions(-) (limited to 'doc/libstddjb/tai.html') diff --git a/doc/libstddjb/tai.html b/doc/libstddjb/tai.html index 3826e80..6ffcff8 100644 --- a/doc/libstddjb/tai.html +++ b/doc/libstddjb/tai.html @@ -165,11 +165,13 @@ the right format for the system clock.

- void tain_now_set_wallclock (void)
+ int tain_now_set_wallclock (tain_t *a)
Tells skalibs that future invocations of tain_now() (see below) should use a wall clock, i.e. the system time as returned by clock_gettime(CLOCK_REALTIME) or -gettimeofday(). This is the default: it is not necessary +gettimeofday(). Also reads the current time into *a. +Returns 1 if it succeeds or 0 (and sets errno) if it fails. +A wall clock is the default: it is not necessary to call this function before invoking tain_now() at the start of a program.

@@ -184,13 +186,15 @@ Otherwise, they will fail with errno set to ENOSYS.

- int tain_stopwatch_init (clock_t cl, tain_t *offset)
+ int tain_stopwatch_init (tain_t *a, clock_t cl, tain_t *offset)
Initializes a stopwatch in *offset, using a clock named cl. Typically, cl is something like CLOCK_MONOTONIC, when it is defined by the system. The actual value of *offset is meaningless to the user; offset's only use is to be given as a second parameter to tain_stopwatch_read(). The function returns 1 if it succeeds or 0 (and sets errno) if it fails. +On success, the current time, as given by the system clock (a +wall clock), is returned in *a.

@@ -216,7 +220,7 @@ The function returns 1 if it succeeds or 0 (and sets errno) if it fails.

- void tain_now_set_stopwatch (void)
+ int tain_now_set_stopwatch (tain_t *a)
Tells skalibs that future invocations of tain_now() (see below) should use a stopwatch, i.e. the system time as returned by clock_gettime(CLOCK_MONOTONIC) or similar, @@ -226,7 +230,11 @@ system clock does, than to display absolute time that is in sync with a human view of time (which is the cause and reason of most system clock jumps).
If no monotonic clock is supported by the system, this function does -nothing (and tain_now() will keep using a wall clock). +not change what tain_now() refers to (i.e. it will keep +referring to the system clock).
+Returns 1 on success and 0 (and sets errno) on failure. On success, +the current time, as given by the system clock (a wall clock), +is returned in *a.

All-purpose time reading

@@ -249,6 +257,21 @@ make tain_now() resistant to system clock jumps, but will also make it unsuitable for timestamping.

+

+ In other words: the first time you need to read the clock, or +at the start of your program, you should use +tain_now_set_wallclock() or tain_now_set_stopwatch() +depending on whether you want the One True Time Source to be the system +clock (CLOCK_REALTIME or gettimeofday()) or a stopwatch +(CLOCK_MONOTONIC, if supported). Afterwards, every time you need to read +from that time source, use tain_now(). skalibs functions that +may block, such as iopause_g, internally call tain_now() +to update the timestamp they're using, so they will use the time source +you have defined. (Functions ending in _g +use the STAMP global variable to store the current timestamp.) +

+ +

Converting to/from libc representations

-- cgit v1.2.3