diff options
Diffstat (limited to 'cpukit/include/rtems/score/threadq.h')
-rw-r--r-- | cpukit/include/rtems/score/threadq.h | 83 |
1 files changed, 70 insertions, 13 deletions
diff --git a/cpukit/include/rtems/score/threadq.h b/cpukit/include/rtems/score/threadq.h index 5234019b81..20633d4341 100644 --- a/cpukit/include/rtems/score/threadq.h +++ b/cpukit/include/rtems/score/threadq.h @@ -1,3 +1,5 @@ +/* SPDX-License-Identifier: BSD-2-Clause */ + /** * @file * @@ -12,9 +14,26 @@ * COPYRIGHT (c) 1989-2014. * On-Line Applications Research Corporation (OAR). * - * The license and distribution terms for this file may be - * found in the file LICENSE in this distribution or at - * http://www.rtems.org/license/LICENSE. + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in the + * documentation and/or other materials provided with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" + * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE + * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE + * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE + * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR + * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF + * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS + * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN + * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE + * POSSIBILITY OF SUCH DAMAGE. */ #ifndef _RTEMS_SCORE_THREADQ_H @@ -214,7 +233,8 @@ struct Thread_queue_Context { * callout must be used to install the thread watchdog for timeout handling. * * @see _Thread_queue_Enqueue_do_nothing_extra(). - * _Thread_queue_Add_timeout_ticks(), and + * _Thread_queue_Add_timeout_ticks(), + * _Thread_queue_Add_timeout_monotonic_timespec(), and * _Thread_queue_Add_timeout_realtime_timespec(). */ Thread_queue_Enqueue_callout enqueue_callout; @@ -236,6 +256,12 @@ struct Thread_queue_Context { const void *arg; } Timeout; + /** + * @brief If this member is true, the timeout shall be absolute, otherwise it + * shall be relative to the current time of the clock. + */ + bool timeout_absolute; + #if defined(RTEMS_SMP) /** * @brief Representation of a thread queue path from a start thread queue to @@ -399,6 +425,7 @@ typedef struct _Thread_queue_Heads { } Thread_queue_Heads; struct Thread_queue_Queue { +#if defined(RTEMS_SMP) /** * @brief Lock to protect this thread queue. * @@ -411,7 +438,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 @@ -510,37 +536,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; }; |