qbutil.h(3) libqb qbutil.h(3)NAMEqbutil.h-
SYNOPSIS
#include <pthread.h>
#include <stdint.h>
#include <unistd.h>
#include <qb/qbdefs.h>
Macros
#define QB_UTIL_SW_OVERWRITE 0x01
Typedefs
typedef struct qb_thread_lock_s qb_thread_lock_t
typedef void(* qb_util_log_fn_t )(const char *file_name, int32_t
file_line, int32_t severity, const char *msg)
typedef struct qb_util_stopwatch qb_util_stopwatch_t
Enumerations
enum qb_thread_lock_type_t { QB_THREAD_LOCK_SHORT, QB_THREAD_LOCK_LONG
}
QB_THREAD_LOCK_SHORT is a short term lock (spinlock if available on
your system) QB_THREAD_LOCK_LONG is a mutex.
Functions
qb_thread_lock_t * qb_thread_lock_create (qb_thread_lock_type_t type)
Create a new lock of the given type.
int32_t qb_thread_lock (qb_thread_lock_t *tl)
Calls either pthread_mutex_lock() or pthread_spin_lock().
int32_t qb_thread_trylock (qb_thread_lock_t *tl)
Calls either pthread_mutex_trylock() or pthread_spin_trylock().
int32_t qb_thread_unlock (qb_thread_lock_t *tl)
Calls either pthread_mutex_unlock() or pthread_spin_unlock.
int32_t qb_thread_lock_destroy (qb_thread_lock_t *tl)
Calls either pthread_mutex_destro() or pthread_spin_destroy().
void qb_util_set_log_function (qb_util_log_fn_t fn) QB_GNUC_DEPRECATED
Use this function to output libqb internal log message as you wish.
void qb_timespec_add_ms (struct timespec *ts, int32_t ms)
Add milliseconds onto the timespec.
uint64_t qb_util_nano_current_get (void)
Get the current number of nano secounds produced by the systems
incrementing clock (CLOCK_MONOTOMIC if available).
uint64_t qb_util_nano_monotonic_hz (void)
Get the frequence of the clock used in qb_util_nano_current_get().
uint64_t qb_util_nano_from_epoch_get (void)
Get the time in nano seconds since epoch.
void qb_util_timespec_from_epoch_get (struct timespec *ts)
Get the time in timespec since epoch.
char * qb_strerror_r (int errnum, char *buf, size_t buflen)
strerror_r replacement.
qb_util_stopwatch_t * qb_util_stopwatch_create (void)
Create a Stopwatch (to time operations)
void qb_util_stopwatch_free (qb_util_stopwatch_t *sw)
Free the stopwatch.
void qb_util_stopwatch_start (qb_util_stopwatch_t *sw)
Start the stopwatch.
void qb_util_stopwatch_stop (qb_util_stopwatch_t *sw)
Stop the stopwatch.
uint64_t qb_util_stopwatch_us_elapsed_get (qb_util_stopwatch_t *sw)
Get the elapsed time in micro seconds.
float qb_util_stopwatch_sec_elapsed_get (qb_util_stopwatch_t *sw)
Get the elapsed time in seconds.
int32_t qb_util_stopwatch_split_ctl (qb_util_stopwatch_t *sw, uint32_t
max_splits, uint32_t options)
uint64_t qb_util_stopwatch_split (qb_util_stopwatch_t *sw)
Create a new time split (or lap time)
uint32_t qb_util_stopwatch_split_last (qb_util_stopwatch_t *sw)
Get the last split index to be used by
qb_util_stopwatch_time_split_get()
uint64_t qb_util_stopwatch_time_split_get (qb_util_stopwatch_t *sw,
uint32_t receint, uint32_t older)
Read the time split (in us) from 'receint' to 'older'.
Detailed Description
Author:
Angus Salkeld asalkeld@redhat.com
These are some convience functions used throughout libqb.
Locking
· qb_thread_lock_create()
· qb_thread_lock()
· qb_thread_trylock()
· qb_thread_unlock()
· qb_thread_lock_destroy()
Time functions
· qb_timespec_add_ms()
· qb_util_nano_current_get()
· qb_util_nano_monotonic_hz()
· qb_util_nano_from_epoch_get()
· qb_util_timespec_from_epoch_get()
Basic Stopwatch
* 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);
*
Stopwatch with splits
Setup a stopwatch with space for 3 splits.
* 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);
*
Macro Definition Documentation
#define QB_UTIL_SW_OVERWRITE 0x01
Typedef Documentation
typedef struct qb_thread_lock_s qb_thread_lock_t
typedef void(* qb_util_log_fn_t)(const char *file_name, int32_t file_line,
int32_t severity, const char *msg)
typedef struct qb_util_stopwatch qb_util_stopwatch_t
Enumeration Type Documentation
enum qb_thread_lock_type_t
QB_THREAD_LOCK_SHORT is a short term lock (spinlock if available on
your system) QB_THREAD_LOCK_LONG is a mutex.
Enumerator
QB_THREAD_LOCK_SHORT
QB_THREAD_LOCK_LONG
Function Documentation
char* qb_strerror_r (interrnum, char *buf, size_tbuflen)
strerror_r replacement.
int32_t qb_thread_lock (qb_thread_lock_t *tl)
Calls either pthread_mutex_lock() or pthread_spin_lock().
qb_thread_lock_t* qb_thread_lock_create (qb_thread_lock_type_ttype)
Create a new lock of the given type.
Parameters:
type QB_THREAD_LOCK_SHORT == spinlock (where available, else mutex)
QB_THREAD_LOCK_LONG == mutex
Returns:
pointer to qb_thread_lock_type_t or NULL on error.
int32_t qb_thread_lock_destroy (qb_thread_lock_t *tl)
Calls either pthread_mutex_destro() or pthread_spin_destroy().
int32_t qb_thread_trylock (qb_thread_lock_t *tl)
Calls either pthread_mutex_trylock() or pthread_spin_trylock().
int32_t qb_thread_unlock (qb_thread_lock_t *tl)
Calls either pthread_mutex_unlock() or pthread_spin_unlock.
void qb_timespec_add_ms (struct timespec *ts, int32_tms)
Add milliseconds onto the timespec.
Parameters:
ts the ts to add to
ms the amount of milliseconds to increment ts
uint64_t qb_util_nano_current_get (void)
Get the current number of nano secounds produced by the systems
incrementing clock (CLOCK_MONOTOMIC if available).
uint64_t qb_util_nano_from_epoch_get (void)
Get the time in nano seconds since epoch.
uint64_t qb_util_nano_monotonic_hz (void)
Get the frequence of the clock used in qb_util_nano_current_get().
void qb_util_set_log_function (qb_util_log_fn_tfn)
Use this function to output libqb internal log message as you wish.
qb_util_stopwatch_t* qb_util_stopwatch_create (void)
Create a Stopwatch (to time operations)
void qb_util_stopwatch_free (qb_util_stopwatch_t *sw)
Free the stopwatch.
float qb_util_stopwatch_sec_elapsed_get (qb_util_stopwatch_t *sw)
Get the elapsed time in seconds. (it must have been started and
stopped).
uint64_t qb_util_stopwatch_split (qb_util_stopwatch_t *sw)
Create a new time split (or lap time)
Parameters:
sw the stopwatch
Return values:
the relative split time in micro seconds
0 if no more splits available
int32_t qb_util_stopwatch_split_ctl (qb_util_stopwatch_t *sw,
uint32_tmax_splits, uint32_toptions)
Parameters:
sw the stopwatch
max_splits maximum number of time splits
options (0 or QB_UTIL_SW_OVERWRITE )
Return values:
0 on success
-errno on failure
uint32_t qb_util_stopwatch_split_last (qb_util_stopwatch_t *sw)
Get the last split index to be used by
qb_util_stopwatch_time_split_get()
Note:
this is zero based
Parameters:
sw the stopwatch
Returns:
the last entry index
void qb_util_stopwatch_start (qb_util_stopwatch_t *sw)
Start the stopwatch. This also acts as a reset. Essentially it sets the
starting time and clears the splits.
void qb_util_stopwatch_stop (qb_util_stopwatch_t *sw)
Stop the stopwatch. This just allows you to get the elapsed time. So
you can call this multiple times. Do not call qb_util_stopwatch_start()
unless you want to reset the stopwatch.
uint64_t qb_util_stopwatch_time_split_get (qb_util_stopwatch_t *sw,
uint32_treceint, uint32_tolder)
Read the time split (in us) from 'receint' to 'older'. If older ==
receint then the cumulated split will be returned (from the stopwatch
start).
Parameters:
sw the stopwatch
receint split
older split
Return values:
the split time in micro seconds
0 if not a valid split
uint64_t qb_util_stopwatch_us_elapsed_get (qb_util_stopwatch_t *sw)
Get the elapsed time in micro seconds. (it must have been started and
stopped).
void qb_util_timespec_from_epoch_get (struct timespec *ts)
Get the time in timespec since epoch.
Parameters:
ts (out) the timespec
Returns:
status (0 == ok, -errno on error)
Author
Generated automatically by Doxygen for libqb from the source code.
Version 0.16.0 Mon May 12 2014 qbutil.h(3)