qbutil.h (3)

#include <pthread.h>

#include <stdint.h>

#include <unistd.h>

#include <qb/qbdefs.h>

Defines

#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'.

Author:

Angus Salkeld <[email protected]>

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);

#define \fBQB_UTIL_SW_OVERWRITE\fP 0x01

typedef struct qb_thread_lock_s \fBqb_thread_lock_t\fP

typedef void(* \fBqb_util_log_fn_t\fP)(const char *file_name, int32_t file_line, int32_t severity, const char *msg)

typedef struct qb_util_stopwatch \fBqb_util_stopwatch_t\fP

enum \fBqb_thread_lock_type_t\fP

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

char* \fBqb_strerror_r\fP (interrnum, char *buf, size_tbuflen)

strerror_r replacement.

int32_t \fBqb_thread_lock\fP (\fBqb_thread_lock_t\fP *tl)

Calls either pthread_mutex_lock() or pthread_spin_lock().

\fBqb_thread_lock_t\fP* \fBqb_thread_lock_create\fP (\fBqb_thread_lock_type_t\fPtype)

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 \fBqb_thread_lock_destroy\fP (\fBqb_thread_lock_t\fP *tl)

Calls either pthread_mutex_destro() or pthread_spin_destroy().

int32_t \fBqb_thread_trylock\fP (\fBqb_thread_lock_t\fP *tl)

Calls either pthread_mutex_trylock() or pthread_spin_trylock().

int32_t \fBqb_thread_unlock\fP (\fBqb_thread_lock_t\fP *tl)

Calls either pthread_mutex_unlock() or pthread_spin_unlock.

void \fBqb_timespec_add_ms\fP (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 \fBqb_util_nano_current_get\fP (void)

Get the current number of nano secounds produced by the systems incrementing clock (CLOCK_MONOTOMIC if available).

uint64_t \fBqb_util_nano_from_epoch_get\fP (void)

Get the time in nano seconds since epoch.

uint64_t \fBqb_util_nano_monotonic_hz\fP (void)

Get the frequence of the clock used in qb_util_nano_current_get().

void \fBqb_util_set_log_function\fP (\fBqb_util_log_fn_t\fPfn)

Use this function to output libqb internal log message as you wish.

\fBqb_util_stopwatch_t\fP* \fBqb_util_stopwatch_create\fP (void)

Create a Stopwatch (to time operations)

void \fBqb_util_stopwatch_free\fP (\fBqb_util_stopwatch_t\fP *sw)

Free the stopwatch.

float \fBqb_util_stopwatch_sec_elapsed_get\fP (\fBqb_util_stopwatch_t\fP *sw)

Get the elapsed time in seconds. (it must have been started and stopped).

uint64_t \fBqb_util_stopwatch_split\fP (\fBqb_util_stopwatch_t\fP *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 \fBqb_util_stopwatch_split_ctl\fP (\fBqb_util_stopwatch_t\fP *sw, uint32_tmax_splits, uint32_toptions) \fBParameters:\fP

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 \fBqb_util_stopwatch_split_last\fP (\fBqb_util_stopwatch_t\fP *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 \fBqb_util_stopwatch_start\fP (\fBqb_util_stopwatch_t\fP *sw)

Start the stopwatch. This also acts as a reset. Essentially it sets the starting time and clears the splits.

void \fBqb_util_stopwatch_stop\fP (\fBqb_util_stopwatch_t\fP *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 \fBqb_util_stopwatch_time_split_get\fP (\fBqb_util_stopwatch_t\fP *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 \fBqb_util_stopwatch_us_elapsed_get\fP (\fBqb_util_stopwatch_t\fP *sw)

Get the elapsed time in micro seconds. (it must have been started and stopped).

void \fBqb_util_timespec_from_epoch_get\fP (struct timespec *ts)

Get the time in timespec since epoch. Parameters:

ts (out) the timespec

Returns:

status (0 == ok, -errno on error)

Generated automatically by Doxygen for libqb from the source code.