.TH "qbhdb.h" 3 "Thu Dec 21 2017" "Version 1.0.3" "libqb" \" -*- nroff -*-
.ad l
.nh
.SH NAME
qbhdb.h \-
.PP
The handle database is for reference counting objects\&.
.SH SYNOPSIS
.br
.PP
\fC#include <stdlib\&.h>\fP
.br
\fC#include <stdint\&.h>\fP
.br
\fC#include <inttypes\&.h>\fP
.br
\fC#include <qb/qbarray\&.h>\fP
.br
.SS "Data Structures"
.in +1c
.ti -1c
.RI "struct \fBqb_hdb_handle\fP"
.br
.ti -1c
.RI "struct \fBqb_hdb\fP"
.br
.in -1c
.SS "Macros"
.in +1c
.ti -1c
.RI "#define \fB_GNU_SOURCE\fP"
.br
.ti -1c
.RI "#define \fBQB_HDB_D_FORMAT\fP '%' PRIu64"
.br
.ti -1c
.RI "#define \fBQB_HDB_X_FORMAT\fP '%' PRIx64"
.br
.ti -1c
.RI "#define \fBQB_HDB_DECLARE\fP(database_name, destructor_function)"
.br
.RI "\fIConvience macro for declaring a file scoped handle database\&. \fP"
.in -1c
.SS "Typedefs"
.in +1c
.ti -1c
.RI "typedef uint64_t \fBqb_handle_t\fP"
.br
.RI "\fIGeneric handle type is 64 bits\&. \fP"
.in -1c
.SS "Functions"
.in +1c
.ti -1c
.RI "void \fBqb_hdb_create\fP (struct \fBqb_hdb\fP *hdb)"
.br
.RI "\fICreate a new database\&. \fP"
.ti -1c
.RI "void \fBqb_hdb_destroy\fP (struct \fBqb_hdb\fP *hdb)"
.br
.RI "\fIDestroy a handle database\&. \fP"
.ti -1c
.RI "int32_t \fBqb_hdb_handle_create\fP (struct \fBqb_hdb\fP *hdb, int32_t instance_size, \fBqb_handle_t\fP *handle_id_out)"
.br
.RI "\fICreate a new handle\&. \fP"
.ti -1c
.RI "int32_t \fBqb_hdb_handle_get\fP (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fP handle_in, void **instance)"
.br
.RI "\fIGet the instance associated with this handle and increase it's refcount\&. \fP"
.ti -1c
.RI "int32_t \fBqb_hdb_handle_get_always\fP (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fP handle_in, void **instance)"
.br
.RI "\fIGet the instance associated with this handle and increase it's refcount\&. \fP"
.ti -1c
.RI "int32_t \fBqb_hdb_handle_put\fP (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fP handle_in)"
.br
.RI "\fIPut the instance associated with this handle and decrease it's refcount\&. \fP"
.ti -1c
.RI "int32_t \fBqb_hdb_handle_destroy\fP (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fP handle_in)"
.br
.RI "\fIRequest the destruction of the object\&. \fP"
.ti -1c
.RI "int32_t \fBqb_hdb_handle_refcount_get\fP (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fP handle_in)"
.br
.RI "\fIGet the current refcount\&. \fP"
.ti -1c
.RI "void \fBqb_hdb_iterator_reset\fP (struct \fBqb_hdb\fP *hdb)"
.br
.RI "\fIReset the iterator\&. \fP"
.ti -1c
.RI "int32_t \fBqb_hdb_iterator_next\fP (struct \fBqb_hdb\fP *hdb, void **instance, \fBqb_handle_t\fP *handle)"
.br
.RI "\fIGet the next object and increament it's refcount\&. \fP"
.ti -1c
.RI "uint32_t \fBqb_hdb_base_convert\fP (\fBqb_handle_t\fP handle)"
.br
.ti -1c
.RI "uint64_t \fBqb_hdb_nocheck_convert\fP (uint32_t handle)"
.br
.in -1c
.SH "Detailed Description"
.PP
The handle database is for reference counting objects\&.
.PP
\fBNote:\fP
.RS 4
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\&.
.RE
.PP
.SH "Macro Definition Documentation"
.PP
.SS "#define _GNU_SOURCE"
.SS "#define QB_HDB_D_FORMAT '%' PRIu64"
.SS "#define QB_HDB_DECLARE(database_name, destructor_function)"
\fBValue:\fP
.PP
.nf
static struct qb_hdb (database_name) = { \
\&.handle_count = 0, \
\&.handles = NULL, \
\&.iterator = 0, \
\&.destructor = destructor_function, \
\&.first_run = QB_TRUE \
}; \
.fi
.PP
Convience macro for declaring a file scoped handle database\&.
.PP
.nf
* QB_HDB_DECLARE(my_handle_database, NULL);
*
.fi
.PP
.SS "#define QB_HDB_X_FORMAT '%' PRIx64"
.SH "Typedef Documentation"
.PP
.SS "typedef uint64_t \fBqb_handle_t\fP"
.PP
Generic handle type is 64 bits\&.
.SH "Function Documentation"
.PP
.SS "uint32_t qb_hdb_base_convert (\fBqb_handle_t\fPhandle)"
.SS "void qb_hdb_create (struct \fBqb_hdb\fP *hdb)"
.PP
Create a new database\&.
.PP
\fBParameters:\fP
.RS 4
\fIhdb\fP the database to init\&.
.RE
.PP
.SS "void qb_hdb_destroy (struct \fBqb_hdb\fP *hdb)"
.PP
Destroy a handle database\&.
.PP
\fBParameters:\fP
.RS 4
\fIhdb\fP the database to destroy\&.
.RE
.PP
.SS "int32_t qb_hdb_handle_create (struct \fBqb_hdb\fP *hdb, int32_tinstance_size, \fBqb_handle_t\fP *handle_id_out)"
.PP
Create a new handle\&.
.PP
\fBParameters:\fP
.RS 4
\fIhdb\fP the database instance
.br
\fIinstance_size\fP size of the object to malloc
.br
\fIhandle_id_out\fP new handle
.RE
.PP
\fBReturns:\fP
.RS 4
(0 == ok, -errno failure)
.RE
.PP
.SS "int32_t qb_hdb_handle_destroy (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fPhandle_in)"
.PP
Request the destruction of the object\&. When the refcount is 0, it will be destroyed\&.
.PP
\fBParameters:\fP
.RS 4
\fIhandle_in\fP the handle
.br
\fIhdb\fP the database instance
.RE
.PP
\fBReturns:\fP
.RS 4
(0 == ok, -errno failure)
.RE
.PP
.SS "int32_t qb_hdb_handle_get (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fPhandle_in, void **instance)"
.PP
Get the instance associated with this handle and increase it's refcount\&.
.PP
\fBParameters:\fP
.RS 4
\fIhandle_in\fP the handle
.br
\fIhdb\fP the database instance
.br
\fIinstance\fP (out) pointer to the desired object\&.
.RE
.PP
\fBReturns:\fP
.RS 4
(0 == ok, -errno failure)
.RE
.PP
.SS "int32_t qb_hdb_handle_get_always (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fPhandle_in, void **instance)"
.PP
Get the instance associated with this handle and increase it's refcount\&.
.PP
\fBParameters:\fP
.RS 4
\fIhandle_in\fP the handle
.br
\fIhdb\fP the database instance
.br
\fIinstance\fP (out) pointer to the desired object\&.
.RE
.PP
\fBReturns:\fP
.RS 4
(0 == ok, -errno failure)
.RE
.PP
\fBNote:\fP
.RS 4
This is currently an alias to \fBqb_hdb_handle_get\fP\&.
.RE
.PP
.SS "int32_t qb_hdb_handle_put (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fPhandle_in)"
.PP
Put the instance associated with this handle and decrease it's refcount\&.
.PP
\fBParameters:\fP
.RS 4
\fIhandle_in\fP the handle
.br
\fIhdb\fP the database instance
.RE
.PP
\fBReturns:\fP
.RS 4
(0 == ok, -errno failure)
.RE
.PP
.SS "int32_t qb_hdb_handle_refcount_get (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fPhandle_in)"
.PP
Get the current refcount\&.
.PP
\fBParameters:\fP
.RS 4
\fIhandle_in\fP the handle
.br
\fIhdb\fP the database instance
.RE
.PP
\fBReturns:\fP
.RS 4
(>= 0 is the refcount, -errno failure)
.RE
.PP
.SS "int32_t qb_hdb_iterator_next (struct \fBqb_hdb\fP *hdb, void **instance, \fBqb_handle_t\fP *handle)"
.PP
Get the next object and increament it's refcount\&. Remember to call \fBqb_hdb_handle_put()\fP
.PP
\fBParameters:\fP
.RS 4
\fIhdb\fP the database instance
.br
\fIhandle\fP (out) the handle
.br
\fIinstance\fP (out) pointer to the desired object\&.
.RE
.PP
\fBReturns:\fP
.RS 4
(0 == ok, -errno failure)
.RE
.PP
.SS "void qb_hdb_iterator_reset (struct \fBqb_hdb\fP *hdb)"
.PP
Reset the iterator\&.
.PP
\fBParameters:\fP
.RS 4
\fIhdb\fP the database instance
.RE
.PP
.SS "uint64_t qb_hdb_nocheck_convert (uint32_thandle)"
.SH "Author"
.PP
Generated automatically by Doxygen for libqb from the source code\&.