This handler provides the capability to have threads block in ordered sets. More...

Collaboration diagram for Thread Queue Handler:

Data Structures
struct	Thread_queue_Operations
	Thread queue operations. More...

struct	Thread_queue_Control
	This is the structure used to manage sets of tasks which are blocked waiting to acquire a resource. More...

Macros
#define	THREAD_QUEUE_FIFO_INITIALIZER(designator, name)

#define	THREAD_QUEUE_PRIORITY_INITIALIZER(designator, name)

Typedefs
typedef struct Thread_Control	Thread_Control

typedef struct Thread_queue_Control	Thread_queue_Control

typedef void(*	Thread_queue_Priority_change_operation) (Thread_Control the_thread, Priority_Control new_priority, Thread_queue_Control the_thread_queue)
	Thread queue priority change operation. More...

typedef void(*	Thread_queue_Initialize_operation) (Thread_queue_Control *the_thread_queue)
	Thread queue initialize operation. More...

typedef void(*	Thread_queue_Enqueue_operation) (Thread_queue_Control the_thread_queue, Thread_Control the_thread)
	Thread queue enqueue operation. More...

typedef void(*	Thread_queue_Extract_operation) (Thread_queue_Control the_thread_queue, Thread_Control the_thread)
	Thread queue extract operation. More...

typedef Thread_Control (	Thread_queue_First_operation) (Thread_queue_Control *the_thread_queue)
	Thread queue first operation. More...

typedef void(*	Thread_queue_Flush_callout) (Thread_Control *)
	The following type defines the callout used when a remote task is extracted from a local thread queue.

Enumerations
enum	Thread_queue_Disciplines { THREAD_QUEUE_DISCIPLINE_FIFO, THREAD_QUEUE_DISCIPLINE_PRIORITY }
	The following enumerated type details all of the disciplines supported by the Thread Queue Handler.

Functions
RTEMS_INLINE_ROUTINE void	_Thread_queue_Acquire_critical (Thread_queue_Control the_thread_queue, ISR_lock_Context lock_context)

RTEMS_INLINE_ROUTINE void	_Thread_queue_Acquire (Thread_queue_Control the_thread_queue, ISR_lock_Context lock_context)

RTEMS_INLINE_ROUTINE void	_Thread_queue_Release (Thread_queue_Control the_thread_queue, ISR_lock_Context lock_context)

Thread_Control *	_Thread_queue_Dequeue (Thread_queue_Control *the_thread_queue)
	Gets a pointer to a thread waiting on the_thread_queue. More...

void	_Thread_queue_Enqueue_critical (Thread_queue_Control the_thread_queue, Thread_Control the_thread, States_Control state, Watchdog_Interval timeout, uint32_t timeout_code, ISR_lock_Context *lock_context)
	Blocks the thread and places it on the thread queue. More...

RTEMS_INLINE_ROUTINE void	_Thread_queue_Enqueue (Thread_queue_Control the_thread_queue, Thread_Control the_thread, States_Control state, Watchdog_Interval timeout, uint32_t timeout_code)
	Acquires the thread queue lock and calls _Thread_queue_Enqueue_critical().

void	_Thread_queue_Extract_locked (Thread_queue_Control the_thread_queue, Thread_Control the_thread)
	Extracts the thread from the thread queue, restores the default wait operations and restores the default thread lock. More...

void	_Thread_queue_Unblock_critical (Thread_queue_Control the_thread_queue, Thread_Control the_thread, ISR_lock_Context *lock_context)
	Unblocks the thread which was on the thread queue before. More...

void	_Thread_queue_Extract_critical (Thread_queue_Control the_thread_queue, Thread_Control the_thread, ISR_lock_Context *lock_context)
	Extracts the thread from the thread queue and unblocks it. More...

void	_Thread_queue_Extract (Thread_Control *the_thread)
	Extracts thread from thread queue. More...

void	_Thread_queue_Extract_with_proxy (Thread_Control *the_thread)
	Extracts the_thread from the_thread_queue. More...

RTEMS_INLINE_ROUTINE Thread_Control *	_Thread_queue_First_locked (Thread_queue_Control *the_thread_queue)
	Returns the first thread on the thread queue if it exists, otherwise `NULL`. More...

Thread_Control *	_Thread_queue_First (Thread_queue_Control *the_thread_queue)
	Returns the first thread on the thread queue if it exists, otherwise `NULL`. More...

void	_Thread_queue_Flush (Thread_queue_Control *the_thread_queue, Thread_queue_Flush_callout remote_extract_callout, uint32_t status)
	Unblocks all threads blocked on the_thread_queue. More...

