Operations

mapCreate

Creates a map with nEntries elements in it. External ids bound in this map are keySize bytes long. The maximum value for the key size is MAX_MAP_KEY_SIZE, currently 100 bytes. Programmers will normally use sizeof(structuretype) as the keysize to facilitate platform independence. Note that maps never overflow, but they perform best if nEntries is chosen so that the map is at most 50-80%full.

If the keySize parameter is any negative number, the resulting map will support variable length keys. The functions mapVarBind and mapVarResolve should be used with such a map.

Returns 0 if the map could not be created.

Map mapCreate (int nEntries, int keySize);

mapResolve

Looks for the internal identifier bound to the external identifier ext in the map Map. Note that the resolution will be done with keysize bytes of what the ext identifier points to, where keysize is the parameter that was used in the mapCreate call. If a binding is found, *ptr is assigned the value of the internal identifier and XK_SUCCESSis returned. If no appropriate binding is found, mapResolve returns XK_FAILURE. If ptr is NULL, only the error code is returned.

xkern_return_t mapResolve (Map Map, void * ext, void ** ptr );

mapVarResolve

This is almost identical to mapResolve. Note that the resolution will be done with len bytes of what the ext identifier points to, where len is a parameter to this call. The map used in this call must have been created with a negative key size (see section 6.2.1).

xkern_return_t mapVarResolve (Map Map, void * ext, int len, void ** ptr );

mapBind

Adds a binding of external id ext to internal id intern to map Map. Note that the binding will be done with keysize bytes of what the ext identifier 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_BINDindicates that the external identifier is already bound in the map to a different internal id. If the external identifier is already bound to the same internal id, that binding is returned.

Bind mapBind ( Map Map, void * ext, void * intern );

mapVarBind

This is almost identical to mapBind. Note that the binding will be done with len bytes of what the ext identifier points to, where len is a parameter to this call. The map used in this call must have been created with a negative key size (see section 6.2.1).

Bind mapVarBind ( Map Map, void * ext, int len, void * intern );

mapRemoveBinding

Removes binding Bind from map Map. Returns XK_FAILURE if the item is not in the map.

3.1 Compatibility note: Same as 3.1 mapunbindbinding.

xkern_return_t mapRemoveBinding (Map Map, Bind Bind);

mapUnbind

Removes binding of the association key ext from the map Map. This is the inverse of mapBind. Returns XK_FAILUREif the item is not in the map.

3.1 Compatibility note: Same as 3.1 mapremove.

xkern_return_t mapUnbind (Map Map, void * ext);

mapClose

Destroys the map and frees its space. Any elements left in the map will be unbound before the map is destroyed.

void mapClose (Map Map);

mapForEach

Allows iterative access to the entries of a map by the provided function f. Each call to mapForEach puts the key and its value into arguments passed the function f. The third argument passed to f is the supplied value arg. As long as the flag MFE_CONTINUE is set in the function's return value and there are unprocessed keys, mapForEach will continue to call f.

If the flag MFE_REMOVE is set in the return value, 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 recommended way to remove the ``current'' map entry during a mapForEach operation. If the user function tries to remove the ``current'' entry directly (via mapRemove or mapUnbind), mapForEach may fail to find all of the map entries.

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. A return value of 0 negates both flags.

The order in which keys are returned depends on the internal structure of the map.

void mapForEach(Map m, MapForEachFun f, void * arg )

typedef int MapForEachFun ( void * key, void * value, void * arg )