Registry services.
[Native RTAI API.]


Detailed Description

The registry provides a mean to index real-time object descriptors created by the RTAI skin 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.

The registry is a simple yet powerful mechanism for sharing real-time objects between kernel-based and user-space tasks, or between tasks belonging to different user-space processes. Once the binding has been done, an exported object can be controlled through the regular API using the ubiquitous descriptor returned by the registry.

All high-level real-time objects created by the RTAI skin can be registered. The name parameter passed to the various object creation routines is used to have the new object indexed by the RTAI registry. Such registration is always optional though, and can be avoided by passing a null or empty name string.


Files

file  registry.c
 This file is part of the RTAI project.

Functions

int rt_registry_enter (const char *key, void *objaddr, rt_handle_t *phandle)
 Register a real-time object.
int rt_registry_bind (const char *key, RTIME timeout, rt_handle_t *phandle)
 Bind to a real-time object.
int rt_registry_remove (rt_handle_t handle)
 Forcibly unregister a real-time object.
int rt_registry_remove_safe (rt_handle_t handle, RTIME timeout)
 Unregister an idle real-time object.
void * rt_registry_get (rt_handle_t handle)
 Find and lock a real-time object into the registry.
u_long rt_registry_put (rt_handle_t handle)
 Unlock a real-time object from the registry.
void * rt_registry_fetch (rt_handle_t handle)
 Find a real-time object into the registry.


Function Documentation

int rt_registry_bind const char *  key,
RTIME  timeout,
rt_handle_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 TM_INFINITE causes the caller to block indefinitely until the object is registered. Passing TM_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:
  • -EINVAL is returned if key is NULL.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before the retrieval has completed.

  • -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the searched object is not registered on entry.

  • -ETIMEDOUT is returned if the object cannot be retrieved within the specified amount of time.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if timeout is equal to TM_NONBLOCK.

  • Kernel-based task
  • User-space task (switches to primary mode)

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

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

int rt_registry_enter const char *  key,
void *  objaddr,
rt_handle_t *  phandle
 

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 rt_registry_remove() service.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if key or objaddr are NULL.

  • -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.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task

Rescheduling: possible.

u_long rt_registry_fetch rt_handle_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 RT_REGISTRY_SELF is passed, the object is the calling RTAI task.
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.
Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if handle is different from RT_REGISTRY_SELF.

  • Kernel-based task
  • User-space task

Rescheduling: never.

void * rt_registry_get rt_handle_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 deletion atomically. A locking count is tracked, so that rt_registry_get() and rt_registry_put() must be used in pair.

Parameters:
handle The generic handle of the object to find and lock. If RT_REGISTRY_SELF is passed, the object is the calling RTAI task.
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.
Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if handle is different from RT_REGISTRY_SELF.

  • Kernel-based task
  • User-space task

Rescheduling: never.

u_long rt_registry_put rt_handle_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 rt_registry_get(). The object is actually unlocked from the registry when the locking count falls down to zero, thus waking up any task currently waiting inside rt_registry_remove() for unregistering it.

Parameters:
handle The generic handle of the object to unlock. If RT_REGISTRY_SELF is passed, the object is the calling RTAI task.
Returns:
The decremented lock count is returned upon success. Zero is also returned if handle does not reference a registered object.
Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if handle is different from RT_REGISTRY_SELF.

  • Kernel-based task
  • User-space task

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

int rt_registry_remove rt_handle_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:
  • -ESRCH is returned if handle does not reference a registered object.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Kernel-based task
  • User-space task

Rescheduling: never.

int rt_registry_remove_safe rt_handle_t  handle,
RTIME  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 rt_registry_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 TM_INFINITE causes the caller to block indefinitely until the object is unlocked. Passing TM_NONBLOCK causes the service to return immediately without waiting if the object is locked on entry.
Returns:
0 is returned upon success. Otherwise:
  • -ESRCH is returned if handle does not reference a registered object.

  • -EWOULDBLOCK is returned if timeout is equal to TM_NONBLOCK and the object is locked on entry.

  • -EBUSY is returned if handle refers to a locked object and the caller could not sleep until it is unlocked.

  • -ETIMEDOUT is returned if the object cannot be removed within the specified amount of time.

  • -EINTR is returned if rt_task_unblock() has been called for the calling task waiting for the object to be unlocked.

Environments:

This service can be called from:

  • Kernel module initialization/cleanup code
  • Interrupt service routine only if timeout is equal to TM_NONBLOCK.

  • Kernel-based task
  • User-space task

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

Note:
This service is sensitive to the current operation mode of the system timer, as defined by the rt_timer_start() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.


Generated on Mon Dec 13 09:49:49 2004 for RTAI API by  doxygen 1.3.9.1