Thread synchronization services.
[Xenomai nucleus.]

---

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)
	Sleep on a synchronization object.
static void	xnsynch_clear_boost (xnsynch_t *synch, xnthread_t *lastowner)
	Clear the priority boost.
void	xnsynch_renice_sleeper (xnthread_t *thread)
	Change a sleeper's priority.
xnthread_t *	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.
void	xnsynch_release_all_ownerships (xnthread_t *thread)
	Release all ownerships.

---

Function Documentation

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

Clear the priority boost. For internal use only. 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. Note: This routine must be entered nklock locked, interrupts off.

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 to be flushed. reason  Some flags to set in the information mask of every unblocked thread. Zero is an acceptable value. The following bits are pre-defined by the nucleus: XNRMID should be set to indicate that the synchronization object is about to be destroyed (see xnpod_resume_thread()). XNBREAK should be set to indicate that the wait has been forcibly interrupted (see xnpod_unblock_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. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine Kernel-based task User-space task Rescheduling: never.

void xnsynch_forget_sleeper (  xnthread_t *  thread  )

Abort a wait for a resource. For internal use only. 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. Note: This routine must be entered nklock locked, interrupts off.

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. The Xenomai nucleus provides a basic synchronization object which can be used to build higher resource objects. Nucleus 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 the nucleus 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). XNSYNCH_DREORD (Disable REORDering) tells the nucleus that the wait queue should not be reordered whenever the priority of a blocked thread it holds is changed. If this flag is not specified, changing the priority of a blocked thread using xnpod_renice_thread() will cause this object's wait queue to be reordered according to the new priority level, provided the synchronization object makes the waiters wait by priority order on the awaited resource (XNSYNCH_PRIO). Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task Rescheduling: never.

void xnsynch_release_all_ownerships (  xnthread_t *  thread  )

Release all ownerships. For internal use only. 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. Note: This routine must be entered nklock locked, interrupts off.

void xnsynch_renice_sleeper (  xnthread_t *  thread  )

Change a sleeper's priority. For internal use only. 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. Note: This routine must be entered nklock locked, interrupts off.

void xnsynch_sleep_on (  xnsynch_t *  synch, xnticks_t  timeout )

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 (see note). Passing XN_INFINITE specifies an unbounded wait. All other values are used to initialize a nucleus watchdog timer. Environments: This service can be called from: Kernel module initialization/cleanup code Kernel-based task User-space task Rescheduling: always. Note: This service is sensitive to the current operation mode of the system timer, as defined by the xnpod_start_timer() service. In periodic mode, clock ticks are interpreted as periodic jiffies. In oneshot mode, clock ticks are interpreted as nanoseconds.

xnthread_t * 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. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine Kernel-based task User-space task Rescheduling: never.

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 be currently 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. Environments: This service can be called from: Kernel module initialization/cleanup code Interrupt service routine Kernel-based task User-space task Rescheduling: never.

---