[PATCH v2] score: Document thread queue operations

[Chris Johns]

Looks good. Thanks.

Chris

On 2/9/21 5:13 pm, Sebastian Huber wrote:
> ---
>  cpukit/include/rtems/score/threadq.h     | 48 +++++++++++++++++++-----
>  cpukit/include/rtems/score/threadqimpl.h | 21 +++++++++++
>  cpukit/score/src/threadqops.c            |  4 +-
>  3 files changed, 62 insertions(+), 11 deletions(-)
> 
> diff --git a/cpukit/include/rtems/score/threadq.h b/cpukit/include/rtems/score/threadq.h
> index 10476888d4..9d1ad84e81 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,67 @@ 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 for the surrender operation and not for 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..6acbce1b42 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 don't have a thread queue associated with them, so
>     * the enqueue and first operations are superfluous.
>     */
>  };
>