facil.io
API Reference

#./fio-stl/210 map.h

30 public symbols.

#Macros

#FIO_MAP_INIT

c
#define FIO_MAP_INIT   \
  { 0 }

Symbol type: macro

#FIO_MAP_EACH

c
#define FIO_MAP_EACH(map_name, map_ptr, i)   \
  for (FIO_NAME(map_name, iterator_s)   \
           i = FIO_NAME(map_name, get_next)(map_ptr, NULL);   \
       FIO_NAME(map_name, iterator_is_valid)(&i);   \
       i = FIO_NAME(map_name, get_next)(map_ptr, &i))

Iterates through the map using an iterator object.

Symbol type: macro

#FIO_MAP_EACH_REVERSED

c
#define FIO_MAP_EACH_REVERSED(map_name, map_ptr, i)   \
  for (FIO_NAME(map_name, iterator_s)   \
           i = FIO_NAME(map_name, get_prev)(map_ptr, NULL);   \
       FIO_NAME(map_name, iterator_is_valid)(&i);   \
       i = FIO_NAME(map_name, get_prev)(map_ptr, &i))

Iterates through the map using an iterator object.

Symbol type: macro

#Types

#fiobj_hash_node_s

c
struct fiobj_hash_node_s

internal object data representation

Symbol type: type

#fiobj_hash_s

c
struct fiobj_hash_s {
uint32_t bits;
uint32_t count;
FIO_NAME(FIO_MAP_NAME, node_s) * map;
#if FIO_MAP_ORDERED
FIO_INDEXED_LIST32_HEAD head;
#endif
}

A Hash Map / Set type

Symbol type: type

#fiobj_hash_iterator_s

c
typedef struct {
/** the node in the internal map */
fiobj_hash_iterator_s * node;
/** the key in the current position */
FIO_MAP_KEY key;
#ifdef FIO_MAP_VALUE
/** the value in the current position */
FIO_MAP_VALUE value;
#endif
#if !FIO_MAP_RECALC_HASH
/** the hash for the current position */
uint64_t hash;
#endif
struct { /* internal usage, do not access */
uint32_t index; /* the index in the internal map */
uint32_t pos; /* the position in the ordering scheme */
uintptr_t map_validator; /* map mutation guard */
} private_;
} fiobj_hash_iterator_s

Map iterator type

Symbol type: type

#fiobj_hash_each_s

c
struct fiobj_hash_each_s {
/** The being iterated. Once set, cannot be safely changed. */
FIO_MAP_PTR const parent;
/** The current object's index */
uint64_t index;
/** The callback / task called for each index, may be updated mid-cycle. */
int (*task)(struct FIO_NAME(FIO_MAP_NAME, each_s) * info);
/** Opaque user data. */
void *udata;
#ifdef FIO_MAP_VALUE
/** The object's value at the current index. */
FIO_MAP_VALUE value;
#endif
/** The object's key the current index. */
FIO_MAP_KEY key;
}

Iteration information structure passed to the callback.

Symbol type: type

#Functions

#fiobj_hash_destroy

c
void fiobj_hash_destroy(FIO_MAP_PTR map)

Destroys the object, re-initializing its container.

Symbol type: function

#fiobj_hash_capa

c
inline uint32_t fiobj_hash_capa(FIO_MAP_PTR map)

Theoretical map capacity.

Symbol type: function

#fiobj_hash_count

c
inline uint32_t fiobj_hash_count(FIO_MAP_PTR map)

The number of objects in the map capacity.

Symbol type: function

#fiobj_hash_reserve

c
void fiobj_hash_reserve(FIO_MAP_PTR map, size_t capa)

Reserves at minimum the capacity requested.

Symbol type: function

#fiobj_hash_node2key

c
inline FIO_MAP_KEY fiobj_hash_node2key(FIO_NAME(FIO_MAP_NAME, node_s) * node)

Returns the key value associated with the node's pointer (see set_ptr).

Symbol type: function

#fiobj_hash_node2hash

c
inline uint64_t fiobj_hash_node2hash(FIO_NAME(FIO_MAP_NAME, node_s) * node)

Returns the hash value associated with the node's pointer (see set_ptr).

Symbol type: function

#fiobj_hash_node2val

c
inline FIO_MAP_VALUE fiobj_hash_node2val(FIO_NAME(FIO_MAP_NAME, node_s) * node)

Returns the value associated with the node's pointer (see set_ptr).

Symbol type: function

#fiobj_hash_node2key_ptr

c
inline FIO_MAP_KEY_INTERNAL *fiobj_hash_node2key_ptr( FIO_NAME(FIO_MAP_NAME, node_s) * node)

Returns the key value associated with the node's pointer (see set_ptr).

Symbol type: function

#fiobj_hash_node2val_ptr

c
inline FIO_MAP_VALUE_INTERNAL *fiobj_hash_node2val_ptr( FIO_NAME(FIO_MAP_NAME, node_s) * node)