void	_Thread_queue_Initialize (Thread_queue_Control *the_thread_queue, Thread_queue_Disciplines the_discipline)
	Initialize the_thread_queue. More...

RTEMS_INLINE_ROUTINE void	_Thread_queue_Destroy (Thread_queue_Control *the_thread_queue)

RBTree_Compare_result	_Thread_queue_Compare_priority (const RBTree_Node left, const RBTree_Node right)
	Compare two thread's priority for RBTree Insertion. More...

Variables
const Thread_queue_Operations	_Thread_queue_Operations_default

const Thread_queue_Operations	_Thread_queue_Operations_FIFO

const Thread_queue_Operations	_Thread_queue_Operations_priority

Detailed Description

This handler provides the capability to have threads block in ordered sets.

The sets may be ordered using the FIFO or priority discipline.

Macro Definition Documentation

◆ THREAD_QUEUE_FIFO_INITIALIZER

#define THREAD_QUEUE_FIFO_INITIALIZER	(	designator,
		name
	)

Value:

{ \
      .Queues = { \
        .Fifo = CHAIN_INITIALIZER_EMPTY( designator.Queues.Fifo ) \
      }, \
      .operations = &_Thread_queue_Operations_FIFO \
    }

◆ THREAD_QUEUE_PRIORITY_INITIALIZER

#define THREAD_QUEUE_PRIORITY_INITIALIZER	(	designator,
		name
	)

Value:

{ \
      .Queues = { \
        .Priority = RBTREE_INITIALIZER_EMPTY( designator.Queues.Priority ) \
      }, \
      .operations = &_Thread_queue_Operations_priority \
    }

Typedef Documentation

◆ Thread_queue_Enqueue_operation

typedef void( * Thread_queue_Enqueue_operation) (Thread_queue_Control *the_thread_queue, Thread_Control *the_thread)

Thread queue enqueue operation.

Parameters

[in]	the_thread_queue	The thread queue.
[in]	the_thread	The thread to enqueue on the queue.

See also: _Thread_Wait_set_operations().

◆ Thread_queue_Extract_operation

typedef void( * Thread_queue_Extract_operation) (Thread_queue_Control *the_thread_queue, Thread_Control *the_thread)

Thread queue extract operation.

Parameters

[in]	the_thread_queue	The thread queue.
[in]	the_thread	The thread to extract from the thread queue.

See also: _Thread_Wait_set_operations().

◆ Thread_queue_First_operation

typedef Thread_Control*( * Thread_queue_First_operation) (Thread_queue_Control *the_thread_queue)

Thread queue first operation.

Parameters

[in] the_thread_queue The thread queue.

Return values

NULL	No thread is present on the thread queue.
first	The first thread of the thread queue according to the insert order. This thread remains on the thread queue.

See also: _Thread_Wait_set_operations().

◆ Thread_queue_Initialize_operation

typedef void( * Thread_queue_Initialize_operation) (Thread_queue_Control *the_thread_queue)

Thread queue initialize operation.

Parameters

[in] the_thread_queue The thread queue.

See also: _Thread_Wait_set_operations().

◆ Thread_queue_Priority_change_operation

typedef void( * Thread_queue_Priority_change_operation) (Thread_Control *the_thread, Priority_Control new_priority, Thread_queue_Control *the_thread_queue)

Thread queue priority change operation.

Parameters

[in]	the_thread	The thread.
[in]	new_priority	The new priority value.
[in]	the_thread_queue	The thread queue.

See also: Thread_queue_Operations.

Function Documentation

◆ _Thread_queue_Compare_priority()

RBTree_Compare_result _Thread_queue_Compare_priority	(	const RBTree_Node *	left,
		const RBTree_Node *	right
	)

Compare two thread's priority for RBTree Insertion.

Parameters

[in]	left	points to the left thread's RBnode
[in]	right	points to the right thread's RBnode

Return values

1	The left node is more important than right node.
0	The left node is of equal importance with right node.
1	The left node is less important than right node.

◆ _Thread_queue_Dequeue()

Thread_Control* _Thread_queue_Dequeue ( Thread_queue_Control * the_thread_queue )

Gets a pointer to a thread waiting on the_thread_queue.

This function returns a pointer to a thread waiting on the_thread_queue. The selection of this thread is based on the discipline of the_thread_queue. If no threads are waiting on the_thread_queue, then NULL is returned.

INTERRUPT LATENCY:
- single case

Referenced by _CORE_barrier_Release().

◆ _Thread_queue_Enqueue_critical()

