source: rtems/cpukit/sapi/inline/rtems/chain.inl @ 906dd57

4.9
Last change on this file since 906dd57 was 906dd57, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 13, 2008 at 3:10:24 PM

2008-11-13 Joel Sherrill <joel.sherrill@…>

PR 1336/cpukit

  • sapi/inline/rtems/chain.inl: Add rtems_chain_prepend_unprotected and rtems_chain_append_unprotected.
  • Property mode set to 100644
File size: 8.9 KB
Line 
1/**
2 * @file rtems/chain.inl
3 *
4 *  This include file contains all the constants and structures associated
5 *  with the Chain API in RTEMS. The chain is a double linked list that
6 *  is part of the Super Core. This is the published interface to that
7 *  code.
8 *
9 *  Iterate the node of a chain can be performed with the following code:
10 *
11 *     rtems_chain_control* cc = &object->pending;
12 *     rtems_chain_node*    cn = cc->first;
13 *     while (!rtems_chain_is_tail (cc, cn))
14 *     {
15 *       cn = cn->next;
16 *     }
17 */
18 
19/*
20 *  COPYRIGHT (c) 1989-2008.
21 *  On-Line Applications Research Corporation (OAR).
22 *
23 *  The license and distribution terms for this file may be
24 *  found in the file LICENSE in this distribution or at
25 *  http://www.rtems.com/license/LICENSE.
26 *
27 *  $Id$
28 */
29
30#ifndef _RTEMS_CHAIN_H
31# error "Never use <rtems/chain.inl> directly; include <rtems/chain.h> instead."
32#endif
33
34#ifndef _RTEMS_CHAIN_INL
35#define _RTEMS_CHAIN_INL
36
37#include <rtems/score/chain.inl>
38
39/**
40 *  @brief Initialize this Chain as Empty
41 *
42 *  This routine initializes the specified chain to contain zero nodes.
43 *
44 *  @param[in] the_chain is the chain to be initialized.
45 */
46RTEMS_INLINE_ROUTINE void rtems_chain_initialize_empty(
47  rtems_chain_control *the_chain
48)
49{
50  _Chain_Initialize_empty( the_chain );
51}
52
53/**
54 *  @brief Is the Chain Node Pointer NULL
55 *
56 *  This function returns true if the_node is NULL and false otherwise.
57 *
58 *  @param[in] the_node is the node pointer to check.
59 *
60 *  @return This method returns true if the_node is NULL and false otherwise.
61 */
62RTEMS_INLINE_ROUTINE bool rtems_chain_is_null_node(
63  const rtems_chain_node *the_node
64)
65{
66  return _Chain_Is_null_node( the_node );
67}
68
69/**
70 *  @brief Return pointer to Chain Head
71 *
72 *  This function returns a pointer to the first node on the chain.
73 *
74 *  @param[in] the_chain is the chain to be operated upon.
75 *
76 *  @return This method returns the permanent head node of the chain.
77 */
78RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_head(
79  rtems_chain_control *the_chain
80)
81{
82  return _Chain_Head( the_chain );
83}
84
85/**
86 *  @brief Return pointer to Chain Tail
87 *
88 *  This function returns a pointer to the last node on the chain.
89 *
90 *  @param[in] the_chain is the chain to be operated upon.
91 *
92 *  @return This method returns the permanent tail node of the chain.
93 */
94RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_tail(
95  rtems_chain_control *the_chain
96)
97{
98  return _Chain_Tail( the_chain );
99}
100
101/**
102 *  @brief Are Two Nodes Equal
103 *
104 *  This function returns true if @a left and @a right are equal,
105 *  and false otherwise.
106 *
107 *  @param[in] left is the node on the left hand side of the comparison.
108 *  @param[in] right is the node on the left hand side of the comparison.
109 *
110 *  @return This function returns true if @a left and @a right are equal,
111 *          and false otherwise.
112 */
113RTEMS_INLINE_ROUTINE bool rtems_chain_are_nodes_equal(
114  const rtems_chain_node *left,
115  const rtems_chain_node *right
116)
117{
118  return _Chain_Are_nodes_equal( left, right );
119}
120
121/**
122 *  @brief Is the Chain Empty
123 *
124 *  This function returns true if there a no nodes on @a the_chain and
125 *  false otherwise.
126 *
127 *  @param[in] the_chain is the chain to be operated upon.
128 *
129 *  @return This function returns true if there a no nodes on @a the_chain and
130 *  false otherwise.
131 */
132RTEMS_INLINE_ROUTINE bool rtems_chain_is_empty(
133  rtems_chain_control *the_chain
134)
135{
136  return _Chain_Is_empty( the_chain );
137}
138
139/**
140 *  @brief Is this the First Node on the Chain
141 *
142 *  This function returns true if the_node is the first node on a chain and
143 *  false otherwise.
144 *
145 *  @param[in] the_node is the node the caller wants to know if it is
146 *             the first node on a chain.
147 *
148 *  @return This function returns true if @a the_node is the first node on
149 *          a chain and false otherwise.
150 */
151RTEMS_INLINE_ROUTINE bool rtems_chain_is_first(
152  const rtems_chain_node *the_node
153)
154{
155  return _Chain_Is_first( the_node );
156}
157
158/**
159 *  @brief Is this the Last Node on the Chain
160 *
161 *  This function returns true if @a the_node is the last node on a chain and
162 *  false otherwise.
163 *
164 *  @param[in] the_node is the node to check as the last node.
165 *
166 *  @return This function returns true if @a the_node is the last node on
167 *          a chain and false otherwise.
168 */
169RTEMS_INLINE_ROUTINE bool rtems_chain_is_last(
170  const rtems_chain_node *the_node
171)
172{
173  return _Chain_Is_last( the_node );
174}
175
176/**
177 *  @brief Does this Chain have only One Node
178 *
179 *  This function returns true if there is only one node on @a the_chain and
180 *  false otherwise.
181 *
182 *  @param[in] the_chain is the chain to be operated upon.
183 *
184 *  @return This function returns true if there is only one node on
185 *          @a the_chain and false otherwise.
186 */
187RTEMS_INLINE_ROUTINE bool rtems_chain_has_only_one_node(
188  const rtems_chain_control *the_chain
189)
190{
191  return _Chain_Has_only_one_node( the_chain );
192}
193
194/**
195 *  @brief Is this Node the Chain Head
196 *
197 *  This function returns true if @a the_node is the head of the_chain and
198 *  false otherwise.
199 *
200 *  @param[in] the_chain is the chain to be operated upon.
201 *  @param[in] the_node is the node to check for being the Chain Head.
202 *
203 *  @return This function returns true if @a the_node is the head of
204 *          @a the_chain and false otherwise.
205 */
206RTEMS_INLINE_ROUTINE bool rtems_chain_is_head(
207  rtems_chain_control    *the_chain,
208  const rtems_chain_node *the_node
209)
210{
211  return _Chain_Is_head( the_chain, the_node );
212}
213
214/**
215 *  @brief Is this Node the Chail Tail
216 *
217 *  This function returns true if the_node is the tail of the_chain and
218 *  false otherwise.
219 *
220 *  @param[in] the_chain is the chain to be operated upon.
221 *  @param[in] the_node is the node to check for being the Chain Tail.
222 */
223RTEMS_INLINE_ROUTINE bool rtems_chain_is_tail(
224  rtems_chain_control    *the_chain,
225  const rtems_chain_node *the_node
226)
227{
228  return _Chain_Is_tail( the_chain, the_node );
229}
230
231/**
232 *  @brief Extract the specified node from a chain
233 *
234 *  This routine extracts @a the_node from the chain on which it resides.
235 *  It disables interrupts to ensure the atomicity of the
236 *  extract operation.
237 *
238 *  @arg the_node specifies the node to extract
239 */
240RTEMS_INLINE_ROUTINE void rtems_chain_extract(
241  rtems_chain_node *the_node
242)
243{
244  _Chain_Extract( the_node );
245}
246
247/**
248 *  @brief Obtain the first node on a chain
249 *
250 *  This function removes the first node from @a the_chain and returns
251 *  a pointer to that node.  If @a the_chain is empty, then NULL is returned.
252 *
253 *  @return This method returns a pointer a node.  If a node was removed,
254 *          then a pointer to that node is returned.  If @a the_chain was
255 *          empty, then NULL is returned.
256 *
257 *  @note It disables interrupts to ensure the atomicity of the get operation.
258 */
259RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_get(
260  rtems_chain_control *the_chain
261)
262{
263  return _Chain_Get( the_chain );
264}
265
266/**
267 *  @brief Insert a node on a chain
268 *
269 *  This routine inserts @a the_node on a chain immediately following
270 *  @a after_node. 
271 *
272 *  @note It disables interrupts to ensure the atomicity
273 *  of the extract operation.
274 */
275RTEMS_INLINE_ROUTINE void rtems_chain_insert(
276  rtems_chain_node *after_node,
277  rtems_chain_node *the_node
278)
279{
280  _Chain_Insert( after_node, the_node );
281}
282
283/**
284 *  @brief Append a node on the end of a chain
285 *
286 *  This routine appends @a the_node onto the end of @a the_chain.
287 *
288 *  @note It disables interrupts to ensure the atomicity of the
289 *  append operation.
290 */
291RTEMS_INLINE_ROUTINE void rtems_chain_append(
292  rtems_chain_control *the_chain,
293  rtems_chain_node    *the_node
294)
295{
296  _Chain_Append( the_chain, the_node );
297}
298
299/**
300 *  @brief Append a node on the end of a chain (unprotected)
301 *
302 *  This routine appends @a the_node onto the end of @a the_chain.
303 *
304 *  @note It does NOT disable interrupts to ensure the atomicity of the
305 *  append operation.
306 */
307RTEMS_INLINE_ROUTINE void rtems_chain_append_unprotected(
308  rtems_chain_control *the_chain,
309  rtems_chain_node    *the_node
310)
311{
312  _Chain_Append_unprotected( the_chain, the_node );
313}
314
315/** @brief Prepend a Node
316 *
317 *  This routine prepends the_node onto the front of the_chain.
318 *
319 *  @param[in] the_chain is the chain to be operated upon.
320 *  @param[in] the_node is the node to be prepended.
321 *
322 *  @note It disables interrupts to ensure the atomicity of the
323 *        prepend operation.
324 */
325RTEMS_INLINE_ROUTINE void rtems_chain_prepend(
326  rtems_chain_control *the_chain,
327  rtems_chain_node    *the_node
328)
329{
330  _Chain_Prepend( the_chain, the_node );
331}
332
333/** @brief Prepend a Node (unprotected)
334 *
335 *  This routine prepends the_node onto the front of the_chain.
336 *
337 *  @param[in] the_chain is the chain to be operated upon.
338 *  @param[in] the_node is the node to be prepended.
339 *
340 *  @note It does NOT disable interrupts to ensure the atomicity of the
341 *        prepend operation.
342 */
343RTEMS_INLINE_ROUTINE void rtems_chain_prepend_unprotected(
344  rtems_chain_control *the_chain,
345  rtems_chain_node    *the_node
346)
347{
348  _Chain_Prepend_unprotected( the_chain, the_node );
349}
350
351#endif
352/* end of include file */
Note: See TracBrowser for help on using the repository browser.