source: rtems/cpukit/score/include/rtems/score/threadq.h @ 631b3c8

Last change on this file since 631b3c8 was 631b3c8, checked in by Sebastian Huber <sebastian.huber@…>, on May 23, 2016 at 9:40:18 AM

score: Move thread queue MP callout to context

Drop the multiprocessing (MP) dependent callout parameter from the
thread queue extract, dequeue, flush and unblock methods. Merge this
parameter with the lock context into new structure Thread_queue_Context.
This helps to gets rid of the conditionally compiled method call
helpers.

  • Property mode set to 100644
File size: 8.5 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 The thread queue heads.
159   *
160   * This pointer is NULL, if and only if no threads are enqueued.  The first
161   * thread to enqueue will give its spare thread queue heads to this thread
162   * queue.
163   */
164  Thread_queue_Heads *heads;
165
166  /**
167   * @brief Lock to protect this thread queue.
168   *
169   * It may be used to protect additional state of the object embedding this
170   * thread queue.
171   *
172   * @see _Thread_queue_Acquire(), _Thread_queue_Acquire_critical() and
173   * _Thread_queue_Release().
174   */
175#if defined(RTEMS_SMP)
176  SMP_ticket_lock_Control Lock;
177#endif
178} Thread_queue_Queue;
179
180/**
181 * @brief Thread queue priority change operation.
182 *
183 * @param[in] the_thread The thread.
184 * @param[in] new_priority The new priority value.
185 * @param[in] queue The actual thread queue.
186 *
187 * @see Thread_queue_Operations.
188 */
189typedef void ( *Thread_queue_Priority_change_operation )(
190  Thread_Control     *the_thread,
191  Priority_Control    new_priority,
192  Thread_queue_Queue *queue
193);
194
195/**
196 * @brief Thread queue enqueue operation.
197 *
198 * @param[in] queue The actual thread queue.
199 * @param[in] the_thread The thread to enqueue on the queue.
200 *
201 * @see _Thread_Wait_set_operations().
202 */
203typedef void ( *Thread_queue_Enqueue_operation )(
204  Thread_queue_Queue *queue,
205  Thread_Control     *the_thread
206);
207
208/**
209 * @brief Thread queue extract operation.
210 *
211 * @param[in] queue The actual thread queue.
212 * @param[in] the_thread The thread to extract from the thread queue.
213 *
214 * @see _Thread_Wait_set_operations().
215 */
216typedef void ( *Thread_queue_Extract_operation )(
217  Thread_queue_Queue *queue,
218  Thread_Control     *the_thread
219);
220
221/**
222 * @brief Thread queue first operation.
223 *
224 * @param[in] heads The thread queue heads.
225 *
226 * @retval NULL No thread is present on the thread queue.
227 * @retval first The first thread of the thread queue according to the insert
228 * order.  This thread remains on the thread queue.
229 *
230 * @see _Thread_Wait_set_operations().
231 */
232typedef Thread_Control *( *Thread_queue_First_operation )(
233  Thread_queue_Heads *heads
234);
235
236/**
237 * @brief Thread queue operations.
238 *
239 * @see _Thread_wait_Set_operations().
240 */
241typedef struct {
242  /**
243   * @brief Thread queue priority change operation.
244   *
245   * Called by _Thread_Change_priority() to notify a thread about a priority
246   * change.  In case this thread waits currently for a resource the handler
247   * may adjust its data structures according to the new priority value.  This
248   * handler must not be NULL, instead the default handler
249   * _Thread_Do_nothing_priority_change() should be used in case nothing needs
250   * to be done during a priority change.
251   */
252  Thread_queue_Priority_change_operation priority_change;
253
254  /**
255   * @brief Thread queue enqueue operation.
256   *
257   * Called by object routines to enqueue the thread.
258   */
259  Thread_queue_Enqueue_operation enqueue;
260
261  /**
262   * @brief Thread queue extract operation.
263   *
264   * Called by object routines to extract a thread from a thread queue.
265   */
266  Thread_queue_Extract_operation extract;
267
268  /**
269   * @brief Thread queue first operation.
270   */
271  Thread_queue_First_operation first;
272} Thread_queue_Operations;
273
274/**
275 *  This is the structure used to manage sets of tasks which are blocked
276 *  waiting to acquire a resource.
277 */
278typedef struct {
279#if defined(RTEMS_SMP)
280#if defined(RTEMS_DEBUG)
281  /**
282   * @brief The index of the owning processor of the thread queue lock.
283   *
284   * The thread queue lock may be acquired via the thread lock also.  This path
285   * is not covered by this field.  In case the lock is not owned directly via
286   * _Thread_queue_Acquire(), then the value of this field is
287   * SMP_LOCK_NO_OWNER.
288   *
289   * Must be before the queue component of this structure to be able to re-use
290   * implementation parts for structures defined by Newlib <sys/lock.h>.
291   */
292  uint32_t owner;
293#endif
294
295#if defined(RTEMS_PROFILING)
296  /**
297   * @brief SMP lock statistics in case SMP and profiling are enabled.
298   *
299   * Must be before the queue component of this structure to be able to re-use
300   * implementation parts for structures defined by Newlib <sys/lock.h>.
301   */
302  SMP_lock_Stats Lock_stats;
303#endif
304#endif
305
306  /**
307   * @brief The actual thread queue.
308   */
309  Thread_queue_Queue Queue;
310} Thread_queue_Control;
311
312/**@}*/
313
314#ifdef __cplusplus
315}
316#endif
317
318#endif
319/* end of include file */
Note: See TracBrowser for help on using the repository browser.