void _Thread_queue_Enqueue_critical	(	Thread_queue_Control *	the_thread_queue,
		Thread_Control *	the_thread,
		States_Control	state,
		Watchdog_Interval	timeout,
		uint32_t	timeout_code,
		ISR_lock_Context *	lock_context
	)

Blocks the thread and places it on the thread queue.

This enqueues the thread on the thread queue, blocks the thread, and optionally starts the thread timer in case the timeout interval is not WATCHDOG_NO_TIMEOUT.

The caller must be the owner of the thread queue lock. This function will release the thread queue lock and register it as the new thread lock. Thread dispatching is disabled before the thread queue lock is released. Thread dispatching is enabled once the sequence to block the thread is complete. The operation to enqueue the thread on the queue is protected by the thread queue lock. This makes it possible to use the thread queue lock to protect the state of objects embedding the thread queue and directly enter _Thread_queue_Enqueue_critical() in case the thread must block.

#include <rtems/score/threadqimpl.h>
#include <rtems/score/statesimpl.h>
typedef struct {
  Thread_queue_Control  Queue;
  Thread_Control       *owner;
} Mutex;
void _Mutex_Obtain( Mutex *mutex )
{
  ISR_lock_Context  lock_context;
  Thread_Control   *executing;
  _Thread_queue_Acquire( &mutex->Queue, &lock_context );
  executing = _Thread_Executing;
  if ( mutex->owner == NULL ) {
    mutex->owner = executing;
    _Thread_queue_Release( &mutex->Queue, &lock_context );
  } else {
    _Thread_queue_Enqueue_critical(
      &mutex->Queue,
      executing,
      STATES_WAITING_FOR_MUTEX,
      WATCHDOG_NO_TIMEOUT,
      0,
      &lock_context
    );
  }
}

Parameters

[in]	the_thread_queue	The thread queue.
[in]	the_thread	The thread to enqueue.
[in]	state	The new state of the thread.
[in]	timeout	Interval to wait. Use WATCHDOG_NO_TIMEOUT to block potentially forever.
[in]	timeout_code	The return code in case a timeout occurs.
[in]	lock_context	The lock context of the lock acquire.

◆ _Thread_queue_Extract()

void _Thread_queue_Extract ( Thread_Control * the_thread )

Extracts thread from thread queue.

This routine removes the_thread its thread queue and cancels any timeouts associated with this blocking.

Parameters

[in] the_thread is the pointer to a thread control block that is to be removed

◆ _Thread_queue_Extract_critical()

void _Thread_queue_Extract_critical	(	Thread_queue_Control *	the_thread_queue,
		Thread_Control *	the_thread,
		ISR_lock_Context *	lock_context
	)

Extracts the thread from the thread queue and unblocks it.

The caller must be the owner of the thread queue lock. This function will release the thread queue lock and restore the default thread lock. Thread dispatching is disabled before the thread queue lock is released and an unblock is necessary. Thread dispatching is enabled once the sequence to unblock the thread is complete. This makes it possible to use the thread queue lock to protect the state of objects embedding the thread queue and directly enter _Thread_queue_Extract_critical() to finalize an operation in case a waiting thread exists.

