Thread Queue Handler

This group contains the Thread Queue Handler implementation. More...

Files
file	threadq.h
	This header file provides interfaces of the Thread Queue Handler which are used by the implementation and the Application Configuration.
file	threadqimpl.h
	This header file provides interfaces of the Thread Queue Handler which are only used by the implementation.
file	threadqops.h
	This header file provides interfaces related to thread queue operations.
file	threadq.c
	This source file contains static assertions related to the Thread Queue Handler, the definition of _Thread_queue_Object_name, and the implementation of _Thread_queue_Acquire(), _Thread_queue_Do_acquire_critical(), _Thread_queue_Initialize(), _Thread_queue_MP_callout_do_nothing(), _Thread_queue_Object_initialize(), _Thread_queue_Queue_get_name_and_id(), _Thread_queue_Release(), and _Thread_queue_Release_critical().
file	threadqenqueue.c
	This source file contains the implementation of _Thread_queue_Deadlock_fatal(), _Thread_queue_Deadlock_status(), _Thread_queue_Do_dequeue(), _Thread_queue_Enqueue(), _Thread_queue_Enqueue_do_nothing_extra(), _Thread_queue_Enqueue_sticky(), _Thread_queue_Extract_locked(), _Thread_queue_Path_acquire(), _Thread_queue_Path_release(), _Thread_queue_Resume(),_Thread_queue_Surrender(), _Thread_queue_Surrender_no_priority(), _Thread_queue_Surrender_sticky().
file	threadqextract.c
	This source file contains the implementation of _Thread_queue_Extract().
file	threadqextractwithproxy.c
	This source file contains the implementation of _Thread_MP_Extract_proxy().
file	threadqfirst.c
	This source file contains the implementation of _Thread_queue_First().
file	threadqflush.c
	This source file contains the implementation of _Thread_queue_Flush_default_filter(), _Thread_queue_Flush_status_object_was_deleted(), _Thread_queue_Flush_status_unavailable(), and _Thread_queue_Flush_critical().
file	threadqgetnameandid.c
	This source file contains the implementation of _Thread_queue_Queue_get_name_and_id().
file	threadqops.c
	This source file contains the definition of _Thread_queue_Operations_default, _Thread_queue_Operations_FIFO, _Thread_queue_Operations_priority, and _Thread_queue_Operations_priority_inherit.
file	threadqtimeout.c
	This source file contains the implementation of _Thread_queue_Add_timeout_ticks(), _Thread_queue_Add_timeout_timespec(), _Thread_queue_Add_timeout_monotonic_timespec(), and _Thread_queue_Add_timeout_realtime_timespec().

Data Structures
struct	Thread_queue_Lock_context
struct	Thread_queue_Context
	Thread queue context for the thread queue methods. More...
struct	Thread_queue_Priority_queue
	Thread priority queue. More...
struct	_Thread_queue_Heads
	Thread queue heads. More...
struct	Thread_queue_Queue
struct	Thread_queue_Operations
	The thread queue operations are used to manage the threads of a thread queue. More...
struct	Thread_queue_Control
struct	Thread_queue_Syslock_queue
	Thread queue with a layout compatible to struct _Thread_queue_Queue defined in Newlib <sys/lock.h>. More...
struct	Thread_queue_Object
	Helper structure to ensure that all objects containing a thread queue have the right layout. More...

Macros
#define	THREAD_QUEUE_LINK_OF_PATH_NODE(node)    RTEMS_CONTAINER_OF( node, Thread_queue_Link, Path_node );
#define	_Thread_queue_Context_ISR_disable(queue_context, level)
#define	_Thread_queue_Context_set_MP_callout(queue_context, mp_callout)
	Sets the MP callout in the thread queue context.
#define	_Thread_queue_Queue_acquire_critical(queue, lock_stats, lock_context)    _Thread_queue_Queue_do_acquire_critical( queue, lock_context )
#define	THREAD_QUEUE_INITIALIZER(_name)
#define	THREAD_QUEUE_OBJECT_ASSERT(object_type, wait_queue_member, msg)
#define	THREAD_QUEUE_QUEUE_TO_OBJECT(queue)

Typedefs
typedef struct _Thread_Control	Thread_Control
typedef struct Thread_queue_Context	Thread_queue_Context
typedef struct Thread_queue_Queue	Thread_queue_Queue
typedef struct Thread_queue_Operations	Thread_queue_Operations
typedef void(*	Thread_queue_Enqueue_callout) (Thread_queue_Queue *queue, Thread_Control *the_thread, struct Per_CPU_Control *cpu_self, Thread_queue_Context *queue_context)
	Thread queue enqueue callout.
typedef void(*	Thread_queue_Deadlock_callout) (Thread_Control *the_thread)
	Thread queue deadlock callout.
typedef struct _Thread_queue_Heads	Thread_queue_Heads
	Thread queue heads.
typedef void(*	Thread_queue_Priority_actions_operation) (Thread_queue_Queue *queue, Priority_Actions *priority_actions)
	Thread queue action operation.
typedef void(*	Thread_queue_Enqueue_operation) (Thread_queue_Queue *queue, Thread_Control *the_thread, Thread_queue_Context *queue_context)
	Thread queue enqueue operation.
typedef void(*	Thread_queue_Extract_operation) (Thread_queue_Queue *queue, Thread_Control *the_thread, Thread_queue_Context *queue_context)
	Thread queue extract operation.
typedef Thread_Control *(*	Thread_queue_Surrender_operation) (Thread_queue_Queue *queue, Thread_queue_Heads *heads, Thread_Control *previous_owner, Thread_queue_Context *queue_context)
	Thread queue surrender operation.
typedef Thread_Control *(*	Thread_queue_First_operation) (const Thread_queue_Heads *heads)
	Gets the first thread on the queue.
typedef Thread_Control *(*	Thread_queue_Flush_filter) (Thread_Control *the_thread, Thread_queue_Queue *queue, Thread_queue_Context *queue_context)
	Thread queue flush filter function.

Enumerations
enum	Thread_queue_Deadlock_status { THREAD_QUEUE_NO_DEADLOCK , THREAD_QUEUE_DEADLOCK_DETECTED }
	This is a status code to indicate if a deadlock was detected or not. More...

Functions
void	_Thread_queue_Enqueue_do_nothing_extra (Thread_queue_Queue *queue, Thread_Control *the_thread, Per_CPU_Control *cpu_self, Thread_queue_Context *queue_context)
	Does nothing.
void	_Thread_queue_Add_timeout_ticks (Thread_queue_Queue *queue, Thread_Control *the_thread, Per_CPU_Control *cpu_self, Thread_queue_Context *queue_context)
	Adds timeout ticks of the queue to the thread.
void	_Thread_queue_Add_timeout_monotonic_timespec (Thread_queue_Queue *queue, Thread_Control *the_thread, Per_CPU_Control *cpu_self, Thread_queue_Context *queue_context)
	Adds a monotonic timespec to the thread and sets the watchdog header to monotonic.
void	_Thread_queue_Add_timeout_realtime_timespec (Thread_queue_Queue *queue, Thread_Control *the_thread, Per_CPU_Control *cpu_self, Thread_queue_Context *queue_context)
	Adds a monotonic timespec to the thread and sets the watchdog header to realtime.
void	_Thread_queue_Deadlock_status (Thread_Control *the_thread)
	Sets the thread wait return code to STATUS_DEADLOCK.
void	_Thread_queue_Deadlock_fatal (Thread_Control *the_thread)
	Results in an INTERNAL_ERROR_THREAD_QUEUE_DEADLOCK fatal error.
size_t	_Thread_queue_Queue_get_name_and_id (const Thread_queue_Queue *queue, char *buffer, size_t buffer_size, Objects_Id *id)
	Copies the thread queue name to the specified buffer.
void	_Thread_queue_Enqueue (Thread_queue_Queue *queue, const Thread_queue_Operations *operations, Thread_Control *the_thread, Thread_queue_Context *queue_context)
	Blocks the thread and places it on the thread queue.
bool	_Thread_queue_Extract_locked (Thread_queue_Queue *queue, const Thread_queue_Operations *operations, Thread_Control *the_thread, Thread_queue_Context *queue_context)
	Extracts the thread from the thread queue, restores the default wait operations and restores the default thread lock.
void	_Thread_queue_Resume (Thread_queue_Queue *queue, Thread_Control *the_thread, Thread_queue_Context *queue_context)
	Resumes the extracted or surrendered thread.
void	_Thread_queue_Extract (Thread_Control *the_thread)
	Extracts thread from thread queue.
void	_Thread_queue_Surrender (Thread_queue_Queue *queue, Thread_queue_Heads *heads, Thread_Control *previous_owner, Thread_queue_Context *queue_context, const Thread_queue_Operations *operations)
	Surrenders the thread queue previously owned by the thread to the first enqueued thread.
void	_Thread_queue_Surrender_no_priority (Thread_queue_Queue *queue, Thread_queue_Heads *heads, Thread_queue_Context *queue_context, const Thread_queue_Operations *operations)
	Surrenders the thread queue previously owned by the thread to the first enqueued thread.
Status_Control	_Thread_queue_Surrender_priority_ceiling (Thread_queue_Queue *queue, Thread_Control *executing, Priority_Node *ceiling_priority, Thread_queue_Context *queue_context, const Thread_queue_Operations *operations)
	Surrenders the thread queue previously owned by the thread to the first enqueued thread.
Thread_Control *	_Thread_queue_First (Thread_queue_Control *the_thread_queue, const Thread_queue_Operations *operations)
	Returns the first thread on the thread queue if it exists, otherwise NULL.
Thread_Control *	_Thread_queue_Flush_default_filter (Thread_Control *the_thread, Thread_queue_Queue *queue, Thread_queue_Context *queue_context)
	Default thread queue flush filter function.
Thread_Control *	_Thread_queue_Flush_status_unavailable (Thread_Control *the_thread, Thread_queue_Queue *queue, Thread_queue_Context *queue_context)
	Status unavailable thread queue flush filter function.
Thread_Control *	_Thread_queue_Flush_status_object_was_deleted (Thread_Control *the_thread, Thread_queue_Queue *queue, Thread_queue_Context *queue_context)
	Status object was deleted thread queue flush filter function.
size_t	_Thread_queue_Flush_critical (Thread_queue_Queue *queue, const Thread_queue_Operations *operations, Thread_queue_Flush_filter filter, Thread_queue_Context *queue_context)
	Unblocks all threads enqueued on the thread queue.
void	_Thread_queue_Initialize (Thread_queue_Control *the_thread_queue, const char *name)
	Initializes the thread queue control to the given name.
void	_Thread_queue_Object_initialize (Thread_queue_Control *the_thread_queue)
	Initializes a thread queue embedded in an object with identifier.
void	_Thread_queue_Do_nothing_priority_actions (Thread_queue_Queue *queue, Priority_Actions *priority_actions)
	Initializes the priority actions so that no actions are performed.
void	_Thread_queue_FIFO_enqueue (Thread_queue_Queue *queue, Thread_Control *the_thread, Thread_queue_Context *queue_context)
	Enqueues the thread to the FIFO thread queue.
void	_Thread_queue_FIFO_extract (Thread_queue_Queue *queue, Thread_Control *the_thread, Thread_queue_Context *queue_context)
	Extracts the thread from the FIFO thread queue.
Thread_Control *	_Thread_queue_FIFO_surrender (Thread_queue_Queue *queue, Thread_queue_Heads *heads, Thread_Control *previous_owner, Thread_queue_Context *queue_context)
	Surrenders the thread queue to the first thread on the FIFO thread queue.
Thread_Control *	_Thread_queue_FIFO_first (const Thread_queue_Heads *heads)
	Gets the first thread on the FIFO thread queue.

Variables
const Thread_queue_Operations	_Thread_queue_Operations_default
	The default thread queue operations are used when a thread is not enqueued on a thread queue.
const Thread_queue_Operations	_Thread_queue_Operations_FIFO
	The FIFO thread queue operations are used when a thread is enqueued on a thread queue and provide FIFO ordering of enqueued threads.
const Thread_queue_Operations	_Thread_queue_Operations_priority
	The FIFO thread queue operations are used when a thread is enqueued on a thread queue and provide priority ordering of enqueued threads.
const Thread_queue_Operations	_Thread_queue_Operations_priority_inherit
	The FIFO thread queue operations are used when a thread is enqueued on a thread queue and provide priority ordering of enqueued threads with support for priority inheritance.
const char	_Thread_queue_Object_name []
	The special thread queue name to indicated that the thread queue is embedded in an object with identifier.

Detailed Description

This group contains the Thread Queue Handler implementation.

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_Context_ISR_disable

#define _Thread_queue_Context_ISR_disable	(		queue_context,
			level
	)

Value:

  do { \
    _ISR_Local_disable( level ); \
    _ISR_lock_ISR_disable_profile( \
      &( queue_context )->Lock_context.Lock_context \
    ) \
  } while ( 0 )

