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 is ignored.
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.

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 keylen characters.

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 map.

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.
SHMAP_OPTS functions

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.
type shmap_opts
{
	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.


LOCK FUNCTIONS


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.