qbutil.h File Reference

These are some convience functions used throughout libqb. More...

#include <pthread.h>
#include <stdint.h>
#include <unistd.h>
#include <qb/qbdefs.h>

Include dependency graph for qbutil.h:

This graph shows which files directly or indirectly include this file:

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. More...
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)
	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

These are some convience functions used throughout libqb.

Author:: Angus Salkeld <asalkeld@redhat.com>

Locking

Time functions

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

Examples:: ipcclient.c.

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	(	int	errnum,
		char *	buf,
		size_t	buflen
	)

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_t type )

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_t	ms
	)

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_t fn )

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

Examples:: ipcclient.c.

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

Examples:: ipcclient.c.

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_t	max_splits,
		uint32_t	options
	)

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.

Examples:: ipcclient.c.

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.

Examples:: ipcclient.c.

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

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)

qbutil.h File Reference

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation