diff options
Diffstat (limited to 'doc/libstddjb/tai.html')
| -rw-r--r-- | doc/libstddjb/tai.html | 33 |
1 files changed, 28 insertions, 5 deletions
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. </p> <p> -<code> void tain_now_set_wallclock (void) </code> <br /> +<code> int tain_now_set_wallclock (tain_t *a) </code> <br /> Tells skalibs that future invocations of <tt>tain_now()</tt> (see below) should use a wall clock, i.e. the system time as returned by <tt>clock_gettime(CLOCK_REALTIME)</tt> or -<tt>gettimeofday()</tt>. This is the default: it is not necessary +<tt>gettimeofday()</tt>. Also reads the current time into *<em>a</em>. +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 <tt>tain_now()</tt> at the start of a program. </p> @@ -184,13 +186,15 @@ Otherwise, they will fail with errno set to ENOSYS. </p> <p> -<code> int tain_stopwatch_init (clock_t cl, tain_t *offset) </code> <br /> +<code> int tain_stopwatch_init (tain_t *a, clock_t cl, tain_t *offset) </code> <br /> Initializes a stopwatch in *<em>offset</em>, using a clock named <em>cl</em>. Typically, <em>cl</em> is something like CLOCK_MONOTONIC, when it is defined by the system. The actual value of *<em>offset</em> is meaningless to the user; <em>offset</em>'s only use is to be given as a second parameter to <tt>tain_stopwatch_read()</tt>. The function returns 1 if it succeeds or 0 (and sets errno) if it fails. +On success, the current time, as given by the <em>system clock</em> (a +wall clock), is returned in *<em>a</em>. </p> <p> @@ -216,7 +220,7 @@ The function returns 1 if it succeeds or 0 (and sets errno) if it fails. </p> <p> -<code> void tain_now_set_stopwatch (void) </code> <br /> +<code> int tain_now_set_stopwatch (tain_t *a) </code> <br /> Tells skalibs that future invocations of <tt>tain_now()</tt> (see below) should use a stopwatch, i.e. the system time as returned by <tt>clock_gettime(CLOCK_MONOTONIC)</tt> 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). <br /> If no monotonic clock is supported by the system, this function does -nothing (and <tt>tain_now()</tt> will keep using a wall clock). +not change what <tt>tain_now()</tt> refers to (i.e. it will keep +referring to the system clock). <br /> +Returns 1 on success and 0 (and sets errno) on failure. On success, +the current time, as given by the <em>system clock</em> (a wall clock), +is returned in *<em>a</em>. </p> <h3> All-purpose time reading </h3> @@ -249,6 +257,21 @@ make <tt>tain_now()</tt> resistant to system clock jumps, but will also make it unsuitable for timestamping. </p> +<p> + In other words: the <em>first</em> time you need to read the clock, or +at the start of your program, you should use +<tt>tain_now_set_wallclock()</tt> or <tt>tain_now_set_stopwatch()</tt> +depending on whether you want the One True Time Source to be the system +clock (CLOCK_REALTIME or <tt>gettimeofday()</tt>) or a stopwatch +(CLOCK_MONOTONIC, if supported). Afterwards, every time you need to read +from that time source, use <tt>tain_now()</tt>. skalibs functions that +may block, such as <tt>iopause_g</tt>, internally call <tt>tain_now()</tt> +to update the timestamp they're using, so they will use the time source +you have defined. (Functions ending in <tt>_g</tt> +use the STAMP global variable to store the current timestamp.) +</p> + + <h3> Converting to/from libc representations </h3> <p> |