[20f02c6] | 1 | /** |
---|
[a112364] | 2 | * @file |
---|
[ac7d5ef0] | 3 | * |
---|
[a112364] | 4 | * @brief Constants and Structures Needed to Declare a Thread Queue |
---|
[319cb20] | 5 | * |
---|
[a112364] | 6 | * This include file contains all the constants and structures |
---|
| 7 | * needed to declare a thread queue. |
---|
[baff4da] | 8 | */ |
---|
| 9 | |
---|
| 10 | /* |
---|
[ed7a028] | 11 | * COPYRIGHT (c) 1989-2014. |
---|
[ac7d5ef0] | 12 | * On-Line Applications Research Corporation (OAR). |
---|
| 13 | * |
---|
[98e4ebf5] | 14 | * The license and distribution terms for this file may be |
---|
| 15 | * found in the file LICENSE in this distribution or at |
---|
[c499856] | 16 | * http://www.rtems.org/license/LICENSE. |
---|
[ac7d5ef0] | 17 | */ |
---|
| 18 | |
---|
[092f142a] | 19 | #ifndef _RTEMS_SCORE_THREADQ_H |
---|
| 20 | #define _RTEMS_SCORE_THREADQ_H |
---|
[ac7d5ef0] | 21 | |
---|
[a112364] | 22 | #include <rtems/score/chain.h> |
---|
[02c4c441] | 23 | #include <rtems/score/isrlock.h> |
---|
[568af83] | 24 | #include <rtems/score/priority.h> |
---|
| 25 | #include <rtems/score/rbtree.h> |
---|
[5e9b32b] | 26 | |
---|
[b02f920f] | 27 | #ifdef __cplusplus |
---|
| 28 | extern "C" { |
---|
| 29 | #endif |
---|
| 30 | |
---|
[8d0bf322] | 31 | /** |
---|
[a112364] | 32 | * @defgroup ScoreThreadQueue Thread Queue Handler |
---|
[8d0bf322] | 33 | * |
---|
| 34 | * @ingroup Score |
---|
| 35 | * |
---|
[3250664] | 36 | * This handler provides the capability to have threads block in |
---|
| 37 | * ordered sets. The sets may be ordered using the FIFO or priority |
---|
| 38 | * discipline. |
---|
[8d0bf322] | 39 | */ |
---|
| 40 | /**@{*/ |
---|
| 41 | |
---|
[4827470] | 42 | typedef struct _Thread_Control Thread_Control; |
---|
[bd67d7d2] | 43 | |
---|
[3995e6d] | 44 | /** |
---|
| 45 | * @brief Thread priority queue. |
---|
| 46 | */ |
---|
| 47 | typedef struct { |
---|
| 48 | #if defined(RTEMS_SMP) |
---|
| 49 | /** |
---|
| 50 | * @brief Node to enqueue this queue in the FIFO chain of the corresponding |
---|
| 51 | * heads structure. |
---|
| 52 | * |
---|
| 53 | * @see Thread_queue_Heads::Heads::Fifo. |
---|
| 54 | */ |
---|
| 55 | Chain_Node Node; |
---|
| 56 | #endif |
---|
| 57 | |
---|
| 58 | /** |
---|
| 59 | * @brief The actual thread priority queue. |
---|
| 60 | */ |
---|
| 61 | RBTree_Control Queue; |
---|
| 62 | } Thread_queue_Priority_queue; |
---|
| 63 | |
---|
[e421936b] | 64 | /** |
---|
| 65 | * @brief Thread queue heads. |
---|
| 66 | * |
---|
[c4db18a0] | 67 | * Each thread is equipped with spare thread queue heads in case it is not |
---|
| 68 | * enqueued on a thread queue. The first thread enqueued on a thread queue |
---|
| 69 | * will give its spare thread queue heads to that thread queue. The threads |
---|
| 70 | * arriving at the queue will add their thread queue heads to the free chain of |
---|
| 71 | * the queue heads provided by the first thread enqueued. Once a thread is |
---|
| 72 | * dequeued it use the free chain to get new spare thread queue heads. |
---|
| 73 | * |
---|
[e421936b] | 74 | * Uses a leading underscore in the structure name to allow forward |
---|
| 75 | * declarations in standard header files provided by Newlib and GCC. |
---|
| 76 | */ |
---|
| 77 | typedef struct _Thread_queue_Heads { |
---|
[e2735012] | 78 | /** This union contains the data structures used to manage the blocked |
---|
| 79 | * set of tasks which varies based upon the discipline. |
---|
| 80 | */ |
---|
| 81 | union { |
---|
[c4db18a0] | 82 | /** |
---|
| 83 | * @brief This is the FIFO discipline list. |
---|
[3995e6d] | 84 | * |
---|
| 85 | * On SMP configurations this FIFO is used to enqueue the per scheduler |
---|
| 86 | * instance priority queues of this structure. This ensures FIFO fairness |
---|
| 87 | * among the highest priority thread of each scheduler instance. |
---|
[c4db18a0] | 88 | */ |
---|
[e2735012] | 89 | Chain_Control Fifo; |
---|
[c4db18a0] | 90 | |
---|
[3995e6d] | 91 | #if !defined(RTEMS_SMP) |
---|
[c4db18a0] | 92 | /** |
---|
| 93 | * @brief This is the set of threads for priority discipline waiting. |
---|
| 94 | */ |
---|
[3995e6d] | 95 | Thread_queue_Priority_queue Priority; |
---|
| 96 | #endif |
---|
[e2735012] | 97 | } Heads; |
---|
| 98 | |
---|
[c4db18a0] | 99 | /** |
---|
| 100 | * @brief A chain with free thread queue heads providing the spare thread |
---|
| 101 | * queue heads for a thread once it is dequeued. |
---|
| 102 | */ |
---|
[d7665823] | 103 | Chain_Control Free_chain; |
---|
| 104 | |
---|
[c4db18a0] | 105 | /** |
---|
| 106 | * @brief A chain node to add these thread queue heads to the free chain of |
---|
| 107 | * the thread queue heads dedicated to the thread queue of an object. |
---|
| 108 | */ |
---|
[d7665823] | 109 | Chain_Node Free_node; |
---|
[3995e6d] | 110 | |
---|
| 111 | #if defined(RTEMS_SMP) |
---|
| 112 | /** |
---|
| 113 | * @brief One priority queue per scheduler instance. |
---|
| 114 | */ |
---|
| 115 | Thread_queue_Priority_queue Priority[ RTEMS_ZERO_LENGTH_ARRAY ]; |
---|
| 116 | #endif |
---|
[d7665823] | 117 | } Thread_queue_Heads; |
---|
| 118 | |
---|
[3995e6d] | 119 | #if defined(RTEMS_SMP) |
---|
| 120 | #define THREAD_QUEUE_HEADS_SIZE( scheduler_count ) \ |
---|
| 121 | ( sizeof( Thread_queue_Heads ) \ |
---|
| 122 | + ( scheduler_count ) * sizeof( Thread_queue_Priority_queue ) ) |
---|
| 123 | #else |
---|
| 124 | #define THREAD_QUEUE_HEADS_SIZE( scheduler_count ) \ |
---|
| 125 | sizeof( Thread_queue_Heads ) |
---|
| 126 | #endif |
---|
| 127 | |
---|
[d7665823] | 128 | typedef struct { |
---|
[c4db18a0] | 129 | /** |
---|
| 130 | * @brief The thread queue heads. |
---|
| 131 | * |
---|
| 132 | * This pointer is NULL, if and only if no threads are enqueued. The first |
---|
| 133 | * thread to enqueue will give its spare thread queue heads to this thread |
---|
| 134 | * queue. |
---|
| 135 | */ |
---|
[d7665823] | 136 | Thread_queue_Heads *heads; |
---|
| 137 | |
---|
[e2735012] | 138 | /** |
---|
| 139 | * @brief Lock to protect this thread queue. |
---|
| 140 | * |
---|
| 141 | * It may be used to protect additional state of the object embedding this |
---|
| 142 | * thread queue. |
---|
| 143 | * |
---|
| 144 | * @see _Thread_queue_Acquire(), _Thread_queue_Acquire_critical() and |
---|
| 145 | * _Thread_queue_Release(). |
---|
| 146 | */ |
---|
[0e3c59d6] | 147 | #if defined(RTEMS_SMP) |
---|
| 148 | SMP_ticket_lock_Control Lock; |
---|
| 149 | #endif |
---|
[e2735012] | 150 | } Thread_queue_Queue; |
---|
[568af83] | 151 | |
---|
| 152 | /** |
---|
| 153 | * @brief Thread queue priority change operation. |
---|
| 154 | * |
---|
| 155 | * @param[in] the_thread The thread. |
---|
| 156 | * @param[in] new_priority The new priority value. |
---|
[e2735012] | 157 | * @param[in] queue The actual thread queue. |
---|
[568af83] | 158 | * |
---|
| 159 | * @see Thread_queue_Operations. |
---|
| 160 | */ |
---|
| 161 | typedef void ( *Thread_queue_Priority_change_operation )( |
---|
[e2735012] | 162 | Thread_Control *the_thread, |
---|
| 163 | Priority_Control new_priority, |
---|
| 164 | Thread_queue_Queue *queue |
---|
[383cf42] | 165 | ); |
---|
| 166 | |
---|
| 167 | /** |
---|
| 168 | * @brief Thread queue enqueue operation. |
---|
| 169 | * |
---|
[e2735012] | 170 | * @param[in] queue The actual thread queue. |
---|
[383cf42] | 171 | * @param[in] the_thread The thread to enqueue on the queue. |
---|
| 172 | * |
---|
| 173 | * @see _Thread_Wait_set_operations(). |
---|
| 174 | */ |
---|
| 175 | typedef void ( *Thread_queue_Enqueue_operation )( |
---|
[e2735012] | 176 | Thread_queue_Queue *queue, |
---|
| 177 | Thread_Control *the_thread |
---|
[383cf42] | 178 | ); |
---|
| 179 | |
---|
| 180 | /** |
---|
| 181 | * @brief Thread queue extract operation. |
---|
| 182 | * |
---|
[e2735012] | 183 | * @param[in] queue The actual thread queue. |
---|
[383cf42] | 184 | * @param[in] the_thread The thread to extract from the thread queue. |
---|
| 185 | * |
---|
| 186 | * @see _Thread_Wait_set_operations(). |
---|
| 187 | */ |
---|
| 188 | typedef void ( *Thread_queue_Extract_operation )( |
---|
[e2735012] | 189 | Thread_queue_Queue *queue, |
---|
| 190 | Thread_Control *the_thread |
---|
[383cf42] | 191 | ); |
---|
| 192 | |
---|
| 193 | /** |
---|
| 194 | * @brief Thread queue first operation. |
---|
| 195 | * |
---|
[d7665823] | 196 | * @param[in] heads The thread queue heads. |
---|
[383cf42] | 197 | * |
---|
| 198 | * @retval NULL No thread is present on the thread queue. |
---|
| 199 | * @retval first The first thread of the thread queue according to the insert |
---|
| 200 | * order. This thread remains on the thread queue. |
---|
| 201 | * |
---|
| 202 | * @see _Thread_Wait_set_operations(). |
---|
| 203 | */ |
---|
| 204 | typedef Thread_Control *( *Thread_queue_First_operation )( |
---|
[d7665823] | 205 | Thread_queue_Heads *heads |
---|
[568af83] | 206 | ); |
---|
| 207 | |
---|
| 208 | /** |
---|
| 209 | * @brief Thread queue operations. |
---|
| 210 | * |
---|
| 211 | * @see _Thread_wait_Set_operations(). |
---|
| 212 | */ |
---|
| 213 | typedef struct { |
---|
| 214 | /** |
---|
| 215 | * @brief Thread queue priority change operation. |
---|
| 216 | * |
---|
| 217 | * Called by _Thread_Change_priority() to notify a thread about a priority |
---|
| 218 | * change. In case this thread waits currently for a resource the handler |
---|
| 219 | * may adjust its data structures according to the new priority value. This |
---|
| 220 | * handler must not be NULL, instead the default handler |
---|
| 221 | * _Thread_Do_nothing_priority_change() should be used in case nothing needs |
---|
| 222 | * to be done during a priority change. |
---|
| 223 | */ |
---|
| 224 | Thread_queue_Priority_change_operation priority_change; |
---|
[383cf42] | 225 | |
---|
| 226 | /** |
---|
| 227 | * @brief Thread queue enqueue operation. |
---|
| 228 | * |
---|
| 229 | * Called by object routines to enqueue the thread. |
---|
| 230 | */ |
---|
| 231 | Thread_queue_Enqueue_operation enqueue; |
---|
| 232 | |
---|
| 233 | /** |
---|
| 234 | * @brief Thread queue extract operation. |
---|
| 235 | * |
---|
| 236 | * Called by object routines to extract a thread from a thread queue. |
---|
| 237 | */ |
---|
| 238 | Thread_queue_Extract_operation extract; |
---|
| 239 | |
---|
| 240 | /** |
---|
| 241 | * @brief Thread queue first operation. |
---|
| 242 | */ |
---|
| 243 | Thread_queue_First_operation first; |
---|
[568af83] | 244 | } Thread_queue_Operations; |
---|
| 245 | |
---|
[baff4da] | 246 | /** |
---|
[a112364] | 247 | * The following enumerated type details all of the disciplines |
---|
| 248 | * supported by the Thread Queue Handler. |
---|
| 249 | */ |
---|
| 250 | typedef enum { |
---|
| 251 | THREAD_QUEUE_DISCIPLINE_FIFO, /* FIFO queue discipline */ |
---|
| 252 | THREAD_QUEUE_DISCIPLINE_PRIORITY /* PRIORITY queue discipline */ |
---|
| 253 | } Thread_queue_Disciplines; |
---|
| 254 | |
---|
| 255 | /** |
---|
| 256 | * This is the structure used to manage sets of tasks which are blocked |
---|
| 257 | * waiting to acquire a resource. |
---|
| 258 | */ |
---|
[e2735012] | 259 | typedef struct { |
---|
[568af83] | 260 | /** |
---|
[e2735012] | 261 | * @brief The actual thread queue. |
---|
[568af83] | 262 | */ |
---|
[e2735012] | 263 | Thread_queue_Queue Queue; |
---|
[568af83] | 264 | |
---|
[0e3c59d6] | 265 | #if defined(RTEMS_SMP) && defined(RTEMS_PROFILING) |
---|
| 266 | SMP_lock_Stats Lock_stats; |
---|
| 267 | #endif |
---|
| 268 | |
---|
[02c4c441] | 269 | /** |
---|
[e2735012] | 270 | * @brief The operations for the actual thread queue. |
---|
[02c4c441] | 271 | */ |
---|
[e2735012] | 272 | const Thread_queue_Operations *operations; |
---|
| 273 | } Thread_queue_Control; |
---|
[047d67a] | 274 | |
---|
[8d0bf322] | 275 | /**@}*/ |
---|
[047d67a] | 276 | |
---|
[ac7d5ef0] | 277 | #ifdef __cplusplus |
---|
| 278 | } |
---|
| 279 | #endif |
---|
| 280 | |
---|
| 281 | #endif |
---|
[b10825c] | 282 | /* end of include file */ |
---|