Shmap API version 0.3 documentation
shmap * shmap_init ( shmap_opts * p_opts )
This is the main function to use is. A pointer to newly allocated
hashmap structure is returned or NULL if an error occured.
p_opts - the options definig a new hashmap. See shmap_opts* functions for more details.
p_memsegm - the memory segment pointer. useful if you want many hashmaps
to use the same shared memory segment. Currently this is tied with the MM
structure defined in libmm. Set it NULL, if you want a brand new shared memory
segment to be allocated
size - the shared memory segment size. If p_memsegm is NULL, then you have
to specify a number greater than 0. If p_memsegm is not NULL, then this argument
map_type - what type of internal structure to use. Current possible values
are SHMAP_TYPE_LL and SHMAP_TYPE_HM. See internal structures for more information
p_opts - this is for the future. Set it to NULL right now.
void * shmap_get_value ( shmap * map, const char * key, int cached )
This function returns a hashmap value based on the given key.
map - the hashmap pointer
key - the key string pointer. Lookup is done based on that.
cached - specify 0 if you want to bypass any kind of lookup cachings or
1 if it is ok when the result is returned from cache. The thing is, that sometimes
caching might not work and wrong answer is returned. IF this happens, then
you should specify cached = 0. If wrong answer is still displayed, then look
for the error elsewhere.
char * shmap_get ( shmap * map, const char * key )
This functions is merely an alias to shmap_get_value. The
difference is, that you don't have to cast void * into char * and caching
is turned on by default.
int shmap_get_int ( shmap * map, const char * key, int *p_error, int cached )
Instead or void * (or char *, like ine shmap_get) like in
shmap_get_value, int type of data is returned.
map - the hashmap itself where we do the lookup based on key
key - the key for the value we are looking for
*p_error - pointer to int datatype. If an error happened during the lookup,
then 0 is stored to the pointer, if everything is successful, then 1 is stored.
cached - 0 to bypass any kind of lookup caching, 1 to use caching
Return: the integer value for the given key.
int shmap_add_value ( shmap * map, const char * key, const char * value )
Adds or replaces an existing entry in the map. If the given
key already exists, then the value is replaced, otherwise it is inserted.
map - the hashmap that we want to use for adding or replacing.
key - the key to store value under.
value - the value that we want to store into hashmap
Return: 0 if error occured, 1 if everything is a successful
int shmap_add ( shmap * map, const char * key, const char * value )
This is merely an alias to shmap_add_value.
int shmap_del_value ( shmap * map, const char * key )
Deletes a key and its representing value from hashmap
map - the hashmap we want to modify
key - the key we want to remove from hashmap
Return: 1 if hashmap entry was deleted, 0 if an error occured or the entry
did not exist.
char * shmap_get_sub ( shmap * map, const char * key, int keylen, int pos, int cached )
Returns a key value from hashmap based on the subkey.
Example: if key is "IP_ADDRESS", keylen is 2 and pos is 0, then the FIRST
full name of a key is returned, that starts with string "IP"
int shmap_del_sub ( shmap * map, const char * key, int keylen )
Deletes all values that start with key first
map - the hashmap we want to clear of some keys
key - the key name used upon deletion
keylen - key length used is strncmp
Return 1 if success, 0 if error occured
int shmap_clear ( shmap * map )
Deletes all values from map
int shmap_dispose ( shmap * map )
Deletes the whole map. You can not use
it after this point or bad things will start to happen
void shmap_empty_cache ( shmap * map )
If internal caching is used, then this
function will flush the cache. Sometimes it is necessary.
void * shmap_memsegm ( shmap * map )
Returns the memory segment pointer
used within hashmap map.
unsigned int shmap_items ( shmap * map )
Returns the amount of items in hashmap
unsigned int shmap_available ( shmap * map )
Returns the amount of memory available
for hashmap map.
void shmap_free_resource ( shmap * map, void * ptr )
Frees the resource given in ptr. It is mostly meant for usage with SHMAP_TYPE_FIFO map
type, because when you fetch a value from fifo, then that value is detached from fifo,
but the resource is not freed. Unless you added a pointer to fifo, you'll need to
call this function on values returned from fifo.
This describes the shmap_opts structure type. Note that it is better you don't access it directly but though predefined API.
This structure is used to create and initialize a shared memory map. There is also a possibility to use SHMAP_DEFAULT as
shmap_opts in shmap_init.
void * p_mem; - the memory segment pointer
size_t size; - the memory segment size
char type; - type of hashmap
int flags; - special flags for hashmap
char * p_mem_name; - the full path for a file where to keep some data
void shmap_opts_setmem ( shmap_opts * p_opts, void * p_mem )
This will set the memory segment in shmap_opts structure.
void shmap_opts_settype ( shmap_opts * p_opts, char map_type )
This will set the map type in shmap_opts. Possible values are SHMAP_TYPE_LL (linked list),
SHMAP_TYPE_HM (array with hashing algorithm), SHMAP_TYPE_BTREE (binary tree) or
SHMAP_TYPE_FIFO (first in, first out type of hashmap)
SHMAP_TYPE_FIFO : There can be unlimited fifos (actually the limit is shared memory segment size) on one map as each key represents one
fifo. That means you can add many values under one key, and fetch them later (in fifo
order) from that key. If you fetch a value, then after you have done what you needed with it,
you'll need to call shmap_free_resource, to free the resources allocated to that object in shared memory segment.
void shmap_opts_setsize ( shmap_opts * p_opts, size_t size )
This will set the size in shmap_opts type.
void shmap_opts_setname ( shmap_opts * p_opts, char * filename )
This will set the shared memory map name. It will have to be a filename with full path. Useful
if you want to attach to existing maps.
shmap_lock * shmap_lock_init ( void * p_mem, const char * path )
Initialize a brand new lock. Returns NULL on error.
shmap_lock * shmap_lock_get ( shmap * map )
Returns the locks for an existing hashmap.
int shmap_lock_set ( shmap * map, shmap_lock * lock )
Sets a new lock for a hashmap. be very careful when using this!
int shmap_lock_del ( shmap * map )
Sets a lock to NULL in a hashmap. Does not destory the hashmap.
int shmap_lock_dispose ( void * p_mem, shmap_lock * lock )
This deletes a lock and frees the resources.
int shmap_dolock ( shmap_lock * lock, shmap_lock_mode mode )
Locks the lock. Types are SHMAP_LOCK_READ and SHMAP_LOCK_WRITE.
int shmap_unlock ( shmap_lock * lock )
Unlock the given map.