qbhdb.h(3)

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.

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.