.TH "qbhdb.h" 3 "Fri Apr 26 2019" "Version 1.0.5" "libqb" \" -*- nroff -*-
.ad l
.nh
.SH NAME
qbhdb.h \- 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 "Convience macro for declaring a file scoped handle database\&. "
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef uint64_t \fBqb_handle_t\fP"
.br
.RI "Generic handle type is 64 bits\&. "
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "void \fBqb_hdb_create\fP (struct \fBqb_hdb\fP *hdb)"
.br
.RI "Create a new database\&. "
.ti -1c
.RI "void \fBqb_hdb_destroy\fP (struct \fBqb_hdb\fP *hdb)"
.br
.RI "Destroy a handle database\&. "
.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 "Create a new handle\&. "
.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 "Get the instance associated with this handle and increase it's refcount\&. "
.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 "Get the instance associated with this handle and increase it's refcount\&. "
.ti -1c
.RI "int32_t \fBqb_hdb_handle_put\fP (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fP handle_in)"
.br
.RI "Put the instance associated with this handle and decrease it's refcount\&. "
.ti -1c
.RI "int32_t \fBqb_hdb_handle_destroy\fP (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fP handle_in)"
.br
.RI "Request the destruction of the object\&. "
.ti -1c
.RI "int32_t \fBqb_hdb_handle_refcount_get\fP (struct \fBqb_hdb\fP *hdb, \fBqb_handle_t\fP handle_in)"
.br
.RI "Get the current refcount\&. "
.ti -1c
.RI "void \fBqb_hdb_iterator_reset\fP (struct \fBqb_hdb\fP *hdb)"
.br
.RI "Reset the iterator\&. "
.ti -1c
.RI "int32_t \fBqb_hdb_iterator_next\fP (struct \fBqb_hdb\fP *hdb, void **instance, \fBqb_handle_t\fP *handle)"
.br
.RI "Get the next object and increament it's refcount\&. "
.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\fP handle)"

.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_t instance_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\fP handle_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\fP handle_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\fP handle_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\fP handle_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\fP handle_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_t handle)"

.SH "Author"
.PP 
Generated automatically by Doxygen for libqb from the source code\&.