summaryrefslogtreecommitdiffstats
path: root/cpukit/include/rtems/score/threadq.h
diff options
context:
space:
mode:
Diffstat (limited to 'cpukit/include/rtems/score/threadq.h')
-rw-r--r--cpukit/include/rtems/score/threadq.h83
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;
};