Thread synchronization services

Collaboration diagram for Thread synchronization services:

Functions
void	xnsynch_init (struct xnsynch *synch, int flags, atomic_t *fastlock)
	Initialize a synchronization object. More...
void	xnsynch_init_protect (struct xnsynch *synch, int flags, atomic_t *fastlock, u32 *ceiling_ref)
	Initialize a synchronization object enforcing PP. More...
int	xnsynch_destroy (struct xnsynch *synch)
	Destroy a synchronization object. More...
int __must_check	xnsynch_sleep_on (struct xnsynch *synch, xnticks_t timeout, xntmode_t timeout_mode)
	Sleep on an ownerless synchronization object. More...
struct xnthread *	xnsynch_wakeup_one_sleeper (struct xnsynch *synch)
	Unblock the heading thread from wait. More...
void	xnsynch_wakeup_this_sleeper (struct xnsynch *synch, struct xnthread *sleeper)
	Unblock a particular thread from wait. More...
int __must_check	xnsynch_acquire (struct xnsynch *synch, xnticks_t timeout, xntmode_t timeout_mode)
	Acquire the ownership of a synchronization object. More...
int __must_check	xnsynch_try_acquire (struct xnsynch *synch)
	Try acquiring the ownership of a synchronization object. More...
bool	xnsynch_release (struct xnsynch *synch, struct xnthread *thread)
	Release a resource and pass it to the next waiting thread. More...
struct xnthread *	xnsynch_peek_pendq (struct xnsynch *synch)
	Access the thread leading a synch object wait queue. More...
int	xnsynch_flush (struct xnsynch *synch, int reason)
	Unblock all waiters pending on a resource. More...

Detailed Description

Function Documentation

xnsynch_acquire()

int 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 another 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 as a count of nanoseconds. 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.

Tags

primary-only, might-switch

Note

Unlike xnsynch_try_acquire(), this call does NOT check for invalid recursive locking request, which means that such request will always cause a deadlock for the caller.

xnsynch_destroy()

int xnsynch_destroy

(

struct xnsynch *

synch

)

Destroy a synchronization object.

Destroys the synchronization object synch, unblocking all waiters with the XNRMID status.

Returns

XNSYNCH_RESCHED is returned if at least one thread is unblocked, which means the caller should invoke xnsched_run() for applying the new scheduling state. Otherwise, XNSYNCH_DONE is returned.

Side effects

Same as xnsynch_flush().

Tags

task-unrestricted

xnsynch_flush()

int xnsynch_flush	(	struct xnsynch *	synch,
		int	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 Cobalt:

• XNRMID should be set to indicate that the synchronization object is about to be destroyed (see xnthread_resume()).
• XNBREAK should be set to indicate that the wait has been forcibly interrupted (see xnthread_unblock()).

Returns

XNSYNCH_RESCHED is returned if at least one thread is unblocked, which means the caller should invoke xnsched_run() for applying the new scheduling state. Otherwise, XNSYNCH_DONE is returned.

Side effects

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

Tags

unrestricted

xnsynch_init()

void xnsynch_init	(	struct xnsynch *	synch,
		int	flags,
		atomic_t *	fastlock
	)

Initialize a synchronization object.

Initializes a synchronization object. Xenomai threads can wait on and signal such objects for serializing access to resources. This object has built-in support for priority inheritance.

Parameters

synch	The address of a synchronization object descriptor Cobalt 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 the resource ownership, allowing a single owner at most at any point in time. Note that setting this flag implies the use of xnsynch_acquire() and xnsynch_release() instead of xnsynch_sleep_on() and xnsynch_wakeup_*().
• XNSYNCH_PI enables priority inheritance when a priority inversion is detected among threads using this object. XNSYNCH_PI implies XNSYNCH_OWNER and XNSYNCH_PRIO.
• XNSYNCH_PP enables priority protect to prevent priority inversion. XNSYNCH_PP implies XNSYNCH_OWNER and XNSYNCH_PRIO.
• XNSYNCH_DREORD (Disable REORDering) tells Cobalt not to reorder the wait list upon priority change of a waiter. Reordering is the default. Only applies when XNSYNCH_PRIO is present.

Parameters

fastlock

Address of the fast lock word to be associated with a synchronization object with ownership tracking. Therefore, a valid fast-lock address is required if XNSYNCH_OWNER is set in flags.

Tags

task-unrestricted

Referenced by xnsynch_init_protect().

xnsynch_init_protect()

void xnsynch_init_protect	(	struct xnsynch *	synch,
		int	flags,
		atomic_t *	fastlock,
		u32 *	ceiling_ref
	)

Initialize a synchronization object enforcing PP.

This call is a variant of xnsynch_init() for initializing synchronization objects enabling the priority protect protocol.

Parameters

synch	The address of a synchronization object descriptor Cobalt will use to store the object-specific data. See xnsynch_init().
flags	A set of creation flags affecting the operation. See xnsynch_init(). XNSYNCH_PI is mutually exclusive with XNSYNCH_PP, and won't be considered.
fastlock	Address of the fast lock word to be associated with a synchronization object with ownership tracking. See xnsynch_init().
ceiling_ref	The address of the variable holding the current priority ceiling value for this object.

Tags

task-unrestricted

References xnsynch_init().

xnsynch_peek_pendq()

struct xnthread * xnsynch_peek_pendq

(

struct xnsynch *

synch

)

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.

Tags

unrestricted

xnsynch_release()

bool xnsynch_release	(	struct xnsynch *	synch,
		struct xnthread *	curr
	)

Release a resource and pass it 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.
curr	The descriptor address of the current thread, which must own the object at the time of calling.

Returns

True if a reschedule is required.

Side effects

• The effective priority of the previous resource owner might be lowered to its base priority value as a consequence of the priority boost being cleared.
• The synchronization object ownership is transfered to the unblocked thread.

Tags

primary-only, might-switch

xnsynch_sleep_on()

int 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 as a count of nanoseconds. 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.

Tags

primary-only, might-switch

xnsynch_try_acquire()

int xnsynch_try_acquire

(

struct xnsynch *

synch

)

Try acquiring 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 another thread, the call returns with an error code.

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.

Returns

Zero is returned if synch has been successfully acquired. Otherwise:

• -EDEADLK is returned if synch is currently held by the calling thread.
• -EBUSY is returned if synch is currently held by another thread.

Tags

primary-only

xnsynch_wakeup_one_sleeper()

struct xnthread * xnsynch_wakeup_one_sleeper

(

struct xnsynch *

synch

)

Unblock the heading thread from wait.

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.

Tags

unrestricted

xnsynch_wakeup_this_sleeper()

void xnsynch_wakeup_this_sleeper	(	struct xnsynch *	synch,
		struct xnthread *	sleeper
	)

Unblock a particular thread from wait.

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.
sleeper	The thread to unblock which MUST be currently linked to the synchronization object's pending queue (i.e. synch->pendq).

Tags

unrestricted