_Thread_queue_Context_set_MP_callout

#define _Thread_queue_Context_set_MP_callout	(		queue_context,
			mp_callout
	)

Value:

  do { \
    (void) queue_context; \
  } while ( 0 )

Sets the MP callout in the thread queue context.

Parameters

[out]	queue_context	The thread queue context.
	mp_callout	Callout to unblock the thread in case it is actually a thread proxy. This parameter is only used on multiprocessing configurations. Used by thread queue extract and unblock methods for objects with multiprocessing (MP) support.

THREAD_QUEUE_INITIALIZER

#define THREAD_QUEUE_INITIALIZER

(

_name

)

Value:

    { \
      .Queue = { \
        .heads = NULL, \
        .owner = NULL, \
        .name = _name \
      } \
    }

THREAD_QUEUE_OBJECT_ASSERT

#define THREAD_QUEUE_OBJECT_ASSERT	(		object_type,
			wait_queue_member,
			msg
	)

Value:

  RTEMS_STATIC_ASSERT( \
    offsetof( object_type, wait_queue_member ) \
      == offsetof( Thread_queue_Object, Wait_queue ) \
    && RTEMS_HAVE_MEMBER_SAME_TYPE( \
      object_type, \
      wait_queue_member, \
      Thread_queue_Object, \
      Wait_queue \
    ), \
    msg \
  )

THREAD_QUEUE_QUEUE_TO_OBJECT

#define THREAD_QUEUE_QUEUE_TO_OBJECT

(

queue

)

Value:

  RTEMS_CONTAINER_OF( \
    queue, \
    Thread_queue_Object, \
    Wait_queue.Queue \
  )

Typedef Documentation

Thread_queue_Deadlock_callout

typedef void(* Thread_queue_Deadlock_callout) (Thread_Control *the_thread)

Thread queue deadlock callout.

Parameters

the_thread

The thread that detected the deadlock.

See also

_Thread_queue_Context_set_deadlock_callout().

Thread_queue_Enqueue_callout

typedef void(* Thread_queue_Enqueue_callout) (Thread_queue_Queue *queue, Thread_Control *the_thread, struct Per_CPU_Control *cpu_self, Thread_queue_Context *queue_context)

Thread queue enqueue callout.

Parameters

[in]	queue	The actual thread queue.
[in]	the_thread	The thread to enqueue.
[in]	cpu_self	The current processor.
[in]	queue_context	The thread queue context of the lock acquire.

See also

_Thread_queue_Context_set_enqueue_callout().

Thread_queue_Enqueue_operation

typedef void(* Thread_queue_Enqueue_operation) (Thread_queue_Queue *queue, Thread_Control *the_thread, Thread_queue_Context *queue_context)

Thread queue enqueue operation.

A potential thread to update the priority due to priority inheritance is returned via the thread queue context. This thread is handed over to _Thread_Priority_update().

Parameters

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

Thread_queue_Extract_operation

typedef void(* Thread_queue_Extract_operation) (Thread_queue_Queue *queue, Thread_Control *the_thread, Thread_queue_Context *queue_context)

Thread queue extract operation.

Parameters

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

Thread_queue_First_operation

typedef Thread_Control *(* Thread_queue_First_operation) (const Thread_queue_Heads *heads)

Gets the first thread on the queue.

Parameters

heads

are heads of the thread queue.

Return values

NULL	No thread is enqueued on the thread queue.

Returns

Returns the first thread on the thread queue according to the queue order. This thread remains on the thread queue.

Thread_queue_Flush_filter

typedef Thread_Control *(* Thread_queue_Flush_filter) (Thread_Control *the_thread, Thread_queue_Queue *queue, Thread_queue_Context *queue_context)

Thread queue flush filter function.

Called under protection of the thread queue lock by _Thread_queue_Flush_critical() to optionally alter the thread wait information and control the iteration.

Parameters

the_thread	The thread to extract. This is the first parameter to optimize for architectures that use the same register for the first parameter and the return value.
queue	The actual thread queue.
queue_context	The thread queue context of the lock acquire. May be used to pass additional data to the filter function via an overlay structure. The filter function should not release or acquire the thread queue lock.

Return values

the_thread	Extract this thread.
NULL	Do not extract this thread and stop the thread queue flush operation. Threads that are already extracted will complete the flush operation.

Thread_queue_Heads