#include <rtems/score/threadqimpl.h>
typedef struct {
  Thread_queue_Control  Queue;
  Thread_Control       *owner;
} Mutex;
void _Mutex_Release( Mutex *mutex )
{
  ISR_lock_Context  lock_context;
  Thread_Control   *first;
  _Thread_queue_Acquire( &mutex->Queue, &lock_context );
  first = _Thread_queue_First_locked( &mutex->Queue );
  mutex->owner = first;
  if ( first != NULL ) {
    _Thread_queue_Extract_critical(
      &mutex->Queue,
      first,
      &lock_context
  );
}

Parameters

[in]	the_thread_queue	The thread queue.
[in]	the_thread	The thread to extract.
[in]	lock_context	The lock context of the lock acquire.

References _Thread_queue_Extract_locked(), and _Thread_queue_Unblock_critical().

◆ _Thread_queue_Extract_locked()

void _Thread_queue_Extract_locked	(	Thread_queue_Control *	the_thread_queue,
		Thread_Control *	the_thread
	)

Extracts the thread from the thread queue, restores the default wait operations and restores the default thread lock.

The caller must be the owner of the thread queue lock. The thread queue lock is not released.

Parameters

[in]	the_thread_queue	The thread queue.
[in]	the_thread	The thread to extract.

References _Thread_Lock_restore_default, _Thread_Wait_restore_default_operations(), _Thread_Wait_set_queue(), Thread_queue_Operations::extract, and Thread_queue_Control::operations.

Referenced by _Thread_queue_Extract_critical().

◆ _Thread_queue_Extract_with_proxy()

void _Thread_queue_Extract_with_proxy ( Thread_Control * the_thread )

Extracts the_thread from the_thread_queue.

This routine extracts the_thread from the_thread_queue and ensures that if there is a proxy for this task on another node, it is also dealt with.

Extracts the_thread from the_thread_queue.

This routine extracts the_thread from the_thread_queue and ensures that if there is a proxy for this task on another node, it is also dealt with. A proxy is a data data that is on the thread queue on the remote node and acts as a proxy for the local thread. If the local thread was waiting on a remote operation, then the remote side of the operation must be cleaned up.

◆ _Thread_queue_First()

Thread_Control* _Thread_queue_First ( Thread_queue_Control * the_thread_queue )

Returns the first thread on the thread queue if it exists, otherwise NULL.

Parameters

[in] the_thread_queue The thread queue.

Return values

NULL	No thread is present on the thread queue.
first	The first thread on the thread queue according to the enqueue order.

Referenced by _Thread_queue_First_locked().

◆ _Thread_queue_First_locked()

RTEMS_INLINE_ROUTINE Thread_Control* _Thread_queue_First_locked ( Thread_queue_Control * the_thread_queue )

Returns the first thread on the thread queue if it exists, otherwise NULL.

The caller must be the owner of the thread queue lock. The thread queue lock is not released.

Parameters

[in] the_thread_queue The thread queue.

Return values

NULL	No thread is present on the thread queue.
first	The first thread on the thread queue according to the enqueue order.

References _Thread_queue_First(), _Thread_queue_Flush(), Thread_queue_Operations::first, and Thread_queue_Control::operations.

◆ _Thread_queue_Flush()

void _Thread_queue_Flush	(	Thread_queue_Control *	the_thread_queue,
		Thread_queue_Flush_callout	remote_extract_callout,
		uint32_t	status
	)

Unblocks all threads blocked on the_thread_queue.

This routine unblocks all threads blocked on the_thread_queue and cancels any associated timeouts.

Parameters

[in]	the_thread_queue	is the pointer to a threadq header
[in]	remote_extract_callout	points to a method to invoke to invoke when a remote thread is unblocked
[in]	status	is the status which will be returned to all unblocked threads

Referenced by _Thread_queue_First_locked().

◆ _Thread_queue_Initialize()

void _Thread_queue_Initialize	(	Thread_queue_Control *	the_thread_queue,
		Thread_queue_Disciplines	the_discipline
	)

Initialize the_thread_queue.

This routine initializes the_thread_queue based on the discipline indicated in attribute_set. The state set on threads which block on the_thread_queue is state.

Parameters

[in]	the_thread_queue	is the pointer to a threadq header
[in]	the_discipline	is the queueing discipline

References _ISR_lock_Initialize.

Referenced by _CORE_barrier_Initialize(), _CORE_mutex_Initialize(), _CORE_RWLock_Initialize(), _CORE_semaphore_Initialize(), and pthread_cond_init().

◆ _Thread_queue_Unblock_critical()

void _Thread_queue_Unblock_critical	(	Thread_queue_Control *	the_thread_queue,
		Thread_Control *	the_thread,
		ISR_lock_Context *	lock_context
	)

Unblocks the thread which was on the thread queue before.

The caller must be the owner of the thread queue lock. This function will release the thread queue lock. Thread dispatching is disabled before the thread queue lock is released and an unblock is necessary. Thread dispatching is enabled once the sequence to unblock the thread is complete.

Parameters

[in]	the_thread_queue	The thread queue.
[in]	the_thread	The thread to extract.
[in]	lock_context	The lock context of the lock acquire.

Referenced by _Thread_queue_Extract_critical().

Data Structures

Macros

Typedefs

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ THREAD_QUEUE_FIFO_INITIALIZER

◆ THREAD_QUEUE_PRIORITY_INITIALIZER

Typedef Documentation

◆ Thread_queue_Enqueue_operation

◆ Thread_queue_Extract_operation

◆ Thread_queue_First_operation

◆ Thread_queue_Initialize_operation

◆ Thread_queue_Priority_change_operation

Function Documentation

◆ _Thread_queue_Compare_priority()

◆ _Thread_queue_Dequeue()

◆ _Thread_queue_Enqueue_critical()

◆ _Thread_queue_Extract()

◆ _Thread_queue_Extract_critical()

◆ _Thread_queue_Extract_locked()

◆ _Thread_queue_Extract_with_proxy()

◆ _Thread_queue_First()

◆ _Thread_queue_First_locked()

◆ _Thread_queue_Flush()

◆ _Thread_queue_Initialize()

◆ _Thread_queue_Unblock_critical()