Xenomai  3.0.8
Registry services

The registry provides a mean to index object descriptors on unique alphanumeric keys. More...

Collaboration diagram for Registry services:

Functions

int xnregistry_enter (const char *key, void *objaddr, xnhandle_t *phandle, struct xnpnode *pnode)
 Register a real-time object. More...
 
int xnregistry_bind (const char *key, xnticks_t timeout, int timeout_mode, xnhandle_t *phandle)
 Bind to a real-time object. More...
 
int xnregistry_remove (xnhandle_t handle)
 Forcibly unregister a real-time object. More...
 
static void * xnregistry_lookup (xnhandle_t handle, unsigned long *cstamp_r)
 Find a real-time object into the registry. More...
 
int xnregistry_unlink (const char *key)
 Turn a named object into an anonymous object. More...
 

Detailed Description

The registry provides a mean to index object descriptors on unique alphanumeric keys.

When labeled this way, an 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.

Function Documentation

◆ xnregistry_bind()

int xnregistry_bind ( const char *  key,
xnticks_t  timeout,
int  timeout_mode,
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
keyA valid NULL-terminated string which identifies the object to bind to.
timeoutThe timeout which may be used to limit the time the thread wait for the object to be registered. This value is a wait time given as a count of nanoseconds. It can either be relative, absolute monotonic (XN_ABSOLUTE), or absolute adjustable (XN_REALTIME) depending on timeout_mode. Passing XN_INFINITE and setting timeout_mode to XN_RELATIVE specifies an unbounded wait. Passing XN_NONBLOCK causes the service to return immediately without waiting if the object is not registered on entry. All other values are used as a wait limit.
timeout_modeThe mode of the timeout parameter. It can either be set to XN_RELATIVE, XN_ABSOLUTE, or XN_REALTIME (see also xntimer_start()).
phandleA 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:
  • -EINVAL is returned if key is NULL.
  • -EINTR is returned if xnthread_unblock() has been called for the waiting thread before the retrieval has completed.
  • -EWOULDBLOCK is returned if timeout is equal to XN_NONBLOCK and the searched object is not registered on entry. As a special exception, this error is also returned if this service should block, but was called from a context which cannot sleep (e.g. interrupt, non-realtime or scheduler locked).
  • -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.
Tags cobalt-core-tags "primary-only, might-switch"
Note
xnregistry_bind() only returns the index portion of a handle, which might include other fixed bits to be complete (e.g. XNSYNCH_PSHARED). The caller is responsible for completing the handle returned with those bits if applicable, depending on the context.

◆ xnregistry_enter()

int xnregistry_enter ( const char *  key,
void *  objaddr,
xnhandle_t *  phandle,
struct xnpnode *  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
keyA 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. Pass an empty or NULL string if the object shall only occupy a registry slot for handle-based lookups. The slash character is not accepted in key if pnode is non-NULL.
objaddrAn opaque pointer to the object to index by key.
phandleA 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.
pnodeA 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:
  • -EINVAL is returned if objaddr is NULL.
  • -EINVAL if pnode is non-NULL, and key points to a valid string containing a '/' character.
  • -ENOMEM is returned if the system fails to get enough dynamic memory from the global real-time heap in order to register the object.
  • -EEXIST is returned if the key is already in use.
Tags cobalt-core-tags "unrestricted, might-switch, atomic-entry"

◆ xnregistry_lookup()

void * xnregistry_lookup ( xnhandle_t  handle,
unsigned long *  cstamp_r 
)
inlinestatic

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. Optionally, it also copies back the object's creation stamp which is unique across object registration calls.

Parameters
handleThe generic handle of the object to fetch.
cstamp_rIf not-NULL, the object's creation stamp will be copied to this memory area.
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.
Tags cobalt-core-tags "unrestricted"

◆ xnregistry_remove()

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
handleThe generic handle of the object to remove.
Returns
0 is returned upon success. Otherwise:
  • -ESRCH is returned if handle does not reference a registered object.
Tags cobalt-core-tags "unrestricted"

◆ xnregistry_unlink()

int xnregistry_unlink ( const char *  key)

Turn a named object into an anonymous object.

Tags cobalt-core-tags "unrestricted"