source: rtems/cpukit/score/include/rtems/score/threadqimpl.h @ b4bdbcf

4.115
Last change on this file since b4bdbcf was b4bdbcf, checked in by Sebastian Huber <sebastian.huber@…>, on May 15, 2014 at 7:41:20 AM

score: Make _Thread_queue_Requeue() static

This function is only used by _Thread_Change_priority(). Make it static
to avoid the function call overhead in the performance critical function
_Thread_Change_priority().

  • Property mode set to 100644
File size: 12.0 KB
Line 
1/**
2 *  @file  rtems/score/threadq.h
3 *
4 *  Constants and Structures Associated with the Manipulation of Objects
5 *
6 *  This include file contains all the constants and structures associated
7 *  with the manipulation of objects.
8 */
9
10/*
11 *  COPYRIGHT (c) 1989-2009.
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_THREADQIMPL_H
20#define _RTEMS_SCORE_THREADQIMPL_H
21
22#include <rtems/score/threadq.h>
23#include <rtems/score/thread.h>
24
25#ifdef __cplusplus
26extern "C" {
27#endif
28
29/**
30 *  @addtogroup ScoreThreadQueue
31 */
32/**@{*/
33
34/**
35 *  Constant for indefinite wait.
36 */
37#define THREAD_QUEUE_WAIT_FOREVER  WATCHDOG_NO_TIMEOUT
38
39/**
40 *  This is one of the constants used to manage the priority queues.
41 *  @ref TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS for more details.
42 */
43#define TASK_QUEUE_DATA_PRIORITIES_PER_HEADER      64
44
45/**
46 *  This is one of the constants used to manage the priority queues.
47 *  @ref TASK_QUEUE_DATA_NUMBER_OF_PRIORITY_HEADERS for more details.
48 */
49#define TASK_QUEUE_DATA_REVERSE_SEARCH_MASK        0x20
50
51/**
52 *  The following type defines the callout used when a remote task
53 *  is extracted from a local thread queue.
54 */
55typedef void ( *Thread_queue_Flush_callout )(
56                  Thread_Control *
57             );
58
59/**
60 *  The following type defines the callout used for timeout processing
61 *  methods.
62 */
63typedef void ( *Thread_queue_Timeout_callout )(
64                 Objects_Id,
65                 void *
66             );
67
68/**
69 *  @brief Gets a pointer to a thread waiting on the_thread_queue.
70 *
71 *  This function returns a pointer to a thread waiting on
72 *  the_thread_queue.  The selection of this thread is based on
73 *  the discipline of the_thread_queue.  If no threads are waiting
74 *  on the_thread_queue, then NULL is returned.
75 */
76Thread_Control *_Thread_queue_Dequeue(
77  Thread_queue_Control *the_thread_queue
78);
79
80/**
81 *  @brief Enqueues the currently executing thread on the_thread_queue.
82 *
83 *  This routine enqueues the currently executing thread on
84 *  the_thread_queue with an optional timeout.
85 */
86#define _Thread_queue_Enqueue( _the_thread_queue, _the_thread, _timeout ) \
87  _Thread_queue_Enqueue_with_handler( \
88    _the_thread_queue, \
89    _the_thread, \
90    _timeout, \
91    _Thread_queue_Timeout )
92
93/**
94 *  @brief Blocks a thread and places it on a thread.
95 *
96 *  This routine blocks a thread, places it on a thread, and optionally
97 *  starts a timeout timer.
98 *
99 *  @param[in] the_thread_queue pointer to threadq
100 *  @param[in] the_thread the thread to enqueue
101 *  @param[in] timeout interval to wait
102 *
103 *  - INTERRUPT LATENCY:
104 *    + single case
105 */
106void _Thread_queue_Enqueue_with_handler(
107  Thread_queue_Control         *the_thread_queue,
108  Thread_Control               *the_thread,
109  Watchdog_Interval             timeout,
110  Thread_queue_Timeout_callout  handler
111);
112
113/**
114 *  @brief Extracts thread from thread queue.
115 *
116 *  This routine removes @a the_thread from @a the_thread_queue
117 *  and cancels any timeouts associated with this blocking.
118 *
119 *  @param[in] the_thread_queue is the pointer to the ThreadQ header
120 *  @param[in] the_thread is the pointer to a thread control block that is to be removed
121 */
122void _Thread_queue_Extract(
123  Thread_queue_Control *the_thread_queue,
124  Thread_Control       *the_thread
125);
126
127void _Thread_queue_Extract_with_return_code(
128  Thread_queue_Control *the_thread_queue,
129  Thread_Control       *the_thread,
130  uint32_t              return_code
131);
132
133/**
134 *  @brief Extracts the_thread from the_thread_queue.
135 *
136 *  This routine extracts the_thread from the_thread_queue
137 *  and ensures that if there is a proxy for this task on
138 *  another node, it is also dealt with.
139 */
140void _Thread_queue_Extract_with_proxy(
141  Thread_Control       *the_thread
142);
143
144/**
145 *  @brief Gets a pointer to the "first" thread on the_thread_queue.
146 *
147 *  This function returns a pointer to the "first" thread
148 *  on the_thread_queue.  The "first" thread is selected
149 *  based on the discipline of the_thread_queue.
150 *
151 *  @param[in] the_thread_queue pointer to thread queue
152 *
153 *  @retval first thread or NULL
154 */
155Thread_Control *_Thread_queue_First(
156  Thread_queue_Control *the_thread_queue
157);
158
159/**
160 *  @brief Unblocks all threads blocked on the_thread_queue.
161 *
162 *  This routine unblocks all threads blocked on the_thread_queue
163 *  and cancels any associated timeouts.
164 *
165 *  @param[in] the_thread_queue is the pointer to a threadq header
166 *  @param[in] remote_extract_callout points to a method to invoke to
167 *             invoke when a remote thread is unblocked
168 *  @param[in] status is the status which will be returned to
169 *             all unblocked threads
170 */
171void _Thread_queue_Flush(
172  Thread_queue_Control       *the_thread_queue,
173  Thread_queue_Flush_callout  remote_extract_callout,
174  uint32_t                    status
175);
176
177/**
178 *  @brief Initialize the_thread_queue.
179 *
180 *  This routine initializes the_thread_queue based on the
181 *  discipline indicated in attribute_set.  The state set on
182 *  threads which block on the_thread_queue is state.
183 *
184 *  @param[in] the_thread_queue is the pointer to a threadq header
185 *  @param[in] the_discipline is the queueing discipline
186 *  @param[in] state is the state of waiting threads
187 *  @param[in] timeout_status is the return on a timeout
188 */
189void _Thread_queue_Initialize(
190  Thread_queue_Control         *the_thread_queue,
191  Thread_queue_Disciplines      the_discipline,
192  States_Control                state,
193  uint32_t                      timeout_status
194);
195
196/**
197 *  @brief Removes a thread from the specified PRIORITY based
198 *  threadq, unblocks it, and cancels its timeout timer.
199 *
200 *  This routine removes a thread from the specified PRIORITY based
201 *  threadq, unblocks it, and cancels its timeout timer.
202 *
203 *  - INTERRUPT LATENCY:
204 *    + single case
205 *
206 * @param[in] the_thread_queue is a pointer to a thread queue
207 *
208 * @retval thread dequeued
209 * @retval NULL if no thread are waiting on the_thread_queue
210 */
211Thread_Control *_Thread_queue_Dequeue_priority(
212  Thread_queue_Control *the_thread_queue
213);
214
215/**
216 *  @brief Enqueues the currently executing thread on the_thread_queue.
217 *
218 *  This routine enqueues the currently executing thread on
219 *  the_thread_queue with an optional timeout using the
220 *  priority discipline.
221 *
222 *  @param[in] the_thread_queue is the pointer to threadq
223 *  @param[in] the_thread is the thread to insert
224 *  @param[in] level_p is a pointer to an interrupt level to be returned
225 *
226 *  @retval This methods returns an indication of the blocking state as
227 *          well as filling in *@ level_p with the previous interrupt level.
228 *
229 *  - INTERRUPT LATENCY:
230 *    + forward less than
231 *    + forward equal
232 */
233Thread_blocking_operation_States _Thread_queue_Enqueue_priority (
234  Thread_queue_Control *the_thread_queue,
235  Thread_Control       *the_thread,
236  ISR_Level            *level_p
237);
238
239/**
240 *  @brief Removes the_thread and cancels related timeouts.
241 *
242 *  This routine removes the_thread from the_thread_queue
243 *  and cancels any timeouts associated with this blocking.
244 *  @param[in] the_thread_queue pointer to a threadq header
245 *  @param[in] the_thread pointer to a thread control block
246 *  @param[in] requeuing true if requeuing and should not alter
247 *         timeout or state
248 *  - INTERRUPT LATENCY:
249 *    + EXTRACT_PRIORITY
250 *
251 *  @retval true The extract operation was performed by the executing context.
252 *  @retval false Otherwise.
253 */
254void _Thread_queue_Extract_priority_helper(
255  Thread_Control       *the_thread,
256  uint32_t              return_code,
257  bool                  requeuing
258);
259
260/**
261 *  @brief Wraps the underlying call and hides the requeuing argument.
262 *
263 * This macro wraps the underlying call and hides the requeuing argument.
264 */
265
266#define _Thread_queue_Extract_priority( _the_thread, _return_code ) \
267  _Thread_queue_Extract_priority_helper( _the_thread, _return_code, false )
268/**
269 *  @brief Get highest priority thread on the_thread_queue.
270 *
271 *  This function returns a pointer to the "first" thread
272 *  on @a the_thread_queue.  The "first" thread is the highest
273 *  priority thread waiting on @a the_thread_queue.
274 *
275 *  @param[in] the_thread_queue is the pointer to the thread queue
276 *  @retval first thread or NULL
277 */
278Thread_Control *_Thread_queue_First_priority(
279  Thread_queue_Control *the_thread_queue
280);
281
282/**
283 *  @brief Gets a pointer to the thread which has been waiting the longest.
284 *
285 *  This function returns a pointer to the thread which has
286 *  been waiting the longest on  the_thread_queue.  If no
287 *  threads are waiting on the_thread_queue, then NULL is returned.
288 *
289 *  @param[in] the_thread_queue is the pointer to threadq
290 *
291 *  @retval thread dequeued or NULL
292 *
293 *  - INTERRUPT LATENCY:
294 *    + check sync
295 *    + FIFO
296 */
297Thread_Control *_Thread_queue_Dequeue_fifo(
298  Thread_queue_Control *the_thread_queue
299);
300
301/**
302 *  @brief Enqueues the currently executing thread on the_thread_queue.
303 *
304 *  This routine enqueues the currently executing thread on
305 *  the_thread_queue with an optional timeout using the
306 *  FIFO discipline.
307 *
308 *    @param[in] the_thread_queue pointer to threadq
309 *    @param[in] the_thread pointer to the thread to block
310 *    @param[in] level_p interrupt level in case the operation blocks actually
311 *
312 *  - INTERRUPT LATENCY:
313 *    + single case
314 */
315Thread_blocking_operation_States _Thread_queue_Enqueue_fifo (
316  Thread_queue_Control *the_thread_queue,
317  Thread_Control       *the_thread,
318  ISR_Level            *level_p
319);
320
321/**
322 *  @brief Removes the_thread from the_thread_queue and cancels any timeouts.
323 *
324 *  This routine removes the_thread from the_thread_queue
325 *  and cancels any timeouts associated with this blocking.
326 */
327void _Thread_queue_Extract_fifo(
328  Thread_Control       *the_thread,
329  uint32_t              return_code
330);
331
332/**
333 *  @brief Gets a pointer to the "first" thread on the_thread_queue.
334 *
335 *  This function returns a pointer to the "first" thread
336 *  on the_thread_queue.  The first thread is the thread
337 *  which has been waiting longest on the_thread_queue.
338 *
339 *  @param[in] the_thread_queue is the pointer to threadq
340 *
341 *  @retval first thread or NULL
342 */
343Thread_Control *_Thread_queue_First_fifo(
344  Thread_queue_Control *the_thread_queue
345);
346
347/**
348 *  @brief Thread queue timeout.
349 *
350 *  This routine is invoked when a task's request has not
351 *  been satisfied after the timeout interval specified to
352 *  enqueue.  The task represented by ID will be unblocked and
353 *  its status code will be set in it's control block to indicate
354 *  that a timeout has occurred.
355 *
356 *  @param[in] id thread id
357 */
358void _Thread_queue_Timeout (
359  Objects_Id  id,
360  void       *ignored
361);
362
363/**
364 *  @brief Process thread queue timeout.
365 *
366 * This is a shared helper routine which makes it easier to have multiple
367 * object class specific timeout routines.
368 *
369 * @param[in] the_thread is the thread to extract
370 *
371 * @note This method assumes thread dispatching is disabled
372 *       and is expected to be called via the processing of
373 *       a clock tick.
374 */
375void _Thread_queue_Process_timeout(
376  Thread_Control *the_thread
377);
378
379/**
380 * This function returns the index of the priority chain on which
381 * a thread of the_priority should be placed.
382 */
383
384RTEMS_INLINE_ROUTINE uint32_t   _Thread_queue_Header_number (
385  Priority_Control the_priority
386)
387{
388  return (the_priority / TASK_QUEUE_DATA_PRIORITIES_PER_HEADER);
389}
390
391/**
392 * This function returns true if the_priority indicates that the
393 * enqueue search should start at the front of this priority
394 * group chain, and false if the search should start at the rear.
395 */
396
397RTEMS_INLINE_ROUTINE bool _Thread_queue_Is_reverse_search (
398  Priority_Control the_priority
399)
400{
401  return ( the_priority & TASK_QUEUE_DATA_REVERSE_SEARCH_MASK );
402}
403
404/**
405 * This routine is invoked to indicate that the specified thread queue is
406 * entering a critical section.
407 */
408
409RTEMS_INLINE_ROUTINE void _Thread_queue_Enter_critical_section (
410  Thread_queue_Control *the_thread_queue
411)
412{
413  the_thread_queue->sync_state = THREAD_BLOCKING_OPERATION_NOTHING_HAPPENED;
414}
415
416/**@}*/
417
418#ifdef __cplusplus
419}
420#endif
421
422#endif
423/* end of include file */
Note: See TracBrowser for help on using the repository browser.