source: rtems/cpukit/score/include/rtems/score/threadqimpl.h @ 215ccce

4.11
Last change on this file since 215ccce was 215ccce, checked in by Sebastian Huber <sebastian.huber@…>, on Aug 23, 2013 at 9:52:01 AM

score: PR2140: _Thread_queue_Extract()

Return if the executing context performed the extract operation since
interrupts may interfere.

  • Property mode set to 100644
File size: 12.6 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.com/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 Invoked when a thread changes priority and is blocked.
115 *
116 *  This routine is invoked when a thread changes priority and is
117 *  blocked on a thread queue.  If the queue is priority ordered,
118 *  the_thread is removed from the_thread_queue and reinserted using
119 *  its new priority.  This method has no impact on the state of the_thread
120 *  or of any timeouts associated with this blocking.
121 *
122 *  @param[in] the_thread_queue pointer to a threadq header
123 *  @param[in] the_thread pointer to a thread control block
124 */
125void _Thread_queue_Requeue(
126  Thread_queue_Control *the_thread_queue,
127  Thread_Control       *the_thread
128);
129
130/**
131 *  @brief Extracts thread from thread queue.
132 *
133 *  This routine removes @a the_thread from @a the_thread_queue
134 *  and cancels any timeouts associated with this blocking.
135 *
136 *  @param[in] the_thread_queue is the pointer to the ThreadQ header
137 *  @param[in] the_thread is the pointer to a thread control block that is to be removed
138 *
139 *  @retval true The extract operation was performed by the executing context.
140 *  @retval false Otherwise.
141 */
142bool _Thread_queue_Extract(
143  Thread_queue_Control *the_thread_queue,
144  Thread_Control       *the_thread
145);
146
147/**
148 *  @brief Extracts the_thread from the_thread_queue.
149 *
150 *  This routine extracts the_thread from the_thread_queue
151 *  and ensures that if there is a proxy for this task on
152 *  another node, it is also dealt with.
153 */
154bool _Thread_queue_Extract_with_proxy(
155  Thread_Control       *the_thread
156);
157
158/**
159 *  @brief Gets a pointer to the "first" thread on the_thread_queue.
160 *
161 *  This function returns a pointer to the "first" thread
162 *  on the_thread_queue.  The "first" thread is selected
163 *  based on the discipline of the_thread_queue.
164 *
165 *  @param[in] the_thread_queue pointer to thread queue
166 *
167 *  @retval first thread or NULL
168 */
169Thread_Control *_Thread_queue_First(
170  Thread_queue_Control *the_thread_queue
171);
172
173/**
174 *  @brief Unblocks all threads blocked on the_thread_queue.
175 *
176 *  This routine unblocks all threads blocked on the_thread_queue
177 *  and cancels any associated timeouts.
178 *
179 *  @param[in] the_thread_queue is the pointer to a threadq header
180 *  @param[in] remote_extract_callout points to a method to invoke to
181 *             invoke when a remote thread is unblocked
182 *  @param[in] status is the status which will be returned to
183 *             all unblocked threads
184 */
185void _Thread_queue_Flush(
186  Thread_queue_Control       *the_thread_queue,
187  Thread_queue_Flush_callout  remote_extract_callout,
188  uint32_t                    status
189);
190
191/**
192 *  @brief Initialize the_thread_queue.
193 *
194 *  This routine initializes the_thread_queue based on the
195 *  discipline indicated in attribute_set.  The state set on
196 *  threads which block on the_thread_queue is state.
197 *
198 *  @param[in] the_thread_queue is the pointer to a threadq header
199 *  @param[in] the_discipline is the queueing discipline
200 *  @param[in] state is the state of waiting threads
201 *  @param[in] timeout_status is the return on a timeout
202 */
203void _Thread_queue_Initialize(
204  Thread_queue_Control         *the_thread_queue,
205  Thread_queue_Disciplines      the_discipline,
206  States_Control                state,
207  uint32_t                      timeout_status
208);
209
210/**
211 *  @brief Removes a thread from the specified PRIORITY based
212 *  threadq, unblocks it, and cancels its timeout timer.
213 *
214 *  This routine removes a thread from the specified PRIORITY based
215 *  threadq, unblocks it, and cancels its timeout timer.
216 *
217 *  - INTERRUPT LATENCY:
218 *    + single case
219 *
220 * @param[in] the_thread_queue is a pointer to a thread queue
221 *
222 * @retval thread dequeued
223 * @retval NULL if no thread are waiting on the_thread_queue
224 */
225Thread_Control *_Thread_queue_Dequeue_priority(
226  Thread_queue_Control *the_thread_queue
227);
228
229/**
230 *  @brief Enqueues the currently executing thread on the_thread_queue.
231 *
232 *  This routine enqueues the currently executing thread on
233 *  the_thread_queue with an optional timeout using the
234 *  priority discipline.
235 *
236 *  @param[in] the_thread_queue is the pointer to threadq
237 *  @param[in] the_thread is the thread to insert
238 *  @param[in] level_p is a pointer to an interrupt level to be returned
239 *
240 *  @retval This methods returns an indication of the blocking state as
241 *          well as filling in *@ level_p with the previous interrupt level.
242 *
243 *  - INTERRUPT LATENCY:
244 *    + forward less than
245 *    + forward equal
246 */
247Thread_blocking_operation_States _Thread_queue_Enqueue_priority (
248  Thread_queue_Control *the_thread_queue,
249  Thread_Control       *the_thread,
250  ISR_Level            *level_p
251);
252
253/**
254 *  @brief Removes the_thread and cancels related timeouts.
255 *
256 *  This routine removes the_thread from the_thread_queue
257 *  and cancels any timeouts associated with this blocking.
258 *  @param[in] the_thread_queue pointer to a threadq header
259 *  @param[in] the_thread pointer to a thread control block
260 *  @param[in] requeuing true if requeuing and should not alter
261 *         timeout or state
262 *  - INTERRUPT LATENCY:
263 *    + EXTRACT_PRIORITY
264 *
265 *  @retval true The extract operation was performed by the executing context.
266 *  @retval false Otherwise.
267 */
268bool _Thread_queue_Extract_priority_helper(
269  Thread_queue_Control *the_thread_queue,
270  Thread_Control       *the_thread,
271  bool                  requeuing
272);
273
274/**
275 *  @brief Wraps the underlying call and hides the requeuing argument.
276 *
277 * This macro wraps the underlying call and hides the requeuing argument.
278 */
279
280#define _Thread_queue_Extract_priority( _the_thread_queue, _the_thread ) \
281  _Thread_queue_Extract_priority_helper( _the_thread_queue, _the_thread, false )
282/**
283 *  @brief Get highest priority thread on the_thread_queue.
284 *
285 *  This function returns a pointer to the "first" thread
286 *  on @a the_thread_queue.  The "first" thread is the highest
287 *  priority thread waiting on @a the_thread_queue.
288 *
289 *  @param[in] the_thread_queue is the pointer to the thread queue
290 *  @retval first thread or NULL
291 */
292Thread_Control *_Thread_queue_First_priority(
293  Thread_queue_Control *the_thread_queue
294);
295
296/**
297 *  @brief Gets a pointer to the thread which has been waiting the longest.
298 *
299 *  This function returns a pointer to the thread which has
300 *  been waiting the longest on  the_thread_queue.  If no
301 *  threads are waiting on the_thread_queue, then NULL is returned.
302 *
303 *  @param[in] the_thread_queue is the pointer to threadq
304 *
305 *  @retval thread dequeued or NULL
306 *
307 *  - INTERRUPT LATENCY:
308 *    + check sync
309 *    + FIFO
310 */
311Thread_Control *_Thread_queue_Dequeue_fifo(
312  Thread_queue_Control *the_thread_queue
313);
314
315/**
316 *  @brief Enqueues the currently executing thread on the_thread_queue.
317 *
318 *  This routine enqueues the currently executing thread on
319 *  the_thread_queue with an optional timeout using the
320 *  FIFO discipline.
321 *
322 *    @param[in] the_thread_queue pointer to threadq
323 *    @param[in] the_thread pointer to the thread to block
324 *    @param[in] level_p interrupt level in case the operation blocks actually
325 *
326 *  - INTERRUPT LATENCY:
327 *    + single case
328 */
329Thread_blocking_operation_States _Thread_queue_Enqueue_fifo (
330  Thread_queue_Control *the_thread_queue,
331  Thread_Control       *the_thread,
332  ISR_Level            *level_p
333);
334
335/**
336 *  @brief Removes the_thread from the_thread_queue and cancels any timeouts.
337 *
338 *  This routine removes the_thread from the_thread_queue
339 *  and cancels any timeouts associated with this blocking.
340 */
341bool _Thread_queue_Extract_fifo(
342  Thread_queue_Control *the_thread_queue,
343  Thread_Control       *the_thread
344);
345
346/**
347 *  @brief Gets a pointer to the "first" thread on the_thread_queue.
348 *
349 *  This function returns a pointer to the "first" thread
350 *  on the_thread_queue.  The first thread is the thread
351 *  which has been waiting longest on the_thread_queue.
352 *
353 *  @param[in] the_thread_queue is the pointer to threadq
354 *
355 *  @retval first thread or NULL
356 */
357Thread_Control *_Thread_queue_First_fifo(
358  Thread_queue_Control *the_thread_queue
359);
360
361/**
362 *  @brief Thread queue timeout.
363 *
364 *  This routine is invoked when a task's request has not
365 *  been satisfied after the timeout interval specified to
366 *  enqueue.  The task represented by ID will be unblocked and
367 *  its status code will be set in it's control block to indicate
368 *  that a timeout has occurred.
369 *
370 *  @param[in] id thread id
371 */
372void _Thread_queue_Timeout (
373  Objects_Id  id,
374  void       *ignored
375);
376
377/**
378 *  @brief Process thread queue timeout.
379 *
380 * This is a shared helper routine which makes it easier to have multiple
381 * object class specific timeout routines.
382 *
383 * @param[in] the_thread is the thread to extract
384 *
385 * @note This method assumes thread dispatching is disabled
386 *       and is expected to be called via the processing of
387 *       a clock tick.
388 */
389void _Thread_queue_Process_timeout(
390  Thread_Control *the_thread
391);
392
393/**
394 * This function returns the index of the priority chain on which
395 * a thread of the_priority should be placed.
396 */
397
398RTEMS_INLINE_ROUTINE uint32_t   _Thread_queue_Header_number (
399  Priority_Control the_priority
400)
401{
402  return (the_priority / TASK_QUEUE_DATA_PRIORITIES_PER_HEADER);
403}
404
405/**
406 * This function returns true if the_priority indicates that the
407 * enqueue search should start at the front of this priority
408 * group chain, and false if the search should start at the rear.
409 */
410
411RTEMS_INLINE_ROUTINE bool _Thread_queue_Is_reverse_search (
412  Priority_Control the_priority
413)
414{
415  return ( the_priority & TASK_QUEUE_DATA_REVERSE_SEARCH_MASK );
416}
417
418/**
419 * This routine is invoked to indicate that the specified thread queue is
420 * entering a critical section.
421 */
422
423RTEMS_INLINE_ROUTINE void _Thread_queue_Enter_critical_section (
424  Thread_queue_Control *the_thread_queue
425)
426{
427  the_thread_queue->sync_state = THREAD_BLOCKING_OPERATION_NOTHING_HAPPENED;
428}
429
430/**@}*/
431
432#ifdef __cplusplus
433}
434#endif
435
436#endif
437/* end of include file */
Note: See TracBrowser for help on using the repository browser.