Registry services.
[Xenomai nucleus.]

Collaboration diagram for Registry services.:

Detailed Description

The registry provides a mean to index real-time object descriptors created by Xenomai skins on unique alphanumeric keys. When labeled this way, a real-time object is globally exported; it can be searched for, and its descriptor returned to the caller for further use; the latter operation is called a "binding". When no object has been registered under the given name yet, the registry can be asked to set up a rendez-vous, blocking the caller until the object is eventually registered.


Files

file  registry.h
 This file is part of the Xenomai project.
file  registry.c
 This file is part of the Xenomai project.

Functions

int xnregistry_enter (const char *key, void *objaddr, xnhandle_t *phandle, xnpnode_t *pnode)
int xnregistry_bind (const char *key, xnticks_t timeout, xnhandle_t *phandle)
int xnregistry_remove (xnhandle_t handle)
int xnregistry_remove_safe (xnhandle_t handle, xnticks_t timeout)
void * xnregistry_get (xnhandle_t handle)
u_long xnregistry_put (xnhandle_t handle)
void * xnregistry_fetch (xnhandle_t handle)


Function Documentation

int xnregistry_bind ( const char *  key,
xnticks_t  timeout,
xnhandle_t *  phandle 
)

Bind to a real-time object.

This service retrieves the registry handle of a given object identified by its key. Unless otherwise specified, this service will block the caller if the object is not registered yet, waiting for such registration to occur.

Parameters:
key A valid NULL-terminated string which identifies the object to bind to.
timeout The number of clock ticks to wait for the registration to occur (see note). Passing XN_INFINITE causes the caller to block indefinitely until the object is registered. Passing XN_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry.
phandle A pointer to a memory location which will be written upon success with the generic handle defined by the registry for the retrieved object. Contents of this memory is undefined upon failure.
Returns:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: always unless the request is immediately satisfied or timeout specifies a non-blocking operation.

Note:
The timeout value will be interpreted as jiffies if thread is bound to a periodic time base (see xnpod_init_thread), or nanoseconds otherwise.

int xnregistry_enter ( const char *  key,
void *  objaddr,
xnhandle_t *  phandle,
xnpnode_t *  pnode 
)

Register a real-time object.

This service allocates a new registry slot for an associated object, and indexes it by an alphanumeric key for later retrieval.

Parameters:
key A valid NULL-terminated string by which the object will be indexed and later retrieved in the registry. Since it is assumed that such key is stored into the registered object, it will *not* be copied but only kept by reference in the registry.
objaddr An opaque pointer to the object to index by key.
phandle A pointer to a generic handle defined by the registry which will uniquely identify the indexed object, until the latter is unregistered using the xnregistry_remove() service.
pnode A pointer to an optional /proc node class descriptor. This structure provides the information needed to export all objects from the given class through the /proc filesystem, under the /proc/xenomai/registry entry. Passing NULL indicates that no /proc support is available for the newly registered object.
Returns:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: possible.

void* xnregistry_fetch ( xnhandle_t  handle  ) 

Find a real-time object into the registry.

This service retrieves an object from its handle into the registry and returns the memory address of its descriptor.

Parameters:
handle The generic handle of the object to fetch. If XNOBJECT_SELF is passed, the object is the calling Xenomai thread.
Returns:
The memory address of the object's descriptor is returned on success. Otherwise, NULL is returned if handle does not reference a registered object, or if handle is equal to XNOBJECT_SELF but the current context is not a real-time thread.
Environments:

This service can be called from:

Rescheduling: never.

void* xnregistry_get ( xnhandle_t  handle  ) 

Find and lock a real-time object into the registry.

This service retrieves an object from its handle into the registry and prevents it removal atomically. A locking count is tracked, so that xnregistry_get() and xnregistry_put() must be used in pair.

Parameters:
handle The generic handle of the object to find and lock. If XNOBJECT_SELF is passed, the object is the calling Xenomai thread.
Returns:
The memory address of the object's descriptor is returned on success. Otherwise, NULL is returned if handle does not reference a registered object, or if handle is equal to XNOBJECT_SELF but the current context is not a real-time thread.
Environments:

This service can be called from:

Rescheduling: never.

u_long xnregistry_put ( xnhandle_t  handle  ) 

Unlock a real-time object from the registry.

This service decrements the lock count of a registered object previously locked by a call to xnregistry_get(). The object is actually unlocked from the registry when the locking count falls down to zero, thus waking up any thread currently blocked on xnregistry_remove() for unregistering it.

Parameters:
handle The generic handle of the object to unlock. If XNOBJECT_SELF is passed, the object is the calling Xenomai thread.
Returns:
The decremented lock count is returned upon success. Zero is also returned if handle does not reference a registered object, or if handle is equal to XNOBJECT_SELF but the current context is not a real-time thread.
Environments:

This service can be called from:

Rescheduling: possible if the lock count falls down to zero and some thread is currently waiting for the object to be unlocked.

int xnregistry_remove ( xnhandle_t  handle  ) 

Forcibly unregister a real-time object.

This service forcibly removes an object from the registry. The removal is performed regardless of the current object's locking status.

Parameters:
handle The generic handle of the object to remove.
Returns:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: never.

int xnregistry_remove_safe ( xnhandle_t  handle,
xnticks_t  timeout 
)

Unregister an idle real-time object.

This service removes an object from the registry. The caller might sleep as a result of waiting for the target object to be unlocked prior to the removal (see xnregistry_put()).

Parameters:
handle The generic handle of the object to remove.
timeout If the object is locked on entry, param gives the number of clock ticks to wait for the unlocking to occur (see note). Passing XN_INFINITE causes the caller to block indefinitely until the object is unlocked. Passing XN_NONBLOCK causes the service to return immediately without waiting if the object is locked on entry.
Returns:
0 is returned upon success. Otherwise:

Environments:

This service can be called from:

Rescheduling: possible if the object to remove is currently locked and the calling context can sleep.

Note:
The timeout value will be interpreted as jiffies if the current thread is bound to a periodic time base (see xnpod_init_thread), or nanoseconds otherwise.


Generated on Mon Mar 24 18:02:41 2008 for Xenomai API by  doxygen 1.5.3