Registry services.
[Native RTAI API.]


Detailed Description

Registry services.


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)
 Unregister a 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 indexed yet, waiting for such indexing 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 RT_TIME_INFINITE causes the caller to block indefinitely until the object is registered. Passing RT_TIME_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 on 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 RT_TIME_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.

Side-effect: This routine calls the rescheduling procedure if the searched object is not registered on entry and timeout is different from RT_TIME_NONBLOCK.

Context: This routine can be called on behalf of a task.

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 expressed as periodic jiffies. In oneshot mode, clock ticks are expressed in 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.

Side-effect: This routine calls the rescheduling procedure if some task is currently waiting for a registration to occur.

Context: This routine can be called on behalf of a task or from the initialization code.

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.
Context: This routine can be called on behalf of a task. It can also be called on behalf of an interrupt context, or from the initialization code, provided handle is different from RT_REGISTRY_SELF.

u_long 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.
Context: This routine can be called on behalf of a task. It can also be called on behalf of an interrupt context, or from the initialization code, provided handle is different from RT_REGISTRY_SELF.

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.
Side-effect: This routine calls the rescheduling procedure if the lock count falls down to zero and some task is currently waiting for the object to be unlocked.

Context: This routine can be called on behalf of a task. It can also be called on behalf of an interrupt context, or from the initialization code, provided handle is different from RT_REGISTRY_SELF.

int rt_registry_remove rt_handle_t  handle  ) 
 

Unregister a 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()), unless it is called on behalf of the root thread (e.g. the initialization code); in the latter case, the removal is simply forced.

Parameters:
handle The generic handle of the object to remove.
Returns:
0 is returned upon success. Otherwise:
  • -ENOENT is returned if handle does not reference a registered object.

Side-effect: This routine calls the rescheduling procedure if the object to remove is currently locked.

Context: This routine can be called on behalf of a task or the initialization code.


Generated on Mon Aug 30 13:58:39 2004 for RTAI API by doxygen 1.3.8