source: rtems/cpukit/score/include/rtems/score/threadqimpl.h @ 07332ae

4.11
Last change on this file since 07332ae was 07332ae, checked in by Sebastian Huber <sebastian.huber@…>, on Aug 22, 2013 at 1:20:06 PM

score: _Thread_queue_Enqueue_with_handler()

Add thread parameter to _Thread_queue_Enqueue_with_handler() to avoid
access to global _Thread_Executing.

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