Scroll to navigation

qbhdb.h(3) libqb 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.
Thu Jul 30 2020 Version 1.0.6