typedef struct _Thread_queue_Heads Thread_queue_Heads

Thread queue heads.

Each thread is equipped with spare thread queue heads in case it is not enqueued on a thread queue. The first thread enqueued on a thread queue will give its spare thread queue heads to that thread queue. The threads arriving at the queue will add their thread queue heads to the free chain of the queue heads provided by the first thread enqueued. Once a thread is dequeued it use the free chain to get new spare thread queue heads.

Uses a leading underscore in the structure name to allow forward declarations in standard header files provided by Newlib and GCC.

Thread_queue_Priority_actions_operation

typedef void(* Thread_queue_Priority_actions_operation) (Thread_queue_Queue *queue, Priority_Actions *priority_actions)

Thread queue action operation.

Parameters

[in]	queue	The actual thread queue.
[in]	the_thread	The thread.
[in]	queue_context	The thread queue context providing the thread queue action set to perform. Returns the thread queue action set to perform on the thread queue owner or the empty set in case there is nothing to do.

Thread_queue_Surrender_operation

typedef Thread_Control *(* Thread_queue_Surrender_operation) (Thread_queue_Queue *queue, Thread_queue_Heads *heads, Thread_Control *previous_owner, Thread_queue_Context *queue_context)

Thread queue surrender operation.

This operation must dequeue and return the first thread on the queue.

Parameters

[in]	queue	The actual thread queue.
[in]	heads	The thread queue heads. It must not be NULL.
[in]	previous_owner	The previous owner of the thread queue.

Returns

The previous first thread on the queue.

Enumeration Type Documentation

Thread_queue_Deadlock_status

enum Thread_queue_Deadlock_status

This is a status code to indicate if a deadlock was detected or not.

Enumerator
THREAD_QUEUE_NO_DEADLOCK	The operation did not detect a deadlock.
THREAD_QUEUE_DEADLOCK_DETECTED	The operation detected a deadlock.

Function Documentation

_Thread_queue_Add_timeout_monotonic_timespec()

void _Thread_queue_Add_timeout_monotonic_timespec	(	Thread_queue_Queue *	queue,
		Thread_Control *	the_thread,
		Per_CPU_Control *	cpu_self,
		Thread_queue_Context *	queue_context
	)

Adds a monotonic timespec to the thread and sets the watchdog header to monotonic.

Parameters

	queue	This parameter is unused.
[in,out]	the_thread	The thread to add the timeout and set watchdog header to monotonic.
	cpu_self	The cpu to get the monotonic watchdog header from.
	queue_context	The thread queue context.

_Thread_queue_Add_timeout_realtime_timespec()

void _Thread_queue_Add_timeout_realtime_timespec	(	Thread_queue_Queue *	queue,
		Thread_Control *	the_thread,
		Per_CPU_Control *	cpu_self,
		Thread_queue_Context *	queue_context
	)

Adds a monotonic timespec to the thread and sets the watchdog header to realtime.

Parameters

	queue	This parameter is unused.
[in,out]	the_thread	The thread to add the timeout and set watchdog header to realtime.
	cpu_self	The cpu to get the realtime watchdog header from.
	queue_context	The thread queue context.

_Thread_queue_Add_timeout_ticks()

void _Thread_queue_Add_timeout_ticks	(	Thread_queue_Queue *	queue,
		Thread_Control *	the_thread,
		Per_CPU_Control *	cpu_self,
		Thread_queue_Context *	queue_context
	)

Adds timeout ticks of the queue to the thread.

Parameters

	queue	This parameter is unused.
[in,out]	the_thread	The thread to add timeout ticks to.
	cpu_self	The cpu for the operation.
	queue_context	The thread queue context.

_Thread_queue_Deadlock_fatal()

void _Thread_queue_Deadlock_fatal

(

Thread_Control *

the_thread

)

Results in an INTERNAL_ERROR_THREAD_QUEUE_DEADLOCK fatal error.

Parameters

the_thread

The thread for the operation.

_Thread_queue_Deadlock_status()

void _Thread_queue_Deadlock_status

(

Thread_Control *

the_thread

)

Sets the thread wait return code to STATUS_DEADLOCK.

Parameters

[out]

the_thread

The thread to set the wait return code to STATUS_DEADLOCK.

_Thread_queue_Do_nothing_priority_actions()

void _Thread_queue_Do_nothing_priority_actions	(	Thread_queue_Queue *	queue,
		Priority_Actions *	priority_actions
	)

