Mutex services.
[Native RTAI API.]


Detailed Description

Mutex services.

A mutex is a MUTual EXclusion object, and is useful for protecting shared data structures from concurrent modifications, and implementing critical sections and monitors.

A mutex has two possible states: unlocked (not owned by any task), and locked (owned by one task). A mutex can never be owned by two different tasks simultaneously. A task attempting to lock a mutex that is already locked by another task is blocked until the owning task unlocks the mutex first.


Files

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

Functions

int rt_mutex_create (RT_MUTEX *mutex, const char *name)
 Create a mutex.
int rt_mutex_delete (RT_MUTEX *mutex)
 Delete a mutex.
int rt_mutex_lock (RT_MUTEX *mutex)
 Acquire a mutex.
int rt_mutex_unlock (RT_MUTEX *mutex)
 Unlock mutex.
int rt_mutex_inquire (RT_MUTEX *mutex, RT_MUTEX_INFO *info)
 Inquire about a mutex.


Function Documentation

int rt_mutex_create RT_MUTEX *  mutex,
const char *  name
 

Create a mutex.

Create a mutual exclusion object that allows multiple threads to synchronize access to a shared resource. A mutex is left in an unlocked state after creation.

Parameters:
mutex The address of a mutex descriptor RTAI will use to store the mutex-related data. This descriptor must always be valid while the mutex is active therefore it must be allocated in permanent memory.
name An ASCII string standing for the symbolic name of the mutex. When non-NULL and non-empty, this string is copied to a safe place into the descriptor, and passed to the registry package if enabled for indexing the created mutex.
Returns:
0 is returned upon success. Otherwise:
  • -EEXIST is returned if the name is already in use by some registered object.

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

int rt_mutex_delete RT_MUTEX *  mutex  ) 
 

Delete a mutex.

Destroy a mutex and release all the tasks currently pending on it. A mutex exists in the system since rt_mutex_create() has been called to create it, so this service must be called in order to destroy it afterwards.

Parameters:
mutex The descriptor address of the affected mutex.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if sem is not a mutex descriptor.

  • -EIDRM is returned if sem is a deleted mutex descriptor.

Side-effect: This routine calls the rescheduling procedure if tasks have been woken up as a result of the deletion.

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

int rt_mutex_inquire RT_MUTEX *  mutex,
RT_MUTEX_INFO *  info
 

Inquire about a mutex.

Return various information about the status of a given mutex.

Parameters:
mutex The descriptor address of the inquired mutex.
info The address of a structure the mutex information will be written to.
Returns:
0 is returned and status information is written to the structure pointed at by info upon success. Otherwise:
  • -EINVAL is returned if sem is not a mutex descriptor.

  • -EIDRM is returned if sem is a deleted mutex descriptor.

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

int rt_mutex_lock RT_MUTEX *  mutex  ) 
 

Acquire a mutex.

Attempt to lock a mutex. The calling task is blocked until the mutex is available, in which case it is locked again before this service returns. Mutexes have an ownership property, which means that their current owner is tracked. RTAI mutexes are implicitely recursive and implement the priority inheritance protocol.

Since a nested locking count is maintained for the current owner, rt_mutex_lock() and rt_mutex_unlock() must be used in pairs.

Tasks pend on mutexes by priority order.

Parameters:
mutex The descriptor address of the mutex to acquire.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if mutex is not a mutex descriptor.

  • -EIDRM is returned if mutex is a deleted mutex descriptor, including if the deletion occurred while the caller was sleeping on it.

  • -EINTR is returned if rt_task_unblock() has been called for the waiting task before the mutex has become available.

Side-effect: This routine calls the rescheduling procedure unless the mutex is immediately available. If the caller is blocked, the current owner priority might be temporarily raised as a consequence of the priority inheritance protocol.

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

int rt_mutex_unlock RT_MUTEX *  mutex  ) 
 

Unlock mutex.

Release a mutex. If the mutex is pended, the first waiting task (by priority order) is immediately unblocked and transfered the ownership of the mutex; otherwise, the mutex is left in an unlocked state.

Parameters:
mutex The descriptor address of the released mutex.
Returns:
0 is returned upon success. Otherwise:
  • -EINVAL is returned if mutex is not a mutex descriptor.

  • -EIDRM is returned if mutex is a deleted mutex descriptor.

  • -EACCES is returned if mutex is not owned by the current task.

Side-effect: This routine calls the rescheduling procedure if a task is woken up as a result of the operation.

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


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