The final x-kernel tool we describe is the id mapper. This tool provides a facility for maintaining a set of bindings between identifiers. The id mapper supports operations for adding new bindings to the set, removing bindings from the set, and mapping one identifier into another, relative to a set of bindings. Protocol implementations use these operations to translate identifiers extracted from message headers (e.g., addresses, demultiplexing keys) into capabilities for (pointers to) x-kernel objects such as sessions. (See [1] for a description of how the map library is implemented.)
The id mapper supports two main objects: maps and
bindings, represented by the types Map and Binding,
respectively. A map is simply a table of bindings, where each binding
is given by the pair 
external key, internal id 
. An
external key is a variable length byte string, and an internal id is a
fixed-sized identifier (e.g., a 32 or 64-bit memory address).
Typically, an external key is constructed from various fields in a
message header, and an internal id is a pointer to a protocol or
session object. A map is created with the following operation:
Map mapCreate(int number, int size)
This operation creates a map that is able to hold number bindings in it, where the external keys bound in this map are size bytes long.
Once a map is created, protocols can perform two basic operations on it. The first puts bindings into the map and the latter resolves external keys according to the map and returns the corresponding internal id:
Binding mapBind(Map map, void *key, void *id)
XkReturn mapResolve(Map map, void *key, void **id)
The first operation inserts a binding of key to id into the specified map, and returns a pointer to the resulting binding. If key is already bound to some id in the map, then a pointer to that existing binding is returned. The second operation returns the internal id bound to the specified key in the given map. If the key is not found in the map, then mapResolve reports failure by returning XK_FAILURE.
The id mapper also provides a pair of operations for removing bindings from a map:
XkReturn mapRemoveBinding(Map map, Binding binding)
XkReturn mapRemoveKey(Map map, void *key)
The first removes the specified binding---the value returned by an earlier mapBind---and the second removes the binding for the specified key. Both operations return a failure code if the binding does not exist in the map.
Protocols generally maintain two maps: an active map and a passive map. Active maps are used to map keys found in incoming messages into the session that will process the message. Thus, the active map holds information about the set of currently active connections. Passive maps are used to bind keys found in incoming messages into protocol objects, thereby allowing a protocol to create a session when a message that is part of a new connection arrives.
Typically, a protocol binds an active key to a session in its implementation of xOpen, and a passive key to a protocol object in its xOpenEnable routine. These bindings are then used in the protocol's xDemux operation. This general pattern is illustrated in the example given Section 7.