Initializes the priority actions so that no actions are performed.

Parameters

	queue	is unused.
[out]	priority_actions	is initialized so that no actions are performed.

_Thread_queue_Enqueue()

void _Thread_queue_Enqueue	(	Thread_queue_Queue *	queue,
		const Thread_queue_Operations *	operations,
		Thread_Control *	the_thread,
		Thread_queue_Context *	queue_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 discipline is not WATCHDOG_NO_TIMEOUT. Timeout discipline and value are in the queue_context.

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() in case the thread must block.

The thread queue context must be set up with the following functions, otherwise the behaviour is unpredictable

• _Thread_queue_Context_set_thread_state(),
• _Thread_queue_Context_set_enqueue_callout() or _Thread_queue_Context_set_enqueue_do_nothing_extra() or _Thread_queue_Context_set_enqueue_timeout_ticks() or _Thread_queue_Context_set_enqueue_timeout_monotonic_timespec() or _Thread_queue_Context_set_enqueue_timeout_realtime_timespec(),
• _Thread_queue_Context_set_deadlock_callout().

#include <rtems/score/threadqimpl.h>
#include <rtems/score/statesimpl.h>
 
#define MUTEX_TQ_OPERATIONS &_Thread_queue_Operations_priority
 
typedef struct {
  Thread_queue_Control Queue;
} Mutex;
 
void _Mutex_Obtain( Mutex *mutex )
{
  Thread_queue_Context  queue_context;
  Thread_Control       *executing;
 
  _Thread_queue_Context_initialize( &queue_context );
  _Thread_queue_Acquire( &mutex->Queue, queue_context );
 
  executing = _Thread_Executing;
 
  if ( mutex->Queue.owner == NULL ) {
    mutex->Queue.owner = executing;
    _Thread_queue_Release( &mutex->Queue, queue_context );
  } else {
    _Thread_queue_Context_set_thread_state(
      &queue_context,
      STATES_WAITING_FOR_MUTEX
    );
    _Thread_queue_Context_set_enqueue_do_nothing_extra( &queue_context );
    _Thread_queue_Context_set_deadlock_callout(
      queue_context,
      _Thread_queue_Deadlock_fatal
    );
    _Thread_queue_Enqueue(
      &mutex->Queue.Queue,
      MUTEX_TQ_OPERATIONS,
      executing,
      &queue_context
    );
  }
}

Parameters

	queue	The actual thread queue.
	operations	The thread queue operations.
[in,out]	the_thread	The thread to enqueue.
[in,out]	queue_context	The thread queue context of the lock acquire.

_Thread_queue_Enqueue_do_nothing_extra()

void _Thread_queue_Enqueue_do_nothing_extra	(	Thread_queue_Queue *	queue,
		Thread_Control *	the_thread,
		Per_CPU_Control *	cpu_self,
		Thread_queue_Context *	queue_context
	)

Does nothing.

Parameters

queue	This parameter is unused.
the_thread	This parameter is unused.
cpu_self	This parameter is unused.
queue_context	This parameter is unused.

_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,out]

the_thread

The pointer to a thread control block that is to be removed

_Thread_queue_Extract_locked()

bool _Thread_queue_Extract_locked	(	Thread_queue_Queue *	queue,
		const Thread_queue_Operations *	operations,
		Thread_Control *	the_thread,
		Thread_queue_Context *	queue_context
	)

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

	queue	The actual thread queue.
	operations	The thread queue operations.
[in,out]	the_thread	The thread to extract.
[in,out]	queue_context	The thread queue context.

Returns

Returns the unblock indicator. True indicates, that this thread must be unblocked by the scheduler using _Thread_Remove_timer_and_unblock(), and false otherwise. In case false is returned, then the thread queue enqueue procedure was interrupted. Thus it will unblock itself and the thread wait information is no longer accessible, since this thread may already block on another resource in an SMP configuration.

_Thread_queue_FIFO_enqueue()

void _Thread_queue_FIFO_enqueue	(	Thread_queue_Queue *	queue,
		Thread_Control *	the_thread,
		Thread_queue_Context *	queue_context
	)

Enqueues the thread to the FIFO thread queue.

Parameters

[in,out]	queue	is the thread queue.
[in,out]	the_thread	is the thread to enqueue.
[in,out]	queue_context	is the thread queue context.

_Thread_queue_FIFO_extract()

