Provided by: libqb-dev_1.0.1-1ubuntu1_amd64 bug

NAME

       qbutil.h - These are some convience functions used throughout libqb.

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

       These are some convience functions used throughout libqb.

       Author:
           Angus Salkeld asalkeld@redhat.com

       Lockingqb_thread_lock_create()qb_thread_lock()qb_thread_trylock()qb_thread_unlock()qb_thread_lock_destroy()

       Time functionsqb_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 (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)

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

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

Author

       Generated automatically by Doxygen for libqb from the source code.