geopm_time(3) – helper methods for time
Synopsis
#include <geopm_time.h>
Link with -lgeopm (MPI) or -lgeopm (non-MPI)
C interfaces:
#define GEOPM_TIME_STRING_MAX 255ULL
static inline int geopm_time_string(int buf_size,
char *buf);
static inline int geopm_time(struct geopm_time_s *time);
static inline int geopm_time_real(struct geopm_time_s *time);
static inline double geopm_time_diff(const struct geopm_time_s *begin,
const struct geopm_time_s *end);
static inline bool geopm_time_comp(const struct geopm_time_s *aa,
const struct geopm_time_s *bb);
static inline void geopm_time_add(const struct geopm_time_s *begin,
double elapsed,
struct geopm_time_s *end);
static inline double geopm_time_since(const struct geopm_time_s *begin);
int geopm_time_zero(struct geopm_time_s *zero_time);
static inline int geopm_time_to_string(const struct geopm_time_s *time, int buf_size, char *buf);
int geopm_time_real_to_iso_string(const struct geopm_time_s *time, int buf_size, char *buf);
static inline int geopm_time_string(int buf_size, char *buf);
static inline double geopm_time_since(const struct geopm_time_s *begin);
C++ interfaces:
struct geopm_time_s geopm::time_curr(void);
struct geopm_time_s geopm::time_curr_real(void);
std::string geopm::time_curr_string(void);
struct geopm_time_s geopm::time_zero(void);
void geopm::time_zero_reset(const geopm_time_s &zero);
Description
The geopm_time.h
header defines GEOPM interfaces for measuring time in seconds relative to a
fixed arbitrary reference point. The geopm_time_s structure is used to hold
time values.
The default clock used is Linux CLOCK_MONTONIC_RAW. In general, these
interfaces use this as the time reference. This clock is the most precise for
calculating time differences.
There are some times when absolute time accuracy is preferred over time
difference accuracy. For these cases, GEOPM provides time functions that use
CLOCK_REALTIME as the reference time. There is a C accessor for real time:
geopm_time_real(), and there is also a C++ accessor:
geopm::time_curr_real(). Only geopm_time_s values created with these
accessors may be passed to geopm_time_to_iso_string() which provides a
nano-second precision absolute date string.
The last time reference is useful when comparing against the values returned by
PlatformIO for the TIME signal. The reference time (0.0) for this signal is
a CLOCK_MONOTONIC_RAW time value that can be accessed in C with
geopm_time_zero() and in C++ with geopm::time_zero(). There is also a
way to reset this reference with geopm_time_zero_reset() and
geopm:time_zero_reset() by providing a CLOCK_MONOTONIC_RAW time value.
The constant GEOPM_TIME_STRING_MAX may be used to allocate buf results
for any of the C geopm_time_* function calls, although this value is larger than
is generally required.
geopm_time_string()Fills buf with the current date and time as a string. The string will be null-terminated and truncated to buf_size, which must be at least 26 characters as required by asctime_r(3).
geopm_time()Sets time to the current time using Linux CLOCK_MONOTONIC_RAW clock. This can be used with geopm_time_to_string() to get a an approximate date string.
geopm_time_real()Sets time to the current time using the Linux CLOCK_REALTIME clock. This can be used with geopm_time_real_to_iso_string() for an accurate ISO 8601 standard date string representation.
geopm_time_diff()Returns the difference in seconds between begin and end.
geopm_time_comp()Return true if aa is less than bb.
geopm_time_add()Sets end to elapsed seconds after begin.
geopm_time_since()Returns the number of seconds elapsed between the current time and begin.
geopm_time_zero()Return the time since the first call to this interface or the
geopm::time_zero()interface by the calling process. See also:geopm::time_zero_reset().geopm_time_to_string()Convert a CLOCK_MONOTONIC_RAW time representation returned by
geopm_time()orgeopm::time_curr()into an approximate date string.geopm_time_real_to_iso_string()Convert a CLOCK_REALTIME time representation returned by
geopm_time_real()orgeopm::time_curr_real()into an ISO 8601 standard date string with nanosecond resolution.geopm_time_string()Provide a date string for the current time in the format returned by geopm_time_to_string().
geopm::time_zero()Return the time since the first call to this interface or the
geopm_time_zero()interface by the calling process. See also:geopm::time_zero_reset().geopm::time_curr()Returns the current time using Linux CLOCK_MONOTONIC_RAW clock. This can be used with geopm_time_to_string() to get a an approximate date string.
geopm::time_curr_real()Returns the current time using the Linux CLOCK_REALTIME clock. This can be used with geopm_time_real_to_iso_string() for an accurate ISO 8601 standard date string representation.
geopm::time_curr_string()Returns an accurate ISO 8601 standard date string representation of the current time using Linux CLOCK_REALTIME clock..
geopm::time_zero_reset()Override the reference time for the
geopm_time_zero()andgeopm::time_zero()with the value zero.
Structure Type
This structure is part of the global C namespace.
This structure is used to abstract the timespec on Linux from other representations of time.
The field struct timespec t is a POSIX.1b structure for a time value.
This is like a struct timeval but has nanoseconds instead of microseconds.
struct geopm_time_s {
struct timespec t;
};