void _Thread_queue_FIFO_extract	(	Thread_queue_Queue *	queue,
		Thread_Control *	the_thread,
		Thread_queue_Context *	queue_context
	)

Extracts the thread from the FIFO thread queue.

Parameters

[in,out]	queue	is the thread queue.
[in,out]	the_thread	is the thread to extract.
[in,out]	queue_context	is the thread queue context.

_Thread_queue_FIFO_first()

Thread_Control * _Thread_queue_FIFO_first

(

const Thread_queue_Heads *

heads

)

Gets the first thread on the FIFO thread queue.

Parameters

[in,out]	queue	is the thread queue.
[in,out]	the_thread	is the thread to extract.
[in,out]	queue_context	is the thread queue context.

_Thread_queue_FIFO_surrender()

Thread_Control * _Thread_queue_FIFO_surrender	(	Thread_queue_Queue *	queue,
		Thread_queue_Heads *	heads,
		Thread_Control *	previous_owner,
		Thread_queue_Context *	queue_context
	)

Surrenders the thread queue to the first thread on the FIFO thread queue.

Parameters

[in,out]	queue	is the thread queue.
[in,out]	heads	are heads of the thread queue.
	previous_owner	is unused.
[in,out]	queue_context	is the thread queue context.

Returns

Returns the first thread on the thread queue according to the queue order.

_Thread_queue_First()

Thread_Control * _Thread_queue_First	(	Thread_queue_Control *	the_thread_queue,
		const Thread_queue_Operations *	operations
	)

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

Parameters

the_thread_queue

The thread queue.

Return values

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

_Thread_queue_Flush_critical()

size_t _Thread_queue_Flush_critical	(	Thread_queue_Queue *	queue,
		const Thread_queue_Operations *	operations,
		Thread_queue_Flush_filter	filter,
		Thread_queue_Context *	queue_context
	)

Unblocks all threads enqueued on the thread queue.

This function iteratively extracts the first enqueued thread of the thread queue until the thread queue is empty or the filter function indicates a stop. The thread timers of the extracted threads are cancelled. The extracted threads are unblocked.

Parameters

queue	The actual thread queue.
operations	The thread queue operations.
filter	The filter functions is called for each thread to extract from the thread queue. It may be used to alter the thread under protection of the thread queue lock, for example to set the thread wait return code. The return value of the filter function controls if the thread queue flush operation should stop or continue.
queue_context	The thread queue context of the lock acquire. May be used to pass additional data to the filter function via an overlay structure. The filter function should not release or acquire the thread queue lock.

Returns

The count of extracted threads.

_Thread_queue_Flush_default_filter()

Thread_Control * _Thread_queue_Flush_default_filter	(	Thread_Control *	the_thread,
		Thread_queue_Queue *	queue,
		Thread_queue_Context *	queue_context
	)

Default thread queue flush filter function.

Parameters

the_thread	The thread to extract.
queue	This parameter is unused.
queue_context	This parameter is unused.

Return values

the_thread

Extract this thread.

_Thread_queue_Flush_status_object_was_deleted()

Thread_Control * _Thread_queue_Flush_status_object_was_deleted	(	Thread_Control *	the_thread,
		Thread_queue_Queue *	queue,
		Thread_queue_Context *	queue_context
	)

Status object was deleted thread queue flush filter function.

Sets the thread wait return code of the thread to STATUS_OBJECT_WAS_DELETED

Parameters

[out]	the_thread	The thread to extract.
	queue	This parameter is unused.
	queue_context	This parameter is unused.

Return values

the_thread

Extract this thread.

_Thread_queue_Flush_status_unavailable()

Thread_Control * _Thread_queue_Flush_status_unavailable	(	Thread_Control *	the_thread,
		Thread_queue_Queue *	queue,
		Thread_queue_Context *	queue_context
	)

Status unavailable thread queue flush filter function.

Sets the thread wait return code of the thread to STATUS_UNAVAILABLE.

Parameters

[out]	the_thread	The thread to extract.
	queue	This parameter is unused.
	queue_context	This parameter is unused.

Return values

the_thread

Extract this thread.

_Thread_queue_Initialize()

void _Thread_queue_Initialize	(	Thread_queue_Control *	the_thread_queue,
		const char *	name
	)

Initializes the thread queue control to the given name.

Parameters

[out]	the_thread_queue	The thread queue control to initialize.
	name	The name for the_thread_queue.

