source: rtems/cpukit/score/include/rtems/score/threadq.h @ dfcc8bb

Last change on this file since dfcc8bb was dfcc8bb, checked in by Sebastian Huber <sebastian.huber@…>, on May 3, 2016 at 5:43:54 AM

score: Adjust thread queue layout

Adjust thread queue layout according to Newlib. This makes it possible
to use the same implementation for <sys/lock.h> and CORE mutexes in the
future.

  • Property mode set to 100644
File size: 8.7 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/object.h>
25#include <rtems/score/priority.h>
26#include <rtems/score/rbtree.h>
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
32/**
33 *  @defgroup ScoreThreadQueue Thread Queue Handler
34 *
35 *  @ingroup Score
36 *
37 *  This handler provides the capability to have threads block in
38 *  ordered sets. The sets may be ordered using the FIFO or priority
39 *  discipline.
40 */
41/**@{*/
42
43typedef struct _Thread_Control Thread_Control;
44
45#if defined(RTEMS_MULTIPROCESSING)
46/**
47 * @brief Multiprocessing (MP) support callout for thread queue operations.
48 *
49 * @param the_proxy The thread proxy of the thread queue operation.  A thread
50 *   control is actually a thread proxy if and only if
51 *   _Objects_Is_local_id( the_proxy->Object.id ) is false.
52 * @param mp_id Object identifier of the object containing the thread queue.
53 */
54typedef void ( *Thread_queue_MP_callout )(
55  Thread_Control *the_proxy,
56  Objects_Id      mp_id
57);
58#endif
59
60/**
61 * @brief Thread queue context for the thread queue methods.
62 *
63 * @see _Thread_queue_Context_initialize().
64 */
65typedef struct {
66  ISR_lock_Context Lock_context;
67#if defined(RTEMS_MULTIPROCESSING)
68  Thread_queue_MP_callout mp_callout;
69#endif
70} Thread_queue_Context;
71
72/**
73 * @brief Thread priority queue.
74 */
75typedef struct {
76#if defined(RTEMS_SMP)
77  /**
78   * @brief Node to enqueue this queue in the FIFO chain of the corresponding
79   * heads structure.
80   *
81   * @see Thread_queue_Heads::Heads::Fifo.
82   */
83  Chain_Node Node;
84#endif
85
86  /**
87   * @brief The actual thread priority queue.
88   */
89  RBTree_Control Queue;
90} Thread_queue_Priority_queue;
91
92/**
93 * @brief Thread queue heads.
94 *
95 * Each thread is equipped with spare thread queue heads in case it is not
96 * enqueued on a thread queue.  The first thread enqueued on a thread queue
97 * will give its spare thread queue heads to that thread queue.  The threads
98 * arriving at the queue will add their thread queue heads to the free chain of
99 * the queue heads provided by the first thread enqueued.  Once a thread is
100 * dequeued it use the free chain to get new spare thread queue heads.
101 *
102 * Uses a leading underscore in the structure name to allow forward
103 * declarations in standard header files provided by Newlib and GCC.
104 */
105typedef struct _Thread_queue_Heads {
106  /** This union contains the data structures used to manage the blocked
107   *  set of tasks which varies based upon the discipline.
108   */
109  union {
110    /**
111     * @brief This is the FIFO discipline list.
112     *
113     * On SMP configurations this FIFO is used to enqueue the per scheduler
114     * instance priority queues of this structure.  This ensures FIFO fairness
115     * among the highest priority thread of each scheduler instance.
116     */
117    Chain_Control Fifo;
118
119#if !defined(RTEMS_SMP)
120    /**
121     * @brief This is the set of threads for priority discipline waiting.
122     */
123    Thread_queue_Priority_queue Priority;
124#endif
125  } Heads;
126
127  /**
128   * @brief A chain with free thread queue heads providing the spare thread
129   * queue heads for a thread once it is dequeued.
130   */
131  Chain_Control Free_chain;
132
133  /**
134   * @brief A chain node to add these thread queue heads to the free chain of
135   * the thread queue heads dedicated to the thread queue of an object.
136   */
137  Chain_Node Free_node;
138
139#if defined(RTEMS_SMP)
140  /**
141   * @brief One priority queue per scheduler instance.
142   */
143  Thread_queue_Priority_queue Priority[ RTEMS_ZERO_LENGTH_ARRAY ];
144#endif
145} Thread_queue_Heads;
146
147#if defined(RTEMS_SMP)
148  #define THREAD_QUEUE_HEADS_SIZE( scheduler_count ) \
149    ( sizeof( Thread_queue_Heads ) \
150      + ( scheduler_count ) * sizeof( Thread_queue_Priority_queue ) )
151#else
152  #define THREAD_QUEUE_HEADS_SIZE( scheduler_count ) \
153    sizeof( Thread_queue_Heads )
154#endif
155
156typedef struct {
157  /**
158   * @brief Lock to protect this thread queue.
159   *
160   * It may be used to protect additional state of the object embedding this
161   * thread queue.
162   *
163   * Must be the first component of this structure to be able to re-use
164   * implementation parts for structures defined by Newlib <sys/lock.h>.
165   *
166   * @see _Thread_queue_Acquire(), _Thread_queue_Acquire_critical() and
167   * _Thread_queue_Release().
168   */
169#if defined(RTEMS_SMP)
170  SMP_ticket_lock_Control Lock;
171#endif
172
173  /**
174   * @brief The thread queue heads.
175   *
176   * This pointer is NULL, if and only if no threads are enqueued.  The first
177   * thread to enqueue will give its spare thread queue heads to this thread
178   * queue.
179   */
180  Thread_queue_Heads *heads;
181
182  /**
183   * @brief The thread queue owner.
184   */
185  Thread_Control *owner;
186} Thread_queue_Queue;
187
188/**
189 * @brief Thread queue priority change operation.
190 *
191 * @param[in] the_thread The thread.
192 * @param[in] new_priority The new priority value.
193 * @param[in] queue The actual thread queue.
194 *
195 * @see Thread_queue_Operations.
196 */
197typedef void ( *Thread_queue_Priority_change_operation )(
198  Thread_Control     *the_thread,
199  Priority_Control    new_priority,
200  Thread_queue_Queue *queue
201);
202
203/**
204 * @brief Thread queue enqueue operation.
205 *
206 * @param[in] queue The actual thread queue.
207 * @param[in] the_thread The thread to enqueue on the queue.
208 *
209 * @see _Thread_Wait_set_operations().
210 */
211typedef void ( *Thread_queue_Enqueue_operation )(
212  Thread_queue_Queue *queue,
213  Thread_Control     *the_thread
214);
215
216/**
217 * @brief Thread queue extract operation.
218 *
219 * @param[in] queue The actual thread queue.
220 * @param[in] the_thread The thread to extract from the thread queue.
221 *
222 * @see _Thread_Wait_set_operations().
223 */
224typedef void ( *Thread_queue_Extract_operation )(
225  Thread_queue_Queue *queue,
226  Thread_Control     *the_thread
227);
228
229/**
230 * @brief Thread queue first operation.
231 *
232 * @param[in] heads The thread queue heads.
233 *
234 * @retval NULL No thread is present on the thread queue.
235 * @retval first The first thread of the thread queue according to the insert
236 * order.  This thread remains on the thread queue.
237 *
238 * @see _Thread_Wait_set_operations().
239 */
240typedef Thread_Control *( *Thread_queue_First_operation )(
241  Thread_queue_Heads *heads
242);
243
244/**
245 * @brief Thread queue operations.
246 *
247 * @see _Thread_wait_Set_operations().
248 */
249typedef struct {
250  /**
251   * @brief Thread queue priority change operation.
252   *
253   * Called by _Thread_Change_priority() to notify a thread about a priority
254   * change.  In case this thread waits currently for a resource the handler
255   * may adjust its data structures according to the new priority value.  This
256   * handler must not be NULL, instead the default handler
257   * _Thread_Do_nothing_priority_change() should be used in case nothing needs
258   * to be done during a priority change.
259   */
260  Thread_queue_Priority_change_operation priority_change;
261
262  /**
263   * @brief Thread queue enqueue operation.
264   *
265   * Called by object routines to enqueue the thread.
266   */
267  Thread_queue_Enqueue_operation enqueue;
268
269  /**
270   * @brief Thread queue extract operation.
271   *
272   * Called by object routines to extract a thread from a thread queue.
273   */
274  Thread_queue_Extract_operation extract;
275
276  /**
277   * @brief Thread queue first operation.
278   */
279  Thread_queue_First_operation first;
280} Thread_queue_Operations;
281
282/**
283 *  This is the structure used to manage sets of tasks which are blocked
284 *  waiting to acquire a resource.
285 */
286typedef struct {
287#if defined(RTEMS_SMP)
288#if defined(RTEMS_DEBUG)
289  /**
290   * @brief The index of the owning processor of the thread queue lock.
291   *
292   * The thread queue lock may be acquired via the thread lock also.  This path
293   * is not covered by this field.  In case the lock is not owned directly via
294   * _Thread_queue_Acquire(), then the value of this field is
295   * SMP_LOCK_NO_OWNER.
296   *
297   * Must be before the queue component of this structure to be able to re-use
298   * implementation parts for structures defined by Newlib <sys/lock.h>.
299   */
300  uint32_t owner;
301#endif
302
303#if defined(RTEMS_PROFILING)
304  /**
305   * @brief SMP lock statistics in case SMP and profiling are enabled.
306   *
307   * Must be before the queue component of this structure to be able to re-use
308   * implementation parts for structures defined by Newlib <sys/lock.h>.
309   */
310  SMP_lock_Stats Lock_stats;
311#endif
312#endif
313
314  /**
315   * @brief The actual thread queue.
316   */
317  Thread_queue_Queue Queue;
318} Thread_queue_Control;
319
320/**@}*/
321
322#ifdef __cplusplus
323}
324#endif
325
326#endif
327/* end of include file */
Note: See TracBrowser for help on using the repository browser.