The qDecoder Project

qHashtbl.c File Reference

Hash-table Data Structure API. More...


Functions

Q_HASHTBL * qHashtbl (int max, bool resize, int threshold)
 Initialize dynamic-hash table.
static void _lock (Q_HASHTBL *tbl)
 Q_HASHtbl->lock(): Enter critical section.
static void _unlock (Q_HASHTBL *tbl)
 Q_HASHTBL->unlock(): Leave critical section.
static bool _put (Q_HASHTBL *tbl, const char *name, const void *data, size_t size)
 Q_HASHTBL->put(): Put object into hash table.
static bool _putStr (Q_HASHTBL *tbl, const char *name, const char *str)
 Q_HASHTBL->putStr(): Put string into hash table.
static bool _putInt (Q_HASHTBL *tbl, const char *name, const int num)
 Q_HASHTBL->putInt(): Put integer into hash table.
static void * _get (Q_HASHTBL *tbl, const char *name, size_t *size, bool newmem)
 Q_HASHTBL->get(): Get object from hash table.
static char * _getStr (Q_HASHTBL *tbl, const char *name, bool newmem)
 Q_HASHTBL->getStr(): Get string from hash table.
static int _getInt (Q_HASHTBL *tbl, const char *name)
 Q_HASHTBL->getInt(): Get integer from hash table.
static bool _getNext (Q_HASHTBL *tbl, Q_NOBJ_T *obj, int *idx, bool newmem)
 Q_HASHTBL->getNext(): Get next key name.
static bool _remove (Q_HASHTBL *tbl, const char *name)
 Q_HASHTBL->remove(): Remove key from hash table.
static int _getNum (Q_HASHTBL *tbl)
 Q_HASHTBL->getNum(): get number of objects stored.
static int _getMax (Q_HASHTBL *tbl)
 Q_HASHTBL->getMax(): Get number of object slots.
bool _truncate (Q_HASHTBL *tbl)
 Q_HASHTBL->truncate(): Truncate hash table.
bool _resize (Q_HASHTBL *tbl, int max)
 Q_HASHTBL->resize(): Resize dynamic-hash table.
bool _print (Q_HASHTBL *tbl, FILE *out, bool print_data)
 Q_HASHTBL->print(): Print hash table for debugging purpose.
bool _free (Q_HASHTBL *tbl)
 Q_HASHTBL->free(): De-allocate hash table.

Detailed Description

Hash-table Data Structure API.

Note:
Use "--enable-threadsafe" configure script option to use under multi-threaded environments.

Function Documentation

Q_HASHTBL* qHashtbl ( int  max,
bool  resize,
int  threshold 
)

Initialize dynamic-hash table.

Parameters:
max a number of initial number of slots of Q_HASHTBL
resize enable or disable auto incremental resizing
threshold a persent of threshold for resizing. 0 for default.
Returns:
a pointer of malloced Q_HASHTBL, otherwise returns false
   // initial table size is 1000, enable resizing, use default threshold
   Q_HASHTBL *hashtbl = qHashtblInit(1000, true, 0);
   qHashtblFree(hashtbl);

Note:
If the total number of used slots is reached at threshold parameter, hash table is automatically enlarged to double size(_Q_HASHTBL_RESIZE_MAG). The default threshold is 80% and is defined in header with _Q_HASHTBL_DEF_THRESHOLD.

static void _lock ( Q_HASHTBL *  tbl  )  [static]

Q_HASHtbl->lock(): Enter critical section.

Returns:
none
Note:
Q_HASHTBL uses recursive mutex lock mechanism. And it uses lock at least as possible. User can raise lock to proctect data modification during Q_HASHTBL->getNext() operation.

static void _unlock ( Q_HASHTBL *  tbl  )  [static]

Q_HASHTBL->unlock(): Leave critical section.

Returns:
none

static bool _put ( Q_HASHTBL *  tbl,
const char *  name,
const void *  data,
size_t  size 
) [static]

Q_HASHTBL->put(): Put object into hash table.

Parameters:
tbl a pointer of Q_HASHTBL
name key name
data data object
size size of data object
Returns:
true if successful, otherwise returns false

static bool _putStr ( Q_HASHTBL *  tbl,
const char *  name,
const char *  str 
) [static]

Q_HASHTBL->putStr(): Put string into hash table.

Parameters:
tbl a pointer of Q_HASHTBL
name key name
data data object
Returns:
true if successful, otherwise returns false

static bool _putInt ( Q_HASHTBL *  tbl,
const char *  name,
const int  num 
) [static]

Q_HASHTBL->putInt(): Put integer into hash table.

Parameters:
tbl a pointer of Q_HASHTBL
name key name
data data object
Returns:
true if successful, otherwise returns false

static void* _get ( Q_HASHTBL *  tbl,
const char *  name,
size_t *  size,
bool  newmem 
) [static]

Q_HASHTBL->get(): Get object from hash table.

