Collaboration diagram for Thread synchronization services.:

Files
file	synch.c
	Thread synchronization services.
Functions
void	xnsynch_init (struct xnsynch synch, xnflags_t flags, xnarch_atomic_t fastlock)
	Initialize a synchronization object.
xnflags_t	xnsynch_sleep_on (struct xnsynch *synch, xnticks_t timeout, xntmode_t timeout_mode)
	Sleep on an ownerless synchronization object.
struct xnthread *	xnsynch_wakeup_one_sleeper (struct xnsynch *synch)
	Give the resource ownership to the next waiting thread.
struct xnpholder *	xnsynch_wakeup_this_sleeper (struct xnsynch synch, struct xnpholder holder)
	Give the resource ownership to a given waiting thread.
xnflags_t	xnsynch_acquire (struct xnsynch *synch, xnticks_t timeout, xntmode_t timeout_mode)
	Acquire the ownership of a synchronization object.
static void	xnsynch_clear_boost (struct xnsynch synch, struct xnthread owner)
	Clear the priority boost.
void	xnsynch_requeue_sleeper (struct xnthread *thread)
	Change a sleeper's priority.
struct xnthread *	xnsynch_release (struct xnsynch *synch)
	Give the resource ownership to the next waiting thread.
struct xnthread *	xnsynch_peek_pendq (struct xnsynch *synch)
	Access the thread leading a synch object wait queue.
int	xnsynch_flush (struct xnsynch *synch, xnflags_t reason)
	Unblock all waiters pending on a resource.
void	xnsynch_forget_sleeper (struct xnthread *thread)
	Abort a wait for a resource.
void	xnsynch_release_all_ownerships (struct xnthread *thread)
	Release all ownerships.

Detailed Description

Thread synchronization services.

Function Documentation

xnflags_t xnsynch_acquire	(	struct xnsynch *	synch,
		xnticks_t	timeout,
		xntmode_t	timeout_mode
	)

Acquire the ownership of a synchronization object.

This service should be called by upper interfaces wanting the current thread to acquire the ownership of the given resource. If the resource is already assigned to a thread, the caller is suspended.

This service must be used only with synchronization objects that track ownership (XNSYNCH_OWNER set.

Parameters:

synch	The descriptor address of the synchronization object to acquire.
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()).

Returns:: A bitmask which may include zero or one information bit among XNRMID, XNTIMEO and XNBREAK, which should be tested by the caller, for detecting respectively: object deletion, timeout or signal/unblock conditions which might have happened while waiting.

Environments:

This service can be called from:

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

Rescheduling: possible.

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.

References XNBOOST, XNBREAK, XNPEND, xnpod_suspend_thread(), XNRMID, XNROBBED, XNTIMEO, and XNWAKEN.

Referenced by pthread_mutex_destroy(), rt_task_send(), and rtdm_mutex_timedlock().

void xnsynch_clear_boost	(	struct xnsynch *	synch,
		struct xnthread *	owner
	)		`[static]`

Clear the priority boost.

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.

References XNBOOST.

Referenced by xnsynch_flush(), xnsynch_forget_sleeper(), and xnsynch_release().

int xnsynch_flush	(	struct xnsynch *	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.

References XNPEND, xnpod_resume_thread(), and xnsynch_clear_boost().

Referenced by pthread_cond_broadcast(), pthread_detach(), rt_buffer_clear(), rt_cond_broadcast(), rt_sem_broadcast(), rt_task_send(), rtdm_event_signal(), and xnregistry_put().

void xnsynch_forget_sleeper ( struct xnthread * thread )

Abort a wait for a resource.

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.

References XNPEND, and xnsynch_clear_boost().

Referenced by xnpod_delete_thread(), xnpod_resume_thread(), and xnpod_suspend_thread().

void xnsynch_init	(	struct xnsynch *	synch,
		xnflags_t	flags,
		xnarch_atomic_t *	fastlock
	)

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_OWNER indicates that the synchronization object shall track its owning thread (required if XNSYNCH_PIP is selected). Note that setting this flag implies the use xnsynch_acquire and xnsynch_release instead of xnsynch_sleep_on and xnsynch_wakeup_one_sleeper/xnsynch_wakeup_this_sleeper.

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_set_thread_schedparam() 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).

Parameters:

fastlock Address of the fast lock word to be associated with the synchronization object. If NULL is passed or XNSYNCH_OWNER is not set, fast-lock support is disabled.

Environments:

This service can be called from:

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

Rescheduling: never.

Referenced by pthread_cond_init(), pthread_create(), pthread_intr_attach_np(), rt_alarm_create(), rt_buffer_create(), rt_cond_create(), rt_event_create(), rt_heap_create(), rt_intr_create(), rt_queue_create(), rt_sem_create(), rt_task_create(), rtdm_event_init(), rtdm_mutex_init(), rtdm_sem_init(), xnregistry_enter(), and xnselector_init().

struct xnthread* xnsynch_peek_pendq ( struct xnsynch * 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.

struct xnthread* xnsynch_release ( struct xnsynch * synch ) [read]

Give the resource ownership to the next waiting thread.

This service releases the ownership of the given synchronization object. The thread which is currently leading the object's pending list, if any, is unblocked from its pending state. However, no reschedule is performed.

This service must be used only with synchronization objects that track ownership (XNSYNCH_OWNER set).

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.

References XNPEND, xnpod_resume_thread(), xnsynch_clear_boost(), and XNWAKEN.

Referenced by pthread_mutex_unlock(), rt_mutex_release(), and xnsynch_release_all_ownerships().

void xnsynch_release_all_ownerships ( struct xnthread * thread )

Release all ownerships.

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.

References xnsynch_release().

Referenced by xnpod_delete_thread().

void xnsynch_requeue_sleeper ( struct xnthread * thread )

Change a sleeper's priority.

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.

References XNBOOST.

xnflags_t xnsynch_sleep_on	(	struct xnsynch *	synch,
		xnticks_t	timeout,
		xntmode_t	timeout_mode
	)

Sleep on an ownerless 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. It must not be used with synchronization objects that are supposed to track ownership (XNSYNCH_OWNER).

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()).

Returns:: A bitmask which may include zero or one information bit among XNRMID, XNTIMEO and XNBREAK, which should be tested by the caller, for detecting respectively: object deletion, timeout or signal/unblock conditions which might have happened while waiting.

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.

References XNBREAK, XNPEND, xnpod_suspend_thread(), XNRMID, and XNTIMEO.

Referenced by pthread_join(), rt_heap_alloc(), rt_task_receive(), rtdm_event_timedwait(), rtdm_sem_timeddown(), xnregistry_bind(), xnregistry_remove_safe(), and xnselect().

struct xnthread* xnsynch_wakeup_one_sleeper ( struct xnsynch * synch ) [read]

Give the resource ownership to the next waiting thread.

This service wakes up the thread which is currently leading the synchronization object's pending list. The sleeping thread is unblocked from its pending state, but no reschedule is performed.

This service should be called by upper interfaces wanting to signal the given resource so that a single waiter is resumed. It must not be used with synchronization objects that are supposed to track ownership (XNSYNCH_OWNER not set).

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.

References XNPEND, and xnpod_resume_thread().

Referenced by pthread_cond_signal(), pthread_join(), rt_cond_signal(), rt_queue_send(), rt_sem_v(), rtdm_sem_up(), and sem_post().

struct xnpholder* xnsynch_wakeup_this_sleeper	(	struct xnsynch *	synch,
		struct xnpholder *	holder
	)		`[read]`

Give the resource ownership to a given waiting thread.

This service wakes up a specific thread which is currently pending on the given synchronization object. The sleeping thread is unblocked from its pending state, but no reschedule is performed.

This service should be called by upper interfaces wanting to signal the given resource so that a specific waiter is resumed. It must not be used with synchronization objects that are supposed to track ownership (XNSYNCH_OWNER not set).

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.

References XNPEND, and xnpod_resume_thread().

Referenced by rt_event_signal(), and rt_heap_free().

Files

Functions

Detailed Description

Function Documentation