Xenomai  3.0.8
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...
 
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...
 
struct xnthread * xnsynch_release (struct xnsynch *synch, struct xnthread *thread)
 Give the resource ownership 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
synchThe descriptor address of the synchronization object to acquire.
timeoutThe 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_modeThe 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 cobalt-core-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.

References xnthread_current().

◆ 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 cobalt-core-tags "task-unrestricted"

References XNRMID, and xnsynch_flush().

◆ 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
synchThe descriptor address of the synchronization object to be flushed.
reasonSome 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 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 previous resource owner might be lowered to its base priority value as a consequence of the priority inheritance boost being cleared.
  • After this operation has completed, the synchronization object is not owned by any thread.
Tags cobalt-core-tags "unrestricted"

Referenced by xnsynch_destroy().

◆ 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
synchThe 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.
flagsA 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_PIP enables priority inheritance when a priority inversion is detected among threads using this object. XNSYNCH_PIP enables XNSYNCH_OWNER and XNSYNCH_PRIO implicitly.
  • 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 xnthread_set_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
fastlockAddress 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 cobalt-core-tags "task-unrestricted"

Referenced by xnselector_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
synchThe descriptor address of the target synchronization object.
Returns
The descriptor address of the unblocked thread.
Tags cobalt-core-tags "unrestricted"

◆ xnsynch_release()

struct xnthread * xnsynch_release ( struct xnsynch *  synch,
struct xnthread *  thread 
)

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
synchThe descriptor address of the synchronization object whose ownership is changed.
threadThe descriptor address of the current owner.
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.
Tags cobalt-core-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
synchThe descriptor address of the synchronization object to sleep on.
timeoutThe 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_modeThe 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 cobalt-core-tags "primary-only, might-switch"

References xnthread_current().

◆ 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
synchThe 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 cobalt-core-tags "primary-only"

References xnthread_current().

◆ 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
synchThe descriptor address of the synchronization object whose ownership is changed.
Returns
The descriptor address of the unblocked thread.
Tags cobalt-core-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
synchThe descriptor address of the synchronization object whose ownership is changed.
sleeperThe thread to unblock which MUST be currently linked to the synchronization object's pending queue (i.e. synch->pendq).
Tags cobalt-core-tags "unrestricted"