Parameters:
tbl a pointer of Q_HASHTBL
name key name
size if not NULL, oject size will be stored
newmem whether or not to allocate memory for the data.
Returns:
a pointer of data if the key is found, otherwise returns NULL.
   Q_HASHTBL *tbl = qHashtbl();
   (...codes...)

   // with newmem flag unset
   size_t size;
   const char *data = tbl->get(tbl, "key_name", &size, false);

   // with newmem flag set
   size_t size;
   char *data = tbl->get(tbl, "key_name", &size, true);
   if(data != NULL) free(data);

Note:
If newmem flag is set, returned data will be malloced and should be deallocated by user. Otherwise returned pointer will point internal buffer directly and should not be de-allocated by user. In thread-safe mode, newmem flag always should be true.

static char* _getStr ( Q_HASHTBL *  tbl,
const char *  name,
bool  newmem 
) [static]

Q_HASHTBL->getStr(): Get string from hash table.

Parameters:
tbl a pointer of Q_HASHTBL
name key name
newmem whether or not to allocate memory for the data.
Returns:
a pointer of data if the key is found, otherwise returns NULL.
Note:
If newmem flag is set, returned data will be malloced and should be deallocated by user.

static int _getInt ( Q_HASHTBL *  tbl,
const char *  name 
) [static]

Q_HASHTBL->getInt(): Get integer from hash table.

Parameters:
tbl a pointer of Q_HASHTBL
name key name
Returns:
value integer if successful, otherwise(not found) returns 0
Note:
If newmem flag is true, returned data will be malloced and should be deallocated by user.

static bool _getNext ( Q_HASHTBL *  tbl,
Q_NOBJ_T *  obj,
int *  idx,
bool  newmem 
) [static]

Q_HASHTBL->getNext(): Get next key name.

Parameters:
tbl a pointer of Q_HASHTBL
idx index pointer (must be set to 0 when first call)
Returns:
true if found otherwise returns false
   Q_HASHTBL *tbl = qHashtbl();
   tbl->putStr(tbl, "key1", "hello world 1", false);
   tbl->putStr(tbl, "key2", "hello world 2", false);
   tbl->putStr(tbl, "key3", "hello world 3", false);

   // non-thread usages
   int idx = 0;
   Q_NOBJ_T obj;
   while(tbl->getNext(tbl, &obj, &idx, false) == true) {
     printf("NAME=%s, DATA=%s", SIZE=%zu", obj.name, obj.data, obj.size);
   }

   // thread model
   int idx = 0;
   Q_NOBJ_T obj;
   tbl->lock();
   while(tbl->getNext(tbl, &obj, &idx, false) == true) {
     printf("NAME=%s, DATA=%s", SIZE=%zu", obj.name, obj.data, obj.size);
   }
   tbl->unlock();

   // thread model 2 with newmem flag
   int idx = 0;
   Q_NOBJ_T obj;
   tbl->lock();
   while(tbl->getNext(tbl, &obj, &idx, false) == true) {
     printf("NAME=%s, DATA=%s", SIZE=%zu", obj.name, obj.data, obj.size);
     free(obj.name);
     free(obj.data);
   }
   tbl->unlock();

static bool _remove ( Q_HASHTBL *  tbl,
const char *  name 
) [static]

Q_HASHTBL->remove(): Remove key from hash table.

Parameters:
tbl a pointer of Q_HASHTBL
name key name
Returns:
true if successful, otherwise(not found) returns false

static int _getNum ( Q_HASHTBL *  tbl  )  [static]

Q_HASHTBL->getNum(): get number of objects stored.

Parameters:
tbl a pointer of Q_HASHTBL
Returns:
number of objects stored

static int _getMax ( Q_HASHTBL *  tbl  )  [static]

Q_HASHTBL->getMax(): Get number of object slots.

Parameters:
tbl a pointer of Q_HASHTBL
Returns:
maximum number of object slots

bool _truncate ( Q_HASHTBL *  tbl  ) 

Q_HASHTBL->truncate(): Truncate hash table.

Parameters:
tbl a pointer of Q_HASHTBL
Returns:
true if successful, otherwise returns false

bool _resize ( Q_HASHTBL *  tbl,
int  max 
)

Q_HASHTBL->resize(): Resize dynamic-hash table.

Parameters:
tbl a pointer of Q_HASHTBL
max a number of initial number of slots of Q_HASHTBL
Returns:
true if successful, otherwise returns false
   // initial table size is 1000, enable resizing, use default threshold
   qHashtblResize(tbl, 3000);

Note:
Auto resize flag and resize threshold parameter will be set to same as previous.

bool _print ( Q_HASHTBL *  tbl,
FILE *  out,
bool  print_data 
)

Q_HASHTBL->print(): Print hash table for debugging purpose.

Parameters:
tbl a pointer of Q_HASHTBL
out output stream
print_data print out value if set to true
Returns:
true if successful, otherwise returns false

bool _free ( Q_HASHTBL *  tbl  ) 

Q_HASHTBL->free(): De-allocate hash table.

Parameters:
tbl a pointer of Q_HASHTBL
Returns:
true if successful, otherwise returns false

[Home] [About] [Examples] [Changes] [Download] [SVN Repository] [Install] [Reference]