source: rtems/cpukit/score/include/rtems/score/threadq.h @ 3995e6d

Last change on this file since 3995e6d was 3995e6d, checked in by Sebastian Huber <sebastian.huber@…>, on Sep 2, 2015 at 9:58:54 AM

score: Implement SMP-specific priority queue

  • Property mode set to 100644
File size: 7.3 KB
Line 
1/**
2 *  @file
3 *
4 *  @brief Constants and Structures Needed to Declare a Thread Queue
5 *
6 *  This include file contains all the constants and structures
7 *  needed to declare a thread queue.
8 */
9
10/*
11 *  COPYRIGHT (c) 1989-2014.
12 *  On-Line Applications Research Corporation (OAR).
13 *
14 *  The license and distribution terms for this file may be
15 *  found in the file LICENSE in this distribution or at
16 *  http://www.rtems.org/license/LICENSE.
17 */
18
19#ifndef _RTEMS_SCORE_THREADQ_H
20#define _RTEMS_SCORE_THREADQ_H
21
22#include <rtems/score/chain.h>
23#include <rtems/score/isrlock.h>
24#include <rtems/score/priority.h>
25#include <rtems/score/rbtree.h>
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31/**
32 *  @defgroup ScoreThreadQueue Thread Queue Handler
33 *
34 *  @ingroup Score
35 *
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.
39 */
40/**@{*/
41
42typedef struct _Thread_Control Thread_Control;
43
44/**
45 * @brief Thread priority queue.
46 */
47typedef 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
64/**
65 * @brief Thread queue heads.
66 *
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 *
74 * Uses a leading underscore in the structure name to allow forward
75 * declarations in standard header files provided by Newlib and GCC.
76 */
77typedef struct _Thread_queue_Heads {
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 {
82    /**
83     * @brief This is the FIFO discipline list.
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.
88     */
89    Chain_Control Fifo;
90
91#if !defined(RTEMS_SMP)
92    /**
93     * @brief This is the set of threads for priority discipline waiting.
94     */
95    Thread_queue_Priority_queue Priority;
96#endif
97  } Heads;
98
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   */
103  Chain_Control Free_chain;
104
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   */
109  Chain_Node Free_node;
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
117} Thread_queue_Heads;
118
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
128typedef struct {
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   */
136  Thread_queue_Heads *heads;
137
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   */
147#if defined(RTEMS_SMP)
148  SMP_ticket_lock_Control Lock;
149#endif
150} Thread_queue_Queue;
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.
157 * @param[in] queue The actual thread queue.
158 *
159 * @see Thread_queue_Operations.
160 */
161typedef void ( *Thread_queue_Priority_change_operation )(
162  Thread_Control     *the_thread,
163  Priority_Control    new_priority,
164  Thread_queue_Queue *queue
165);
166
167/**
168 * @brief Thread queue enqueue operation.
169 *
170 * @param[in] queue The actual thread queue.
171 * @param[in] the_thread The thread to enqueue on the queue.
172 *
173 * @see _Thread_Wait_set_operations().
174 */
175typedef void ( *Thread_queue_Enqueue_operation )(
176  Thread_queue_Queue *queue,
177  Thread_Control     *the_thread
178);
179
180/**
181 * @brief Thread queue extract operation.
182 *
183 * @param[in] queue The actual thread queue.
184 * @param[in] the_thread The thread to extract from the thread queue.
185 *
186 * @see _Thread_Wait_set_operations().
187 */
188typedef void ( *Thread_queue_Extract_operation )(
189  Thread_queue_Queue *queue,
190  Thread_Control     *the_thread
191);
192
193/**
194 * @brief Thread queue first operation.
195 *
196 * @param[in] heads The thread queue heads.
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 */
204typedef Thread_Control *( *Thread_queue_First_operation )(
205  Thread_queue_Heads *heads
206);
207
208/**
209 * @brief Thread queue operations.
210 *
211 * @see _Thread_wait_Set_operations().
212 */
213typedef 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;
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;
244} Thread_queue_Operations;
245
246/**
247 *  The following enumerated type details all of the disciplines
248 *  supported by the Thread Queue Handler.
249 */
250typedef 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 */
259typedef struct {
260  /**
261   * @brief The actual thread queue.
262   */
263  Thread_queue_Queue Queue;
264
265#if defined(RTEMS_SMP) && defined(RTEMS_PROFILING)
266  SMP_lock_Stats Lock_stats;
267#endif
268
269  /**
270   * @brief The operations for the actual thread queue.
271   */
272  const Thread_queue_Operations *operations;
273} Thread_queue_Control;
274
275/**@}*/
276
277#ifdef __cplusplus
278}
279#endif
280
281#endif
282/* end of include file */
Note: See TracBrowser for help on using the repository browser.