Xenomai  3.0.8
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
nkeysThe 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.
reserveThe 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.
offsetThe 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 cobalt-core-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
mapThe address of the map to delete.
Tags cobalt-core-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
mapThe address of the map to insert into.
keyThe 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.
objaddrThe 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 cobalt-core-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
mapThe address of the map to retrieve from.
keyThe 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 cobalt-core-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
mapThe address of the map to retrieve from.
keyThe 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 cobalt-core-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
mapThe address of the map to remove from.
keyThe 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 cobalt-core-tags "unrestricted"