.TH "qbutil.h" 3 "Fri Apr 26 2019" "Version 1.0.5" "libqb" \" -*- nroff -*- .ad l .nh .SH NAME qbutil.h \- These are some convience functions used throughout libqb\&. .SH SYNOPSIS .br .PP \fC#include \fP .br \fC#include \fP .br \fC#include \fP .br \fC#include \fP .br .SS "Data Structures" .in +1c .ti -1c .RI "struct \fBqb_version\fP" .br .RI "Structured library versioning info\&. " .in -1c .SS "Macros" .in +1c .ti -1c .RI "#define \fBQB_UTIL_SW_OVERWRITE\fP 0x01" .br .in -1c .SS "Typedefs" .in +1c .ti -1c .RI "typedef struct qb_thread_lock_s \fBqb_thread_lock_t\fP" .br .ti -1c .RI "typedef void(* \fBqb_util_log_fn_t\fP) (const char *file_name, int32_t file_line, int32_t severity, const char *msg)" .br .ti -1c .RI "typedef struct qb_util_stopwatch \fBqb_util_stopwatch_t\fP" .br .in -1c .SS "Enumerations" .in +1c .ti -1c .RI "enum \fBqb_thread_lock_type_t\fP { \fBQB_THREAD_LOCK_SHORT\fP, \fBQB_THREAD_LOCK_LONG\fP } .RI "QB_THREAD_LOCK_SHORT is a short term lock (spinlock if available on your system) QB_THREAD_LOCK_LONG is a mutex\&. "" .br .in -1c .SS "Functions" .in +1c .ti -1c .RI "\fBqb_thread_lock_t\fP * \fBqb_thread_lock_create\fP (\fBqb_thread_lock_type_t\fP type)" .br .RI "Create a new lock of the given type\&. " .ti -1c .RI "int32_t \fBqb_thread_lock\fP (\fBqb_thread_lock_t\fP *tl)" .br .RI "Calls either pthread_mutex_lock() or pthread_spin_lock()\&. " .ti -1c .RI "int32_t \fBqb_thread_trylock\fP (\fBqb_thread_lock_t\fP *tl)" .br .RI "Calls either pthread_mutex_trylock() or pthread_spin_trylock()\&. " .ti -1c .RI "int32_t \fBqb_thread_unlock\fP (\fBqb_thread_lock_t\fP *tl)" .br .RI "Calls either pthread_mutex_unlock() or pthread_spin_unlock\&. " .ti -1c .RI "int32_t \fBqb_thread_lock_destroy\fP (\fBqb_thread_lock_t\fP *tl)" .br .RI "Calls either pthread_mutex_destro() or pthread_spin_destroy()\&. " .ti -1c .RI "void \fBqb_util_set_log_function\fP (\fBqb_util_log_fn_t\fP fn) \fBQB_GNUC_DEPRECATED\fP" .br .RI "Use this function to output libqb internal log message as you wish\&. " .ti -1c .RI "void \fBqb_timespec_add_ms\fP (struct timespec *ts, int32_t ms)" .br .RI "Add milliseconds onto the timespec\&. " .ti -1c .RI "uint64_t \fBqb_util_nano_current_get\fP (void)" .br .RI "Get the current number of nano secounds produced by the systems incrementing clock (CLOCK_MONOTOMIC if available)\&. " .ti -1c .RI "uint64_t \fBqb_util_nano_monotonic_hz\fP (void)" .br .RI "Get the frequence of the clock used in \fBqb_util_nano_current_get()\fP\&. " .ti -1c .RI "uint64_t \fBqb_util_nano_from_epoch_get\fP (void)" .br .RI "Get the time in nano seconds since epoch\&. " .ti -1c .RI "void \fBqb_util_timespec_from_epoch_get\fP (struct timespec *ts)" .br .RI "Get the time in timespec since epoch\&. " .ti -1c .RI "char * \fBqb_strerror_r\fP (int errnum, char *buf, size_t buflen)" .br .RI "strerror_r replacement\&. " .ti -1c .RI "\fBqb_util_stopwatch_t\fP * \fBqb_util_stopwatch_create\fP (void)" .br .RI "Create a Stopwatch (to time operations) " .ti -1c .RI "void \fBqb_util_stopwatch_free\fP (\fBqb_util_stopwatch_t\fP *sw)" .br .RI "Free the stopwatch\&. " .ti -1c .RI "void \fBqb_util_stopwatch_start\fP (\fBqb_util_stopwatch_t\fP *sw)" .br .RI "Start the stopwatch\&. " .ti -1c .RI "void \fBqb_util_stopwatch_stop\fP (\fBqb_util_stopwatch_t\fP *sw)" .br .RI "Stop the stopwatch\&. " .ti -1c .RI "uint64_t \fBqb_util_stopwatch_us_elapsed_get\fP (\fBqb_util_stopwatch_t\fP *sw)" .br .RI "Get the elapsed time in micro seconds\&. " .ti -1c .RI "float \fBqb_util_stopwatch_sec_elapsed_get\fP (\fBqb_util_stopwatch_t\fP *sw)" .br .RI "Get the elapsed time in seconds\&. " .ti -1c .RI "int32_t \fBqb_util_stopwatch_split_ctl\fP (\fBqb_util_stopwatch_t\fP *sw, uint32_t max_splits, uint32_t options)" .br .ti -1c .RI "uint64_t \fBqb_util_stopwatch_split\fP (\fBqb_util_stopwatch_t\fP *sw)" .br .RI "Create a new time split (or lap time) " .ti -1c .RI "uint32_t \fBqb_util_stopwatch_split_last\fP (\fBqb_util_stopwatch_t\fP *sw)" .br .RI "Get the last split index to be used by \fBqb_util_stopwatch_time_split_get()\fP " .ti -1c .RI "uint64_t \fBqb_util_stopwatch_time_split_get\fP (\fBqb_util_stopwatch_t\fP *sw, uint32_t receint, uint32_t older)" .br .RI "Read the time split (in us) from 'receint' to 'older'\&. " .in -1c .SS "Variables" .in +1c .ti -1c .RI "const struct \fBqb_version\fP \fBqb_ver\fP" .br .ti -1c .RI "const char *const \fBqb_ver_str\fP" .br .RI "Complete library versioning info as a string\&. " .in -1c .SH "Detailed Description" .PP These are some convience functions used throughout libqb\&. .PP \fBAuthor:\fP .RS 4 Angus Salkeld asalkeld@redhat.com .RE .PP \fBLocking\fP .RS 4 .IP "\(bu" 2 \fBqb_thread_lock_create()\fP .IP "\(bu" 2 \fBqb_thread_lock()\fP .IP "\(bu" 2 \fBqb_thread_trylock()\fP .IP "\(bu" 2 \fBqb_thread_unlock()\fP .IP "\(bu" 2 \fBqb_thread_lock_destroy()\fP .PP .RE .PP \fBTime functions\fP .RS 4 .IP "\(bu" 2 \fBqb_timespec_add_ms()\fP .IP "\(bu" 2 \fBqb_util_nano_current_get()\fP .IP "\(bu" 2 \fBqb_util_nano_monotonic_hz()\fP .IP "\(bu" 2 \fBqb_util_nano_from_epoch_get()\fP .IP "\(bu" 2 \fBqb_util_timespec_from_epoch_get()\fP .PP .RE .PP \fBBasic Stopwatch\fP .RS 4 .PP .nf uint64_t elapsed1; uint64_t elapsed2; qb_util_stopwatch_t *sw = qb_util_stopwatch_create(); qb_util_stopwatch_start(sw); usleep(sometime); qb_util_stopwatch_stop(sw); elapsed1 = qb_util_stopwatch_us_elapsed_get(sw); usleep(somemoretime); qb_util_stopwatch_stop(sw); elapsed2 = qb_util_stopwatch_us_elapsed_get(sw); qb_util_stopwatch_free(sw); .fi .PP .RE .PP \fBStopwatch with splits\fP .RS 4 Setup a stopwatch with space for 3 splits\&. .RE .PP .PP .nf uint64_t split; qb_util_stopwatch_t *sw = qb_util_stopwatch_create(); qb_util_stopwatch_split_ctl(sw, 3, 0); qb_util_stopwatch_start(sw); usleep(sometime); qb_util_stopwatch_split(sw); usleep(somemoretime); qb_util_stopwatch_split(sw); usleep(somemoretime); qb_util_stopwatch_split(sw); idx = qb_util_stopwatch_split_last(sw); do { split = qb_util_stopwatch_time_split_get(sw, idx, idx); qb_log(LOG_INFO, "split %d is %"PRIu64"", last, split); idx--; } while (split > 0); split = qb_util_stopwatch_time_split_get(sw, 2, 1); qb_log(LOG_INFO, "time between second and third split is %"PRIu64"", split); qb_util_stopwatch_free(sw); .fi .PP .SH "Macro Definition Documentation" .PP .SS "#define QB_UTIL_SW_OVERWRITE 0x01" .SH "Typedef Documentation" .PP .SS "typedef struct qb_thread_lock_s \fBqb_thread_lock_t\fP" .SS "typedef void(* qb_util_log_fn_t) (const char *file_name, int32_t file_line, int32_t severity, const char *msg)" .SS "typedef struct qb_util_stopwatch \fBqb_util_stopwatch_t\fP" .SH "Enumeration Type Documentation" .PP .SS "enum \fBqb_thread_lock_type_t\fP" .PP QB_THREAD_LOCK_SHORT is a short term lock (spinlock if available on your system) QB_THREAD_LOCK_LONG is a mutex\&. .PP \fBEnumerator\fP .in +1c .TP \fB\fIQB_THREAD_LOCK_SHORT \fP\fP .TP \fB\fIQB_THREAD_LOCK_LONG \fP\fP .SH "Function Documentation" .PP .SS "char* qb_strerror_r (int errnum, char * buf, size_t buflen)" .PP strerror_r replacement\&. .SS "int32_t qb_thread_lock (\fBqb_thread_lock_t\fP * tl)" .PP Calls either pthread_mutex_lock() or pthread_spin_lock()\&. .SS "\fBqb_thread_lock_t\fP* qb_thread_lock_create (\fBqb_thread_lock_type_t\fP type)" .PP Create a new lock of the given type\&. .PP \fBParameters:\fP .RS 4 \fItype\fP QB_THREAD_LOCK_SHORT == spinlock (where available, else mutex) QB_THREAD_LOCK_LONG == mutex .RE .PP \fBReturns:\fP .RS 4 pointer to qb_thread_lock_type_t or NULL on error\&. .RE .PP .SS "int32_t qb_thread_lock_destroy (\fBqb_thread_lock_t\fP * tl)" .PP Calls either pthread_mutex_destro() or pthread_spin_destroy()\&. .SS "int32_t qb_thread_trylock (\fBqb_thread_lock_t\fP * tl)" .PP Calls either pthread_mutex_trylock() or pthread_spin_trylock()\&. .SS "int32_t qb_thread_unlock (\fBqb_thread_lock_t\fP * tl)" .PP Calls either pthread_mutex_unlock() or pthread_spin_unlock\&. .SS "void qb_timespec_add_ms (struct timespec * ts, int32_t ms)" .PP Add milliseconds onto the timespec\&. .PP \fBParameters:\fP .RS 4 \fIts\fP the ts to add to .br \fIms\fP the amount of milliseconds to increment ts .RE .PP .SS "uint64_t qb_util_nano_current_get (void)" .PP Get the current number of nano secounds produced by the systems incrementing clock (CLOCK_MONOTOMIC if available)\&. .SS "uint64_t qb_util_nano_from_epoch_get (void)" .PP Get the time in nano seconds since epoch\&. .SS "uint64_t qb_util_nano_monotonic_hz (void)" .PP Get the frequence of the clock used in \fBqb_util_nano_current_get()\fP\&. .SS "void qb_util_set_log_function (\fBqb_util_log_fn_t\fP fn)" .PP Use this function to output libqb internal log message as you wish\&. .SS "\fBqb_util_stopwatch_t\fP* qb_util_stopwatch_create (void)" .PP Create a Stopwatch (to time operations) .SS "void qb_util_stopwatch_free (\fBqb_util_stopwatch_t\fP * sw)" .PP Free the stopwatch\&. .SS "float qb_util_stopwatch_sec_elapsed_get (\fBqb_util_stopwatch_t\fP * sw)" .PP Get the elapsed time in seconds\&. (it must have been started and stopped)\&. .SS "uint64_t qb_util_stopwatch_split (\fBqb_util_stopwatch_t\fP * sw)" .PP Create a new time split (or lap time) .PP \fBParameters:\fP .RS 4 \fIsw\fP the stopwatch .RE .PP \fBReturn values:\fP .RS 4 \fIthe\fP relative split time in micro seconds .br \fI0\fP if no more splits available .RE .PP .SS "int32_t qb_util_stopwatch_split_ctl (\fBqb_util_stopwatch_t\fP * sw, uint32_t max_splits, uint32_t options)" .PP \fBParameters:\fP .RS 4 \fIsw\fP the stopwatch .br \fImax_splits\fP maximum number of time splits .br \fIoptions\fP (0 or QB_UTIL_SW_OVERWRITE ) .RE .PP \fBReturn values:\fP .RS 4 \fI0\fP on success .br \fI-errno\fP on failure .RE .PP .SS "uint32_t qb_util_stopwatch_split_last (\fBqb_util_stopwatch_t\fP * sw)" .PP Get the last split index to be used by \fBqb_util_stopwatch_time_split_get()\fP .PP \fBNote:\fP .RS 4 this is zero based .RE .PP \fBParameters:\fP .RS 4 \fIsw\fP the stopwatch .RE .PP \fBReturns:\fP .RS 4 the last entry index .RE .PP .SS "void qb_util_stopwatch_start (\fBqb_util_stopwatch_t\fP * sw)" .PP Start the stopwatch\&. This also acts as a reset\&. Essentially it sets the starting time and clears the splits\&. .SS "void qb_util_stopwatch_stop (\fBqb_util_stopwatch_t\fP * sw)" .PP Stop the stopwatch\&. This just allows you to get the elapsed time\&. So you can call this multiple times\&. Do not call \fBqb_util_stopwatch_start()\fP unless you want to reset the stopwatch\&. .SS "uint64_t qb_util_stopwatch_time_split_get (\fBqb_util_stopwatch_t\fP * sw, uint32_t receint, uint32_t older)" .PP Read the time split (in us) from 'receint' to 'older'\&. If older == receint then the cumulated split will be returned (from the stopwatch start)\&. .PP \fBParameters:\fP .RS 4 \fIsw\fP the stopwatch .br \fIreceint\fP split .br \fIolder\fP split .RE .PP \fBReturn values:\fP .RS 4 \fIthe\fP split time in micro seconds .br \fI0\fP if not a valid split .RE .PP .SS "uint64_t qb_util_stopwatch_us_elapsed_get (\fBqb_util_stopwatch_t\fP * sw)" .PP Get the elapsed time in micro seconds\&. (it must have been started and stopped)\&. .SS "void qb_util_timespec_from_epoch_get (struct timespec * ts)" .PP Get the time in timespec since epoch\&. .PP \fBParameters:\fP .RS 4 \fIts\fP (out) the timespec .RE .PP \fBReturns:\fP .RS 4 status (0 == ok, -errno on error) .RE .PP .SH "Variable Documentation" .PP .SS "const struct \fBqb_version\fP qb_ver" .SS "const char* const qb_ver_str" .PP Complete library versioning info as a string\&. .SH "Author" .PP Generated automatically by Doxygen for libqb from the source code\&.