From 2647e76e8fb6b36e12f699eab4e53a420b2ed0c4 Mon Sep 17 00:00:00 2001 From: Sebastian Huber Date: Thu, 2 Sep 2021 07:48:55 +0200 Subject: score: Document thread queue operations --- cpukit/include/rtems/score/threadq.h | 49 ++++++++++++++++++++++++++------ cpukit/include/rtems/score/threadqimpl.h | 21 ++++++++++++++ cpukit/score/src/threadqops.c | 4 +-- 3 files changed, 63 insertions(+), 11 deletions(-) (limited to 'cpukit') diff --git a/cpukit/include/rtems/score/threadq.h b/cpukit/include/rtems/score/threadq.h index 10476888d4..2fbfcd0199 100644 --- a/cpukit/include/rtems/score/threadq.h +++ b/cpukit/include/rtems/score/threadq.h @@ -406,6 +406,7 @@ typedef struct _Thread_queue_Heads { } Thread_queue_Heads; struct Thread_queue_Queue { +#if defined(RTEMS_SMP) /** * @brief Lock to protect this thread queue. * @@ -418,7 +419,6 @@ struct Thread_queue_Queue { * @see _Thread_queue_Acquire(), _Thread_queue_Acquire_critical() and * _Thread_queue_Release(). */ -#if defined(RTEMS_SMP) SMP_ticket_lock_Control Lock; #endif @@ -517,37 +517,68 @@ typedef Thread_Control *( *Thread_queue_First_operation )( ); /** - * @brief Thread queue operations. + * @brief The thread queue operations are used to manage the threads of a + * thread queue. + * + * The standard thread queue operation variants are: + * + * * ::_Thread_queue_Operations_default + * + * * ::_Thread_queue_Operations_FIFO + * + * * ::_Thread_queue_Operations_priority + * + * * ::_Thread_queue_Operations_priority_inherit * * @see _Thread_wait_Set_operations(). */ struct Thread_queue_Operations { /** - * @brief Thread queue priority actions operation. + * @brief This operation performs the thread queue priority actions. + * + * Priority actions are produced and processed during enqueue, extract, and + * surrender operations. */ Thread_queue_Priority_actions_operation priority_actions; /** - * @brief Thread queue enqueue operation. + * @brief This operation is used to enqueue the thread on the thread queue. * - * Called by object routines to enqueue the thread. + * The enqueue order is defined by the operations variant. */ Thread_queue_Enqueue_operation enqueue; /** - * @brief Thread queue extract operation. + * @brief This operation is used to extract the thread from the thread queue. * - * Called by object routines to extract a thread from a thread queue. + * The extract operation is intended for timeouts, thread restarts, and + * thread cancellation. In SMP configurations, the extract operation does + * not ensure FIFO fairness across schedulers for priority queues. The + * surrender operation should be used to dequeue a thread from the thread + * queue under normal conditions (no timeout, no thread restart, and no + * thread cancellation). */ Thread_queue_Extract_operation extract; /** - * @brief Thread queue surrender operation. + * @brief This operation is used to dequeue the thread from the thread queue + * and optionally surrender the thread queue from a previous owner to the + * thread. + * + * In addition to the optional surrender, there is a subtle difference + * between the extract and dequeue of a thread from a thread queue. In SMP + * configurations, FIFO fairness across schedulers for priority queues is + * only ensured by the dequeue done by the surrender operation and not by the + * extract operation. */ Thread_queue_Surrender_operation surrender; /** - * @brief Thread queue first operation. + * @brief This operation returns the first thread on the thread queue. + * + * This operation may be called only when the thread queue contains at least + * one thread. Use ::Thread_queue_Queue::heads to determine if a thread + * queue is empty. */ Thread_queue_First_operation first; }; diff --git a/cpukit/include/rtems/score/threadqimpl.h b/cpukit/include/rtems/score/threadqimpl.h index 33cdb3058d..22e0c7f069 100644 --- a/cpukit/include/rtems/score/threadqimpl.h +++ b/cpukit/include/rtems/score/threadqimpl.h @@ -1396,12 +1396,33 @@ typedef struct { Wait_queue.Queue \ ) +/** + * @brief 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. + */ extern const Thread_queue_Operations _Thread_queue_Operations_default; +/** + * @brief The FIFO thread queue operations are used when a thread is enqueued + * on a thread queue and provide FIFO ordering of enqueued threads. + */ extern const Thread_queue_Operations _Thread_queue_Operations_FIFO; +/** + * @brief The FIFO thread queue operations are used when a thread is enqueued + * on a thread queue and provide priority ordering of enqueued threads. + */ extern const Thread_queue_Operations _Thread_queue_Operations_priority; +/** + * @brief 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. + */ extern const Thread_queue_Operations _Thread_queue_Operations_priority_inherit; /** diff --git a/cpukit/score/src/threadqops.c b/cpukit/score/src/threadqops.c index eb01002679..a42876cf09 100644 --- a/cpukit/score/src/threadqops.c +++ b/cpukit/score/src/threadqops.c @@ -1464,8 +1464,8 @@ const Thread_queue_Operations _Thread_queue_Operations_default = { .priority_actions = _Thread_queue_Do_nothing_priority_actions, .extract = _Thread_queue_Do_nothing_extract /* - * The default operations are only used in _Thread_Change_priority() and - * _Thread_Timeout() and don't have a thread queue associated with them, so + * The default operations are only used in _Thread_Priority_apply() and + * _Thread_Continue() and do not have a thread queue associated with them, so * the enqueue and first operations are superfluous. */ }; -- cgit v1.2.3