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

4.115
Last change on this file since 3250664 was 3250664, checked in by Joel Sherrill <joel.sherrill@…>, on 07/15/14 at 17:37:36

Thread Queue: Merge discipline subroutines into main methods

There was a lot of duplication between the discipline subroutines.
With the transition to RBTrees for priority discipline, there were
only a few lines of source code manipulating the data structure
for FIFO and priority. Thus is made sense to fold these back
into the main methods.

As part of doing this all of the tests for discipline were changed
to be in the same order.

  • Property mode set to 100644
File size: 8.5 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-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_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 *  The following type defines the callout used when a remote task
41 *  is extracted from a local thread queue.
42 */
43typedef void ( *Thread_queue_Flush_callout )(
44                  Thread_Control *
45             );
46
47/**
48 *  The following type defines the callout used for timeout processing
49 *  methods.
50 */
51typedef void ( *Thread_queue_Timeout_callout )(
52                 Objects_Id,
53                 void *
54             );
55
56/**
57 *  @brief Gets a pointer to a thread waiting on the_thread_queue.
58 *
59 *  This function returns a pointer to a thread waiting on
60 *  the_thread_queue.  The selection of this thread is based on
61 *  the discipline of the_thread_queue.  If no threads are waiting
62 *  on the_thread_queue, then NULL is returned.
63 *
64 *  - INTERRUPT LATENCY:
65 *    + single case
66 */
67Thread_Control *_Thread_queue_Dequeue(
68  Thread_queue_Control *the_thread_queue
69);
70
71/**
72 *  @brief Enqueues the currently executing thread on the_thread_queue.
73 *
74 *  This routine enqueues the currently executing thread on
75 *  the_thread_queue with an optional timeout.
76 */
77#define _Thread_queue_Enqueue( _the_thread_queue, _the_thread, _timeout ) \
78  _Thread_queue_Enqueue_with_handler( \
79    _the_thread_queue, \
80    _the_thread, \
81    _timeout, \
82    _Thread_queue_Timeout )
83
84/**
85 *  @brief Blocks a thread and places it on a thread.
86 *
87 *  This routine blocks a thread, places it on a thread, and optionally
88 *  starts a timeout timer.
89 *
90 *  @param[in] the_thread_queue pointer to threadq
91 *  @param[in] the_thread the thread to enqueue
92 *  @param[in] timeout interval to wait
93 *
94 *  - INTERRUPT LATENCY:
95 *    + single case
96 */
97void _Thread_queue_Enqueue_with_handler(
98  Thread_queue_Control         *the_thread_queue,
99  Thread_Control               *the_thread,
100  Watchdog_Interval             timeout,
101  Thread_queue_Timeout_callout  handler
102);
103
104/**
105 *  @brief Extracts thread from thread queue.
106 *
107 *  This routine removes @a the_thread from @a the_thread_queue
108 *  and cancels any timeouts associated with this blocking.
109 *
110 *  @param[in] the_thread_queue is the pointer to the ThreadQ header
111 *  @param[in] the_thread is the pointer to a thread control block that
112 *      is to be removed
113 */
114void _Thread_queue_Extract(
115  Thread_queue_Control *the_thread_queue,
116  Thread_Control       *the_thread
117);
118
119/**
120 *  @brief Extracts thread from thread queue (w/return code).
121 *
122 *  This routine removes @a the_thread from @a the_thread_queue
123 *  and cancels any timeouts associated with this blocking.
124 *
125 *  @param[in] the_thread_queue is the pointer to the ThreadQ header
126 *  @param[in] the_thread is the pointer to a thread control block that
127 *      is to be removed
128 *  @param[in] return_code specifies the status to be returned.
129 *
130 *  - INTERRUPT LATENCY:
131 *    + single case
132 */
133void _Thread_queue_Extract_with_return_code(
134  Thread_queue_Control *the_thread_queue,
135  Thread_Control       *the_thread,
136  uint32_t              return_code
137);
138
139/**
140 *  @brief Extracts the_thread from the_thread_queue.
141 *
142 *  This routine extracts the_thread from the_thread_queue
143 *  and ensures that if there is a proxy for this task on
144 *  another node, it is also dealt with.
145 */
146void _Thread_queue_Extract_with_proxy(
147  Thread_Control       *the_thread
148);
149
150/**
151 *  @brief Gets a pointer to the "first" thread on the_thread_queue.
152 *
153 *  This function returns a pointer to the "first" thread
154 *  on the_thread_queue.  The "first" thread is selected
155 *  based on the discipline of the_thread_queue.
156 *
157 *  @param[in] the_thread_queue pointer to thread queue
158 *
159 *  @retval first thread or NULL
160 */
161Thread_Control *_Thread_queue_First(
162  Thread_queue_Control *the_thread_queue
163);
164
165/**
166 *  @brief Unblocks all threads blocked on the_thread_queue.
167 *
168 *  This routine unblocks all threads blocked on the_thread_queue
169 *  and cancels any associated timeouts.
170 *
171 *  @param[in] the_thread_queue is the pointer to a threadq header
172 *  @param[in] remote_extract_callout points to a method to invoke to
173 *             invoke when a remote thread is unblocked
174 *  @param[in] status is the status which will be returned to
175 *             all unblocked threads
176 */
177void _Thread_queue_Flush(
178  Thread_queue_Control       *the_thread_queue,
179  Thread_queue_Flush_callout  remote_extract_callout,
180  uint32_t                    status
181);
182
183/**
184 *  @brief Initialize the_thread_queue.
185 *
186 *  This routine initializes the_thread_queue based on the
187 *  discipline indicated in attribute_set.  The state set on
188 *  threads which block on the_thread_queue is state.
189 *
190 *  @param[in] the_thread_queue is the pointer to a threadq header
191 *  @param[in] the_discipline is the queueing discipline
192 *  @param[in] state is the state of waiting threads
193 *  @param[in] timeout_status is the return on a timeout
194 */
195void _Thread_queue_Initialize(
196  Thread_queue_Control         *the_thread_queue,
197  Thread_queue_Disciplines      the_discipline,
198  States_Control                state,
199  uint32_t                      timeout_status
200);
201
202/**
203 *  @brief Removes a thread from the specified PRIORITY based
204 *  threadq, unblocks it, and cancels its timeout timer.
205 *
206 *  This routine removes a thread from the specified PRIORITY based
207 *  threadq, unblocks it, and cancels its timeout timer.
208 *
209 *  - INTERRUPT LATENCY:
210 *    + single case
211 *
212 * @param[in] the_thread_queue is a pointer to a thread queue
213 *
214 * @retval thread dequeued
215 * @retval NULL if no thread are waiting on the_thread_queue
216 */
217Thread_Control *_Thread_queue_Dequeue_priority(
218  Thread_queue_Control *the_thread_queue
219);
220
221/**
222 *  @brief Thread queue timeout.
223 *
224 *  This routine is invoked when a task's request has not
225 *  been satisfied after the timeout interval specified to
226 *  enqueue.  The task represented by ID will be unblocked and
227 *  its status code will be set in it's control block to indicate
228 *  that a timeout has occurred.
229 *
230 *  @param[in] id thread id
231 */
232void _Thread_queue_Timeout(
233  Objects_Id  id,
234  void       *ignored
235);
236
237/**
238 *  @brief Process thread queue timeout.
239 *
240 * This is a shared helper routine which makes it easier to have multiple
241 * object class specific timeout routines.
242 *
243 * @param[in] the_thread is the thread to extract
244 *
245 * @note This method assumes thread dispatching is disabled
246 *       and is expected to be called via the processing of
247 *       a clock tick.
248 */
249void _Thread_queue_Process_timeout(
250  Thread_Control *the_thread
251);
252
253/**
254 * @brief Compare two thread's priority for RBTree Insertion.
255 *
256 * @param[in] left points to the left thread's RBnode
257 * @param[in] right points to the right thread's RBnode
258 *
259 * @retval 1 The @left node is more important than @right node.
260 * @retval 0 The @left node is of equal importance with @right node.
261 * @retval 1 The @left node is less important than @right node.
262 */
263int _Thread_queue_Compare_priority(
264  const RBTree_Node *left,
265  const RBTree_Node *right
266);
267
268/**
269 *  @brief Invoked when a thread changes priority and is blocked.
270 *
271 *  This routine is invoked when a thread changes priority and is
272 *  blocked on a thread queue.  If the queue is priority ordered,
273 *  the_thread is removed from the_thread_queue and reinserted using
274 *  its new priority.  This method has no impact on the state of the_thread
275 *  or of any timeouts associated with this blocking.
276 *
277 *  @param[in] the_thread_queue pointer to a threadq header
278 *  @param[in] the_thread pointer to a thread control block
279 */
280void _Thread_queue_Requeue(
281  Thread_queue_Control *the_thread_queue,
282  Thread_Control       *the_thread
283);
284
285/**
286 * This routine is invoked to indicate that the specified thread queue is
287 * entering a critical section.
288 */
289RTEMS_INLINE_ROUTINE void _Thread_queue_Enter_critical_section (
290  Thread_queue_Control *the_thread_queue
291)
292{
293  the_thread_queue->sync_state = THREAD_BLOCKING_OPERATION_NOTHING_HAPPENED;
294}
295
296/**@}*/
297
298#ifdef __cplusplus
299}
300#endif
301
302#endif
303/* end of include file */
Note: See TracBrowser for help on using the repository browser.