NAME

       qbhdb.h - The handle database is for reference counting objects.

SYNOPSIS

       #include <stdlib.h>
       #include <stdint.h>
       #include <inttypes.h>
       #include <qb/qbarray.h>

   Data Structures
       struct qb_hdb_handle
       struct qb_hdb

   Macros
       #define _GNU_SOURCE
       #define QB_HDB_D_FORMAT   '%' PRIu64
       #define QB_HDB_X_FORMAT   '%' PRIx64
       #define QB_HDB_DECLARE(database_name,  destructor_function)
           Convience macro for declaring a file scoped handle database.

   Typedefs
       typedef uint64_t qb_handle_t
           Generic handle type is 64 bits.

   Functions
       void qb_hdb_create (struct qb_hdb *hdb)
           Create a new database.
       void qb_hdb_destroy (struct qb_hdb *hdb)
           Destroy a handle database.
       int32_t qb_hdb_handle_create (struct qb_hdb *hdb, int32_t instance_size, qb_handle_t
           *handle_id_out)
           Create a new handle.
       int32_t qb_hdb_handle_get (struct qb_hdb *hdb, qb_handle_t handle_in, void **instance)
           Get the instance associated with this handle and increase it's refcount.
       int32_t qb_hdb_handle_get_always (struct qb_hdb *hdb, qb_handle_t handle_in, void
           **instance)
           Get the instance associated with this handle and increase it's refcount.
       int32_t qb_hdb_handle_put (struct qb_hdb *hdb, qb_handle_t handle_in)
           Put the instance associated with this handle and decrease it's refcount.
       int32_t qb_hdb_handle_destroy (struct qb_hdb *hdb, qb_handle_t handle_in)
           Request the destruction of the object.
       int32_t qb_hdb_handle_refcount_get (struct qb_hdb *hdb, qb_handle_t handle_in)
           Get the current refcount.
       void qb_hdb_iterator_reset (struct qb_hdb *hdb)
           Reset the iterator.
       int32_t qb_hdb_iterator_next (struct qb_hdb *hdb, void **instance, qb_handle_t *handle)
           Get the next object and increament it's refcount.
       uint32_t qb_hdb_base_convert (qb_handle_t handle)
       uint64_t qb_hdb_nocheck_convert (uint32_t handle)

Detailed Description

       The handle database is for reference counting objects.

Macro Definition Documentation

   #define _GNU_SOURCE
   #define QB_HDB_D_FORMAT   '%' PRIu64
   #define QB_HDB_DECLARE(database_name, destructor_function)
       Value:

       static struct qb_hdb (database_name) = {                                  .handle_count    = 0,                                                    .handles = NULL,                                                 .iterator        = 0,                                                    .destructor      = destructor_function,                                  .first_run       = QB_TRUE                                       };                                                                      .fi

       Convience macro for declaring a file scoped handle database.

       QB_HDB_DECLARE(my_handle_database, NULL);

   #define QB_HDB_X_FORMAT   '%' PRIx64

Typedef Documentation

   typedef uint64_t qb_handle_t
       Generic handle type is 64 bits.

Function Documentation

   uint32_t qb_hdb_base_convert (qb_handle_t handle)
   void qb_hdb_create (struct qb_hdb * hdb)
       Create a new database.

       Parameters:
           hdb the database to init.

   void qb_hdb_destroy (struct qb_hdb * hdb)
       Destroy a handle database.

       Parameters:
           hdb the database to destroy.

   int32_t qb_hdb_handle_create (struct qb_hdb * hdb, int32_t instance_size, qb_handle_t *
       handle_id_out)
       Create a new handle.

       Parameters:
           hdb the database instance
           instance_size size of the object to malloc
           handle_id_out new handle

       Returns:
           (0 == ok, -errno failure)

   int32_t qb_hdb_handle_destroy (struct qb_hdb * hdb, qb_handle_t handle_in)
       Request the destruction of the object. When the refcount is 0, it will be destroyed.

       Parameters:
           handle_in the handle
           hdb the database instance

       Returns:
           (0 == ok, -errno failure)

   int32_t qb_hdb_handle_get (struct qb_hdb * hdb, qb_handle_t handle_in, void ** instance)
       Get the instance associated with this handle and increase it's refcount.

       Parameters:
           handle_in the handle
           hdb the database instance
           instance (out) pointer to the desired object.

       Returns:
           (0 == ok, -errno failure)

   int32_t qb_hdb_handle_get_always (struct qb_hdb * hdb, qb_handle_t handle_in, void **
       instance)
       Get the instance associated with this handle and increase it's refcount.

       Parameters:
           handle_in the handle
           hdb the database instance
           instance (out) pointer to the desired object.

       Returns:
           (0 == ok, -errno failure)

   int32_t qb_hdb_handle_put (struct qb_hdb * hdb, qb_handle_t handle_in)
       Put the instance associated with this handle and decrease it's refcount.

       Parameters:
           handle_in the handle
           hdb the database instance

       Returns:
           (0 == ok, -errno failure)

   int32_t qb_hdb_handle_refcount_get (struct qb_hdb * hdb, qb_handle_t handle_in)
       Get the current refcount.

       Parameters:
           handle_in the handle
           hdb the database instance

       Returns:
           (>= 0 is the refcount, -errno failure)

   int32_t qb_hdb_iterator_next (struct qb_hdb * hdb, void ** instance, qb_handle_t * handle)
       Get the next object and increament it's refcount. Remember to call qb_hdb_handle_put()

       Parameters:
           hdb the database instance
           handle (out) the handle
           instance (out) pointer to the desired object.

       Returns:
           (0 == ok, -errno failure)

   void qb_hdb_iterator_reset (struct qb_hdb * hdb)
       Reset the iterator.

       Parameters:
           hdb the database instance

   uint64_t qb_hdb_nocheck_convert (uint32_t handle)

Author

       Generated automatically by Doxygen for libqb from the source code.