Creates a map with table_len elements in it. External keys bound in this map are keySize bytes long. The maximum value for the key size is MAX_MAP_KEY_SIZE, currently 100 bytes. Programmers should normally use sizeof(structuretype) as the key size to facilitate platform independence. Note that maps never overflow, but they perform best if table_len is chosen so that the map is at most 50-80% full. Returns 0 if the map could not be created.
Map mapCreate(int table_len, int keySize)
Adds a binding of external key to internal id to map. The binding will be done with keySize bytes of what key points to, where keySize is the parameter that was used in the mapCreate call. The return value uniquely identifies this binding; it can later be given as an argument to mapRemoveBinding. A return value of ERR_BIND indicates that the key is already bound in the map to a different id. If the key is already bound to the same id, that binding is returned.
Binding mapBind(Map map, void *key, void *id)
Looks for the internal id bound to the external key in map. The resolution will be done with keySize bytes of what key points to, where keySize is the parameter that was used in the mapCreate call. If a binding is found, *id is assigned the value of the internal identifier and XK_SUCCESS is returned. If no appropriate binding is found, mapResolve returns XK_FAILURE. If id is NULL, only the error code is returned.
XkReturn mapResolve(Map map, void *key, void **id)
Removes binding bind from map. Returns XK_FAILURE if the item is not in the map.
XkReturn mapRemoveBinding(Map map, Binding bind)
Removes binding of the association key from the map. This is the inverse of mapBind. Returns XK_FAILURE if the item is not in the map.
XkReturn mapRemoveKey(Map map, void *key)
Destroys map and frees its space. Any elements left in the map will be unbound before the map is destroyed.
void mapClose(Map map)
Allows iterative access to the entries of a map by the provided callback function func. Each call to mapForEach puts the external key and its internal id into arguments passed the function func. The third argument passed to func is the supplied value arg. As long as the flag MFE_CONTINUE is set in the callback function's return value and there are unprocessed keys, mapForEach will continue to call func.
If the flag MFE_REMOVE is set in the return value of the callback function, mapForEach will remove the entry from the map after the user function returns and before it is called with the next map entry. This is the only correct way to remove the ``current'' map entry during a mapForEach operation. If the user callback function attempts to remove the ``current'' entry directly (via mapRemoveBinding or mapRemoveKey), the result is unpredictable and may result in system crashes.
It is currently possible to remove entries other than the ``current'' entry from within the callback function. However, we strongly discourage such use as its correctness depends on implementation details that may change in future versions of the x-kernel .
New map entries added in the middle of a mapForEach iteration may or may not show up during that iteration. Map manipulations within a mapForEach user function are generally not recommended.
MFE_REMOVE and MFE_CONTINUE are binary flags which may be combined using bitwise OR. The order in which keys are returned depends on the internal structure of the map.
void mapForEach(Map map, MapForEachFun func, void *arg)
typedef int MapForEachFun(void *key, void *id, void *arg)