Usage Rules

External Keys

Maps are used to bind a variable length external id to an internal id of type int. The size of the external id is given as an argument when a particular map is created. All external ids bound using this map are expected to be of this size. The user is warned to 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.

Active and Passive Maps

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 identifiers 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 open routine, and a passive key to an enable object in its openEnable routine. These bindings are then used in the protocol's demux operation, according to the general pattern illustrated in figure 1.

Notice two things about the example. First, in the case where a new session is created, it is necessary to call xDuplicate on the lower-level session to make the reference we hold to it permanent (see Sections 2.2.15 and 11). Second, it is useful to save the binding of an active key to the newly created session in the session object itself. (The same thing is done when a session is created in the protocol's open routine). This is because it will be necessary to be able to remove the binding from the active map when the session is closed, and this is often easier or more efficient if the binding itself is available. Finally, the active key in this example includes both fields found in the message header and the lower-level session that called xDemux. Using the lower-level session as part of the active key is fairly common; it helps to disambiguate protocol header fields that are not unique across all lower-level connections.