qbhdb.h(3)

NAME
qbhdb.h

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.

Note
    Historically, handle database implementation also served internal needs of libqb (e.g. for IPC services tracking), which was eventually replaced with indirection-less reference counters and their direct modifications.

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)

Note
    This is currently an alias to qb_hdb_handle_get.

  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.