Lightweight key-to-object mapping service

A map is a simple indexing structure which associates unique integer keys with pointers to objects. More...

Collaboration diagram for Lightweight key-to-object mapping service:

Functions
struct xnmap *	xnmap_create (int nkeys, int reserve, int offset)
	Create a map. More...
void	xnmap_delete (struct xnmap *map)
	Delete a map. More...
int	xnmap_enter (struct xnmap *map, int key, void *objaddr)
	Index an object into a map. More...
int	xnmap_remove (struct xnmap *map, int key)
	Remove an object reference from a map. More...
static void *	xnmap_fetch_nocheck (struct xnmap *map, int key)
	Search an object into a map - unchecked form. More...
static void *	xnmap_fetch (struct xnmap *map, int key)
	Search an object into a map. More...

Detailed Description

A map is a simple indexing structure which associates unique integer keys with pointers to objects.

The current implementation supports reservation, for naming/indexing objects, either on a fixed, user-provided integer (i.e. a reserved key value), or by drawing the next available key internally if the caller did not specify any fixed key. For instance, in some given map, the key space ranging from 0 to 255 could be reserved for fixed keys, whilst the range from 256 to 511 could be available for drawing free keys dynamically.

A maximum of 1024 unique keys per map is supported on 32bit machines.

(This implementation should not be confused with C++ STL maps, which are dynamically expandable and allow arbitrary key types; Xenomai maps don't).

Function Documentation

xnmap_create()

struct xnmap * xnmap_create	(	int	nkeys,
		int	reserve,
		int	offset
	)

Create a map.

Allocates a new map with the specified addressing capabilities. The memory is obtained from the Xenomai system heap.

Parameters

nkeys	The maximum number of unique keys the map will be able to hold. This value cannot exceed the static limit represented by XNMAP_MAX_KEYS, and must be a power of two.
reserve	The number of keys which should be kept for reservation within the index space. Reserving a key means to specify a valid key to the xnmap_enter() service, which will then attempt to register this exact key, instead of drawing the next available key from the unreserved index space. When reservation is in effect, the unreserved index space will hold key values greater than reserve, keeping the low key values for the reserved space. For instance, passing reserve = 32 would cause the index range [ 0 .. 31 ] to be kept for reserved keys. When non-zero, reserve is rounded to the next multiple of BITS_PER_LONG. If reserve is zero no reservation will be available from the map.
offset	The lowest key value xnmap_enter() will return to the caller. Key values will be in the range [ 0 + offset .. nkeys + offset - 1 ]. Negative offsets are valid.

Returns

the address of the new map is returned on success; otherwise, NULL is returned if nkeys is invalid.

Tags

task-unrestricted

xnmap_delete()

void xnmap_delete

(

struct xnmap *

map

)

Delete a map.

Deletes a map, freeing any associated memory back to the Xenomai system heap.

Parameters

map	The address of the map to delete.

Tags

task-unrestricted

xnmap_enter()

int xnmap_enter	(	struct xnmap *	map,
		int	key,
		void *	objaddr
	)

Index an object into a map.

Insert a new object into the given map.

Parameters

map	The address of the map to insert into.
key	The key to index the object on. If this key is within the valid index range [ 0 - offset .. nkeys - offset - 1 ], then an attempt to reserve this exact key is made. If key has an out-of-range value lower or equal to 0 - offset - 1, then an attempt is made to draw a free key from the unreserved index space.
objaddr	The address of the object to index on the key. This value will be returned by a successful call to xnmap_fetch() with the same key.

Returns

a valid key is returned on success, either key if reserved, or the next free key. Otherwise:

• -EEXIST is returned upon attempt to reserve a busy key.
• -ENOSPC when no more free key is available.

Tags

unrestricted

xnmap_fetch()

void xnmap_fetch ( struct xnmap *  map, int  key  )

inlinestatic

Search an object into a map.

Retrieve an object reference from the given map by its index key.

Parameters

map	The address of the map to retrieve from.
key	The key to be searched for in the map index.

Returns

The indexed object address is returned on success, otherwise NULL is returned when key is invalid or no object is currently indexed on it.

Tags

unrestricted

xnmap_fetch_nocheck()

void xnmap_fetch_nocheck ( struct xnmap *  map, int  key  )

inlinestatic

Search an object into a map - unchecked form.

Retrieve an object reference from the given map by its index key, but does not perform any sanity check on the provided key.

Parameters

map	The address of the map to retrieve from.
key	The key to be searched for in the map index.

Returns

The indexed object address is returned on success, otherwise NULL is returned when no object is currently indexed on key.

Tags

unrestricted

xnmap_remove()

int xnmap_remove	(	struct xnmap *	map,
		int	key
	)

Remove an object reference from a map.

Removes an object reference from the given map, releasing the associated key.

Parameters

map	The address of the map to remove from.
key	The key the object reference to be removed is indexed on.

Returns

0 is returned on success. Otherwise:

• -ESRCH is returned if key is invalid.

Tags

unrestricted