It is no longer permissible to directly remove the ``current'' entry in a mapForEach callback function, as it was in x-kernel version 3.2. When adapting a version 3.2 protocol, care should be take to remove such illegal map modifications.
Illegal map modifications often appear in timeout handlers closing active sessions. Such code can be fixed easily because it is customary to save the binding of an active session in the binding field of the Sessn and for functions that close sessions to check this field and perform a mapRemoveKey only if it is non-zero. The fix is to modify the timeout handler to (a) reset binding to zero, (b) call the session-closing function, and (c) return the flag MFE_REMOVE in addition to any other flags that may have been returned by the mapForEach callback function. This ensures that the map entry for the active session that is being closed remains in the map until the mapForEach callback function returns.
Maps are used to bind a variable length external key to an internal id of type int. The size of the external key is given as an argument when a particular map is created. All external keys bound using this map are expected to be of this size. It's important that you use a zero-izing routine like bzero before assigning values to a structure that will be used with the map routines. The C language can have uninitialized data in the interstices of structures (i.e., padding areas), and these can cause structures that are ``equal'' (i.e., all fields have the same values) to fail to map to the same value in the x-kernel .
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 to Enable objects (Section 2.1.2), 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 xOpen routine, and a passive key to an enable object in its xOpenEnable routine. These bindings are then used in the protocol's xDemux routine.