source: rtems/cpukit/score/include/rtems/score/threadq.h @ c4db18a

Last change on this file since c4db18a was c4db18a, checked in by Sebastian Huber <sebastian.huber@…>, on Sep 1, 2015 at 8:38:17 AM

score: Documentation

  • Property mode set to 100644
File size: 6.2 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/priority.h>
25#include <rtems/score/rbtree.h>
26
27#ifdef __cplusplus
28extern "C" {
29#endif
30
31/**
32 *  @defgroup ScoreThreadQueue Thread Queue Handler
33 *
34 *  @ingroup Score
35 *
36 *  This handler provides the capability to have threads block in
37 *  ordered sets. The sets may be ordered using the FIFO or priority
38 *  discipline.
39 */
40/**@{*/
41
42typedef struct _Thread_Control Thread_Control;
43
44/**
45 * @brief Thread queue heads.
46 *
47 * Each thread is equipped with spare thread queue heads in case it is not
48 * enqueued on a thread queue.  The first thread enqueued on a thread queue
49 * will give its spare thread queue heads to that thread queue.  The threads
50 * arriving at the queue will add their thread queue heads to the free chain of
51 * the queue heads provided by the first thread enqueued.  Once a thread is
52 * dequeued it use the free chain to get new spare thread queue heads.
53 *
54 * Uses a leading underscore in the structure name to allow forward
55 * declarations in standard header files provided by Newlib and GCC.
56 */
57typedef struct _Thread_queue_Heads {
58  /** This union contains the data structures used to manage the blocked
59   *  set of tasks which varies based upon the discipline.
60   */
61  union {
62    /**
63     * @brief This is the FIFO discipline list.
64     */
65    Chain_Control Fifo;
66
67    /**
68     * @brief This is the set of threads for priority discipline waiting.
69     */
70    RBTree_Control Priority;
71  } Heads;
72
73  /**
74   * @brief A chain with free thread queue heads providing the spare thread
75   * queue heads for a thread once it is dequeued.
76   */
77  Chain_Control Free_chain;
78
79  /**
80   * @brief A chain node to add these thread queue heads to the free chain of
81   * the thread queue heads dedicated to the thread queue of an object.
82   */
83  Chain_Node Free_node;
84} Thread_queue_Heads;
85
86typedef struct {
87  /**
88   * @brief The thread queue heads.
89   *
90   * This pointer is NULL, if and only if no threads are enqueued.  The first
91   * thread to enqueue will give its spare thread queue heads to this thread
92   * queue.
93   */
94  Thread_queue_Heads *heads;
95
96  /**
97   * @brief Lock to protect this thread queue.
98   *
99   * It may be used to protect additional state of the object embedding this
100   * thread queue.
101   *
102   * @see _Thread_queue_Acquire(), _Thread_queue_Acquire_critical() and
103   * _Thread_queue_Release().
104   */
105#if defined(RTEMS_SMP)
106  SMP_ticket_lock_Control Lock;
107#endif
108} Thread_queue_Queue;
109
110/**
111 * @brief Thread queue priority change operation.
112 *
113 * @param[in] the_thread The thread.
114 * @param[in] new_priority The new priority value.
115 * @param[in] queue The actual thread queue.
116 *
117 * @see Thread_queue_Operations.
118 */
119typedef void ( *Thread_queue_Priority_change_operation )(
120  Thread_Control     *the_thread,
121  Priority_Control    new_priority,
122  Thread_queue_Queue *queue
123);
124
125/**
126 * @brief Thread queue enqueue operation.
127 *
128 * @param[in] queue The actual thread queue.
129 * @param[in] the_thread The thread to enqueue on the queue.
130 *
131 * @see _Thread_Wait_set_operations().
132 */
133typedef void ( *Thread_queue_Enqueue_operation )(
134  Thread_queue_Queue *queue,
135  Thread_Control     *the_thread
136);
137
138/**
139 * @brief Thread queue extract operation.
140 *
141 * @param[in] queue The actual thread queue.
142 * @param[in] the_thread The thread to extract from the thread queue.
143 *
144 * @see _Thread_Wait_set_operations().
145 */
146typedef void ( *Thread_queue_Extract_operation )(
147  Thread_queue_Queue *queue,
148  Thread_Control     *the_thread
149);
150
151/**
152 * @brief Thread queue first operation.
153 *
154 * @param[in] heads The thread queue heads.
155 *
156 * @retval NULL No thread is present on the thread queue.
157 * @retval first The first thread of the thread queue according to the insert
158 * order.  This thread remains on the thread queue.
159 *
160 * @see _Thread_Wait_set_operations().
161 */
162typedef Thread_Control *( *Thread_queue_First_operation )(
163  Thread_queue_Heads *heads
164);
165
166/**
167 * @brief Thread queue operations.
168 *
169 * @see _Thread_wait_Set_operations().
170 */
171typedef struct {
172  /**
173   * @brief Thread queue priority change operation.
174   *
175   * Called by _Thread_Change_priority() to notify a thread about a priority
176   * change.  In case this thread waits currently for a resource the handler
177   * may adjust its data structures according to the new priority value.  This
178   * handler must not be NULL, instead the default handler
179   * _Thread_Do_nothing_priority_change() should be used in case nothing needs
180   * to be done during a priority change.
181   */
182  Thread_queue_Priority_change_operation priority_change;
183
184  /**
185   * @brief Thread queue enqueue operation.
186   *
187   * Called by object routines to enqueue the thread.
188   */
189  Thread_queue_Enqueue_operation enqueue;
190
191  /**
192   * @brief Thread queue extract operation.
193   *
194   * Called by object routines to extract a thread from a thread queue.
195   */
196  Thread_queue_Extract_operation extract;
197
198  /**
199   * @brief Thread queue first operation.
200   */
201  Thread_queue_First_operation first;
202} Thread_queue_Operations;
203
204/**
205 *  The following enumerated type details all of the disciplines
206 *  supported by the Thread Queue Handler.
207 */
208typedef enum {
209  THREAD_QUEUE_DISCIPLINE_FIFO,     /* FIFO queue discipline */
210  THREAD_QUEUE_DISCIPLINE_PRIORITY  /* PRIORITY queue discipline */
211}   Thread_queue_Disciplines;
212
213/**
214 *  This is the structure used to manage sets of tasks which are blocked
215 *  waiting to acquire a resource.
216 */
217typedef struct {
218  /**
219   * @brief The actual thread queue.
220   */
221  Thread_queue_Queue Queue;
222
223#if defined(RTEMS_SMP) && defined(RTEMS_PROFILING)
224  SMP_lock_Stats Lock_stats;
225#endif
226
227  /**
228   * @brief The operations for the actual thread queue.
229   */
230  const Thread_queue_Operations *operations;
231} Thread_queue_Control;
232
233/**@}*/
234
235#ifdef __cplusplus
236}
237#endif
238
239#endif
240/* end of include file */
Note: See TracBrowser for help on using the repository browser.