Thread synchronization services.
[Xenomai scheduler.]


Detailed Description

Thread synchronization services.


Files

file  synch.c
 Thread synchronization services.


Functions

void xnsynch_init (xnsynch_t *synch, xnflags_t flags)
 Initialize a synchronization object.

void xnsynch_sleep_on (xnsynch_t *synch, xnticks_t timeout, xnmutex_t *imutex)
 Sleep on a synchronization object.

void xnsynch_clear_boost (xnsynch_t *synch, xnthread_t *lastowner)
 Clear the priority boost - INTERNAL.

void xnsynch_renice_sleeper (xnthread_t *thread)
 Change a sleeper's priority - INTERNAL.

xnthread * xnsynch_wakeup_one_sleeper (xnsynch_t *synch)
 Give the resource ownership to the next waiting thread.

xnpholder_t * xnsynch_wakeup_this_sleeper (xnsynch_t *synch, xnpholder_t *holder)
 Give the resource ownership to a given waiting thread.

int xnsynch_flush (xnsynch_t *synch, xnflags_t reason)
 Unblock all waiters pending on a resource.

void xnsynch_forget_sleeper (xnthread_t *thread)
 Abort a wait for a resource - INTERNAL.

void xnsynch_release_all_ownerships (xnthread_t *thread)
 Release all ownerships - INTERNAL.


Function Documentation

void xnsynch_clear_boost xnsynch_t *  synch,
xnthread_t *  owner
[static]
 

Clear the priority boost - INTERNAL.

This service is called internally whenever a synchronization object is not claimed anymore by sleepers to reset the object owner's priority to its initial level.

Parameters:
synch The descriptor address of the synchronization object.
owner The descriptor address of the thread which currently owns the synchronization object.

void xnsynch_flush xnsynch_t *  synch,
xnflags_t  reason
 

Unblock all waiters pending on a resource.

This service atomically releases all threads which currently sleep on a given resource.

This service should be called by upper interfaces under circumstances requiring that the pending queue of a given resource is cleared, such as before the resource is deleted.

Parameters:
synch The descriptor address of the synchronization object whose ownership is changed.
reason Some flags to set in the status mask of every unblocked thread. The following bits are pre-defined by the nanokernel:
  • XNRMID should be set to indicate that the synchronization object is about to be destroyed (see xnpod_resume_thread()).

Returns:
XNSYNCH_RESCHED is returned if at least one thread is unblocked, which means the caller should invoke xnpod_schedule() for applying the new scheduling state. Otherwise, XNSYNCH_DONE is returned.
Side-effects:

  • The effective priority of the previous resource owner might be lowered to its base priority value as a consequence of the priority inheritance boost being cleared.

  • The synchronization object is no more owned by any thread.

  • This routine does not call the rescheduling procedure.

Context: This routine must be called on behalf of a thread or IST context.

void xnsynch_forget_sleeper xnthread_t *  thread  ) 
 

Abort a wait for a resource - INTERNAL.

Performs all the necessary housekeeping chores to stop a thread from waiting on a given synchronization object.

Parameters:
thread The descriptor address of the affected thread.
When the trace support is enabled (i.e. MVM), the idle state is posted to the synchronization object's state diagram (if any) whenever no thread remains blocked on it. The real-time interfaces must ensure that such condition (i.e. EMPTY/IDLE) is mapped to state #0.

void xnsynch_init xnsynch_t *  synch,
xnflags_t  flags
 

Initialize a synchronization object.

Initializes a new specialized object which can subsequently be used to synchronize real-time activities. Xenomai provides a basic synchronization object which can be used to build higher resource objects. Xenomai threads can wait for and signal such objects in order to synchronize their activities.

This object has built-in support for priority inheritance.

