.TH "qbutil.h" 3 "Thu Dec 21 2017" "Version 1.0.3" "libqb" \" -*- nroff -*-
.ad l
.nh
.SH NAME
qbutil.h \- 
.PP
These are some convience functions used throughout libqb\&.  

.SH SYNOPSIS
.br
.PP
\fC#include <pthread\&.h>\fP
.br
\fC#include <stdint\&.h>\fP
.br
\fC#include <unistd\&.h>\fP
.br
\fC#include <qb/qbdefs\&.h>\fP
.br

.SS "Data Structures"

.in +1c
.ti -1c
.RI "struct \fBqb_version\fP"
.br
.RI "\fIStructured library versioning info\&. \fP"
.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 }"
.br
.RI "\fIQB_THREAD_LOCK_SHORT is a short term lock (spinlock if available on your system) QB_THREAD_LOCK_LONG is a mutex\&. \fP"
.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 "\fICreate a new lock of the given type\&. \fP"
.ti -1c
.RI "int32_t \fBqb_thread_lock\fP (\fBqb_thread_lock_t\fP *tl)"
.br
.RI "\fICalls either pthread_mutex_lock() or pthread_spin_lock()\&. \fP"
.ti -1c
.RI "int32_t \fBqb_thread_trylock\fP (\fBqb_thread_lock_t\fP *tl)"
.br
.RI "\fICalls either pthread_mutex_trylock() or pthread_spin_trylock()\&. \fP"
.ti -1c
.RI "int32_t \fBqb_thread_unlock\fP (\fBqb_thread_lock_t\fP *tl)"
.br
.RI "\fICalls either pthread_mutex_unlock() or pthread_spin_unlock\&. \fP"
.ti -1c
.RI "int32_t \fBqb_thread_lock_destroy\fP (\fBqb_thread_lock_t\fP *tl)"
.br
.RI "\fICalls either pthread_mutex_destro() or pthread_spin_destroy()\&. \fP"
.ti -1c
.RI "void \fBqb_util_set_log_function\fP (\fBqb_util_log_fn_t\fP fn) \fBQB_GNUC_DEPRECATED\fP"
.br
.RI "\fIUse this function to output libqb internal log message as you wish\&. \fP"
.ti -1c
.RI "void \fBqb_timespec_add_ms\fP (struct timespec *ts, int32_t ms)"
.br
.RI "\fIAdd milliseconds onto the timespec\&. \fP"
.ti -1c
.RI "uint64_t \fBqb_util_nano_current_get\fP (void)"
.br
.RI "\fIGet the current number of nano secounds produced by the systems incrementing clock (CLOCK_MONOTOMIC if available)\&. \fP"
.ti -1c
.RI "uint64_t \fBqb_util_nano_monotonic_hz\fP (void)"
.br
.RI "\fIGet the frequence of the clock used in \fBqb_util_nano_current_get()\fP\&. \fP"
.ti -1c
.RI "uint64_t \fBqb_util_nano_from_epoch_get\fP (void)"
.br
.RI "\fIGet the time in nano seconds since epoch\&. \fP"
.ti -1c
.RI "void \fBqb_util_timespec_from_epoch_get\fP (struct timespec *ts)"
.br
.RI "\fIGet the time in timespec since epoch\&. \fP"
.ti -1c
.RI "char * \fBqb_strerror_r\fP (int errnum, char *buf, size_t buflen)"
.br
.RI "\fIstrerror_r replacement\&. \fP"
.ti -1c
.RI "\fBqb_util_stopwatch_t\fP * \fBqb_util_stopwatch_create\fP (void)"
.br
.RI "\fICreate a Stopwatch (to time operations) \fP"
.ti -1c
.RI "void \fBqb_util_stopwatch_free\fP (\fBqb_util_stopwatch_t\fP *sw)"
.br
.RI "\fIFree the stopwatch\&. \fP"
.ti -1c
.RI "void \fBqb_util_stopwatch_start\fP (\fBqb_util_stopwatch_t\fP *sw)"
.br
.RI "\fIStart the stopwatch\&. \fP"
.ti -1c
.RI "void \fBqb_util_stopwatch_stop\fP (\fBqb_util_stopwatch_t\fP *sw)"
.br
.RI "\fIStop the stopwatch\&. \fP"
.ti -1c
.RI "uint64_t \fBqb_util_stopwatch_us_elapsed_get\fP (\fBqb_util_stopwatch_t\fP *sw)"
.br
.RI "\fIGet the elapsed time in micro seconds\&. \fP"
.ti -1c
.RI "float \fBqb_util_stopwatch_sec_elapsed_get\fP (\fBqb_util_stopwatch_t\fP *sw)"
.br
.RI "\fIGet the elapsed time in seconds\&. \fP"
.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 "\fICreate a new time split (or lap time) \fP"
.ti -1c
.RI "uint32_t \fBqb_util_stopwatch_split_last\fP (\fBqb_util_stopwatch_t\fP *sw)"
.br
.RI "\fIGet the last split index to be used by \fBqb_util_stopwatch_time_split_get()\fP \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 "\fIRead the time split (in us) from 'receint' to 'older'\&. \fP"
.in -1c
.SS "Variables"

.in +1c
.ti -1c
.RI "struct \fBqb_version\fP \fBqb_ver\fP"
.br
.ti -1c
.RI "const char *const \fBqb_ver_str\fP"
.br
.RI "\fIComplete library versioning info as a string\&. \fP"
.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 (interrnum, char *buf, size_tbuflen)"

.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\fPtype)"

.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_tms)"

.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\fPfn)"

.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_tmax_splits, uint32_toptions)"

.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_treceint, uint32_tolder)"

.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 "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\&.