Returns the value associated with the node's pointer (see set_ptr).

Symbol type: function

#fiobj_hash_remove

c
int fiobj_hash_remove(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif FIO_MAP_KEY key, #if defined(FIO_MAP_VALUE) FIO_MAP_VALUE_INTERNAL *old #else FIO_MAP_KEY_INTERNAL *old #endif )

Removes an object in the map, returning a pointer to the map data.

Symbol type: function

#fiobj_hash_evict

c
void fiobj_hash_evict(FIO_MAP_PTR map, size_t number_of_elements)

Evicts elements in order least recently used (LRU), FIFO or undefined.

Symbol type: function

#fiobj_hash_clear

c
void fiobj_hash_clear(FIO_MAP_PTR map)

Removes all objects from the map, without releasing the map's resources.

Symbol type: function

#fiobj_hash_compact

c
void fiobj_hash_compact(FIO_MAP_PTR map)

Attempts to minimize memory use.

Symbol type: function

#fiobj_hash_get

c
inline FIO_MAP_GET_T fiobj_hash_get(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif FIO_MAP_KEY key)

Gets a value from the map, if exists.

Symbol type: function

#fiobj_hash_set

c
inline FIO_MAP_GET_T fiobj_hash_set(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif #ifdef FIO_MAP_VALUE FIO_MAP_KEY key, FIO_MAP_VALUE obj, FIO_MAP_VALUE_INTERNAL *old #else FIO_MAP_KEY key #endif )

Sets a value in the map, hash maps will overwrite existing data if any.

Symbol type: function

#fiobj_hash_set_if_missing

c
inline FIO_MAP_GET_T fiobj_hash_set_if_missing(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif FIO_MAP_KEY key #ifdef FIO_MAP_VALUE , FIO_MAP_VALUE obj #endif )

Sets a value in the map if not set previously.

Symbol type: function

#fiobj_hash_set_ptr

c
fiobj_hash_set_ptr * FIO_NAME(FIO_MAP_NAME, set_ptr)(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif #ifdef FIO_MAP_VALUE FIO_MAP_KEY key, FIO_MAP_VALUE val, FIO_MAP_VALUE_INTERNAL *old, int overwrite #else FIO_MAP_KEY key #endif )

The core set function.

This function returns NULL on error (errors are logged).

If the map is a hash map, overwriting the value (while keeping the key) is possible. In this case the old pointer is optional, and if set than the old data will be copied to over during an overwrite.

NOTE: the function returns a pointer to the map's internal storage.

Symbol type: function

#fiobj_hash_get_ptr

c
fiobj_hash_get_ptr * FIO_NAME(FIO_MAP_NAME, get_ptr)(FIO_MAP_PTR map, #if !defined(FIO_MAP_HASH_FN) uint64_t hash, #endif FIO_MAP_KEY key)

The core get function. This function returns NULL if item is missing.

NOTE: the function returns a pointer to the map's internal storage.

Symbol type: function

#fiobj_hash_each

c
uint32_t fiobj_hash_each(FIO_MAP_PTR map, int (*task)(FIO_NAME(FIO_MAP_NAME, each_s) *), void *udata, ssize_t start_at)

Iteration using a callback for each element in the map.

The callback task function must accept an each_s pointer, see above.

If the callback returns -1, the loop is broken. Any other value is ignored.

Returns the relative "stop" position, i.e., the number of items processed + the starting point.

Symbol type: function

#fiobj_hash_get_next

c
fiobj_hash_get_next FIO_NAME(FIO_MAP_NAME, get_next)(FIO_MAP_PTR map, FIO_NAME(FIO_MAP_NAME, iterator_s) * current_pos)

Returns the next iterator object after current_pos or the first if NULL.

Note that adding objects to the map or rehashing between iterations could incur performance penalties when re-setting and re-seeking the previous iterator position.

Adding objects to, or rehashing, an unordered maps could invalidate the iterator object completely as the ordering may have changed and so the "next" object might be any object in the map.

Symbol type: function

#fiobj_hash_get_prev

c
fiobj_hash_get_prev FIO_NAME(FIO_MAP_NAME, get_prev)(FIO_MAP_PTR map, FIO_NAME(FIO_MAP_NAME, iterator_s) * current_pos)

Returns the next iterator object after current_pos or the last if NULL.

See notes in get_next.

Symbol type: function

#fiobj_hash_iterator_is_valid

c
inline int fiobj_hash_iterator_is_valid(FIO_NAME(FIO_MAP_NAME, iterator_s) * iterator)

Returns 1 if the iterator is out of bounds, otherwise returns 0.

Symbol type: function

#fiobj_hash_iterator2node

c
inline fiobj_hash_iterator2node * FIO_NAME(FIO_MAP_NAME, iterator2node)(FIO_MAP_PTR map, FIO_NAME(FIO_MAP_NAME, iterator_s) * iterator)

Returns a pointer to the node object in the internal map.

Symbol type: function