Parameters:
synch The address of a synchronization object descriptor Xenomai will use to store the object-specific data. This descriptor must always be valid while the object is active therefore it must be allocated in permanent memory.
flags A set of creation flags affecting the operation. The valid flags are:
  • XNSYNCH_PRIO causes the threads waiting for the resource to pend in priority order. Otherwise, FIFO ordering is used (XNSYNCH_FIFO).

  • XNSYNCH_PIP causes the priority inheritance mechanism to be automatically activated when a priority inversion is detected among threads using this object. Otherwise, no priority inheritance takes place upon priority inversion (XNSYNCH_NOPIP).

Side-effect: This routine does not call the rescheduling procedure.

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

void xnsynch_release_all_ownerships xnthread_t *  thread  ) 
 

Release all ownerships - INTERNAL.

This call is used internally to release all the ownerships obtained by a thread on synchronization objects. This routine must be entered interrupts off.

Parameters:
thread The descriptor address of the affected thread.

void xnsynch_renice_sleeper xnthread_t *  thread  ) 
 

Change a sleeper's priority - INTERNAL.

This service is used by the PIP code to update the pending priority of a sleeping thread.

Parameters:
thread The descriptor address of the affected thread.

void xnsynch_sleep_on xnsynch_t *  synch,
xnticks_t  timeout,
xnmutex_t *  imutex
 

Sleep on a synchronization object.

Makes the calling thread sleep on the specified synchronization object, waiting for it to be signaled.

This service should be called by upper interfaces wanting the current thread to pend on the given resource.

Parameters:
synch The descriptor address of the synchronization object to sleep on.
timeout The timeout which may be used to limit the time the thread pends on the resource. This value is a count of ticks. Passing XN_INFINITE specifies an unbounded wait. All other values are used to initialize a nanokernel watchdog timer.
imutex The address of an interface mutex currently held by the caller which will be subject to a lock-breaking preemption before the current thread is actually switched out. The corresponding kernel mutex will be automatically reacquired by the nanokernel when the suspended thread is eventually resumed, before xnsynch_sleep_on() returns to its caller. Passing NULL when no lock breaking is required is valid. See xnpod_schedule() for more on lock-breaking preemption.
Side-effect: This routine always calls the rescheduling procedure.

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

void xnsynch_wakeup_one_sleeper xnsynch_t *  synch  ) 
 

Give the resource ownership to the next waiting thread.

This service gives the ownership of a synchronization object to the thread which is currently leading the object's pending list. The sleeping thread is unblocked, but no action is taken regarding the previous owner of the resource.

This service should be called by upper interfaces wanting to signal the given resource so that a single waiter is resumed.

Parameters:
synch The descriptor address of the synchronization object whose ownership is changed.
Returns:
The descriptor address of the unblocked thread.
Side-effects:

  • The effective priority of the previous resource owner might be lowered to its base priority value as a consequence of the priority inheritance boost being cleared.

  • The synchronization object ownership is transfered to the unblocked thread.

  • This routine does not call the rescheduling procedure.

Context: This routine must be called on behalf of a thread or IST context.

void xnsynch_wakeup_this_sleeper xnsynch_t *  synch,
xnpholder_t *  holder
 

Give the resource ownership to a given waiting thread.

This service gives the ownership of a given synchronization object to a specific thread which is currently pending on it. The sleeping thread is unblocked from its pending state. No action is taken regarding the previous resource owner.

This service should be called by upper interfaces wanting to signal the given resource so that a specific waiter is resumed.

Parameters:
synch The descriptor address of the synchronization object whose ownership is changed.
holder The link holder address of the thread to unblock (&thread->plink) which MUST currently be linked to the synchronization object's pending queue (i.e. synch->pendq).
Returns:
The link address of the unblocked thread in the synchronization object's pending queue.
Side-effects:

  • The effective priority of the previous resource owner might be lowered to its base priority value as a consequence of the priority inheritance boost being cleared.

  • The synchronization object ownership is transfered to the unblocked thread.

  • This routine does not call the rescheduling procedure.

Context: This routine must be called on behalf of a thread or IST context.


Generated on Sat Jul 24 19:36:22 2004 for RTAI API by doxygen 1.3.4