[rtems commit] score: Document thread queue operations

[Sebastian Huber]

Module:    rtems
Branch:    master
Commit:    2647e76e8fb6b36e12f699eab4e53a420b2ed0c4
Changeset: http://git.rtems.org/rtems/commit/?id=2647e76e8fb6b36e12f699eab4e53a420b2ed0c4

Author:    Sebastian Huber <sebastian.huber at embedded-brains.de>
Date:      Thu Sep  2 07:48:55 2021 +0200

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(-)

diff --git a/cpukit/include/rtems/score/threadq.h b/cpukit/include/rtems/score/threadq.h
index 1047688..2fbfcd0 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 33cdb30..22e0c7f 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 eb01002..a42876c 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.
    */
 };