Thread synchronization services.
[Xenomai nucleus.]

Collaboration diagram for Thread synchronization services.:

---

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, xntmode_t timeout_mode)
	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.
xnthread_t *	xnsynch_peek_pendq (xnsynch_t *synch)
	Access the thread leading a synch object wait queue.
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.

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

xnthread_t* xnsynch_peek_pendq

(

xnsynch_t *

synch

)

[read]

Access the thread leading a synch object wait queue.

This services returns the descriptor address of to the thread leading a synchronization object wait queue.

Parameters:

synch

The descriptor address of the target synchronization object.

Returns:

The descriptor address of 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_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,
		xntmode_t	timeout_mode
	)

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 wait time given in ticks (see note). It can either be relative, absolute monotonic, or absolute adjustable depending on timeout_mode. Passing XN_INFINITE and setting mode to XN_RELATIVE specifies an unbounded wait. All other values are used to initialize a watchdog timer.
	timeout_mode	The mode of the timeout parameter. It can either be set to XN_RELATIVE, XN_ABSOLUTE, or XN_REALTIME (see also xntimer_start()).

Environments:

This service can be called from:

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

Rescheduling: always.

Note:

The timeout value will be interpreted as jiffies if the current thread is bound to a periodic time base (see xnpod_init_thread), or nanoseconds otherwise.

xnthread_t* xnsynch_wakeup_one_sleeper

(

xnsynch_t *

synch

)

[read]

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.

xnpholder_t* 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 next waiting 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.

---