_Thread_queue_Object_initialize()

void _Thread_queue_Object_initialize

(

Thread_queue_Control *

the_thread_queue

)

Initializes a thread queue embedded in an object with identifier.

The object must have the layout specified by Thread_queue_Object. It should be ensured with the THREAD_QUEUE_OBJECT_ASSERT() static assertion.

Parameters

[out]

the_thread_queue

The thread queue.

_Thread_queue_Queue_get_name_and_id()

size_t _Thread_queue_Queue_get_name_and_id	(	const Thread_queue_Queue *	queue,
		char *	buffer,
		size_t	buffer_size,
		Objects_Id *	id
	)

Copies the thread queue name to the specified buffer.

Parameters

	queue	The actual thread queue.
[out]	buffer	The buffer for the thread queue name copy.
	buffer_size	The buffer size in characters.
	id	The object identifier in case the thread queue is embedded in an object with identifier, otherwise it is set to 0.

Returns

The length of the thread queue name. May be greater than or equal to the buffer size if truncation occurred.

_Thread_queue_Resume()

void _Thread_queue_Resume	(	Thread_queue_Queue *	queue,
		Thread_Control *	the_thread,
		Thread_queue_Context *	queue_context
	)

Resumes the extracted or surrendered thread.

This function makes the thread ready again. If necessary, the thread is unblocked and its thread timer removed.

The thread shall have been extracted from the thread queue or surrendered by the thread queue right before the call to this function. The caller shall be the owner of the thread queue lock.

Parameters

	queue	is the actual thread queue.
[in,out]	the_thread	is the thread to make ready and unblock.
[in,out]	queue_context	is the thread queue context.

_Thread_queue_Surrender()

void _Thread_queue_Surrender	(	Thread_queue_Queue *	queue,
		Thread_queue_Heads *	heads,
		Thread_Control *	previous_owner,
		Thread_queue_Context *	queue_context,
		const Thread_queue_Operations *	operations
	)

Surrenders the thread queue previously owned by the thread to the first enqueued thread.

The owner of the thread queue must be set to NULL by the caller.

This function releases the thread queue lock. In addition it performs a thread dispatch if necessary.

Parameters

[in,out]	queue	The actual thread queue.
	heads	The thread queue heads. It must not be NULL.
	previous_owner	The previous owner thread surrendering the thread queue.
	queue_context	The thread queue context of the lock acquire.
	operations	The thread queue operations.

_Thread_queue_Surrender_no_priority()

void _Thread_queue_Surrender_no_priority	(	Thread_queue_Queue *	queue,
		Thread_queue_Heads *	heads,
		Thread_queue_Context *	queue_context,
		const Thread_queue_Operations *	operations
	)

Surrenders the thread queue previously owned by the thread to the first enqueued thread.

The owner of the thread queue must be set to NULL by the caller.

This function releases the thread queue lock. In addition it performs a thread dispatch if necessary.

Parameters

[in,out]	queue	The actual thread queue.
	heads	The thread queue heads. It must not be NULL.
	queue_context	The thread queue context of the lock acquire.
	operations	The thread queue operations.

_Thread_queue_Surrender_priority_ceiling()

Status_Control _Thread_queue_Surrender_priority_ceiling	(	Thread_queue_Queue *	queue,
		Thread_Control *	executing,
		Priority_Node *	ceiling_priority,
		Thread_queue_Context *	queue_context,
		const Thread_queue_Operations *	operations
	)

Surrenders the thread queue previously owned by the thread to the first enqueued thread.

The owner of the thread queue must be set to NULL by the caller.

This function releases the thread queue lock. In addition it performs a thread dispatch if necessary.

Parameters

[in,out]	queue	The actual thread queue.
	heads	The thread queue heads. It must not be NULL.
	queue_context	The thread queue context of the lock acquire.
	operations	The thread queue operations.

Variable Documentation

_Thread_queue_Object_name

const char _Thread_queue_Object_name[]

extern

The special thread queue name to indicated that the thread queue is embedded in an object with identifier.

See also

_Thread_queue_Object_initialize().

_Thread_queue_Operations_default

const Thread_queue_Operations _Thread_queue_Operations_default

extern

The default thread queue operations are used when a thread is not enqueued on a thread queue.

The default operations may be used by _Thread_Priority_apply() and _Thread_Continue() if the thread is not enqueued on a thread queue. The default operations do nothing.