source: rtems/cpukit/sapi/inline/rtems/chain.inl @ b8af65a

4.11
Last change on this file since b8af65a was b8af65a, checked in by Sebastian Huber <sebastian.huber@…>, on Aug 9, 2010 at 7:38:51 AM

2010-08-09 Sebastian Huber <sebastian.huber@…>

  • sapi/inline/rtems/chain.inl: Added rtems_chain_extract_unprotected().
  • Property mode set to 100644
File size: 12.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 a Chain Header
41 *
42 *  This routine initializes @a the_chain structure to manage the
43 *  contiguous array of @a number_nodes nodes which starts at
44 *  @a starting_address.  Each node is of @a node_size bytes.
45 *
46 *  @param[in] the_chain specifies the chain to initialize
47 *  @param[in] starting_address is the starting address of the array
48 *         of elements
49 *  @param[in] number_nodes is the number of nodes that will be in the chain
50 *  @param[in] node_size is the size of each node
51 */
52RTEMS_INLINE_ROUTINE void rtems_chain_initialize(
53  rtems_chain_control *the_chain,
54  void                *starting_address,
55  size_t               number_nodes,
56  size_t               node_size
57)
58{
59  _Chain_Initialize( the_chain, starting_address, number_nodes, node_size );
60}
61
62/**
63 *  @brief Initialize this Chain as Empty
64 *
65 *  This routine initializes the specified chain to contain zero nodes.
66 *
67 *  @param[in] the_chain is the chain to be initialized.
68 */
69RTEMS_INLINE_ROUTINE void rtems_chain_initialize_empty(
70  rtems_chain_control *the_chain
71)
72{
73  _Chain_Initialize_empty( the_chain );
74}
75
76/**
77 *  @brief Set off chain
78 *
79 *  This function sets the next and previous fields of the @a node to NULL
80 *  indicating the @a node is not part of a chain.
81 *
82 *  @param[in] node the node set to off chain.
83 */
84RTEMS_INLINE_ROUTINE void rtems_chain_set_off_chain(
85  rtems_chain_node *node
86)
87{
88  _Chain_Set_off_chain( node );
89}
90
91/**
92 *  @brief Is the Node off Chain
93 *
94 *  This function returns true if the @a node is not on a chain. A @a node is
95 *  off chain if the next and previous fields are set to NULL.
96 *
97 *  @param[in] node is the node off chain.
98 *
99 *  @return This function returns true if the @a node is off chain.
100 */
101RTEMS_INLINE_ROUTINE bool rtems_chain_is_node_off_chain(
102  const rtems_chain_node *node
103)
104{
105  return _Chain_Is_node_off_chain( node );
106}
107
108/**
109 *  @brief Is the Chain Node Pointer NULL
110 *
111 *  This function returns true if the_node is NULL and false otherwise.
112 *
113 *  @param[in] the_node is the node pointer to check.
114 *
115 *  @return This method returns true if the_node is NULL and false otherwise.
116 */
117RTEMS_INLINE_ROUTINE bool rtems_chain_is_null_node(
118  const rtems_chain_node *the_node
119)
120{
121  return _Chain_Is_null_node( the_node );
122}
123
124/**
125 *  @brief Return pointer to Chain Head
126 *
127 *  This function returns a pointer to the first node on the chain.
128 *
129 *  @param[in] the_chain is the chain to be operated upon.
130 *
131 *  @return This method returns the permanent  node of the chain.
132 */
133RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_head(
134  rtems_chain_control *the_chain
135)
136{
137  return _Chain_Head( the_chain );
138}
139
140/**
141 *  @brief Return pointer to Chain Tail
142 *
143 *  This function returns a pointer to the last node on the chain.
144 *
145 *  @param[in] the_chain is the chain to be operated upon.
146 *
147 *  @return This method returns the permanent tail node of the chain.
148 */
149RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_tail(
150  rtems_chain_control *the_chain
151)
152{
153  return _Chain_Tail( the_chain );
154}
155
156/**
157 *  @brief Return pointer to Chain's First node after the permanent head.
158 *
159 *  This function returns a pointer to the first node on the chain after the
160 *  head.
161 *
162 *  @param[in] the_chain is the chain to be operated upon.
163 *
164 *  @return This method returns the first node of the chain.
165 */
166RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_first(
167  rtems_chain_control *the_chain
168)
169{
170  return _Chain_First( the_chain );
171}
172
173/**
174 *  @brief Return pointer to Chain's Last node before the permanent tail.
175 *
176 *  This function returns a pointer to the last node on the chain just before
177 *  the tail.
178 *
179 *  @param[in] the_chain is the chain to be operated upon.
180 *
181 *  @return This method returns the last node of the chain.
182 */
183RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_last(
184  rtems_chain_control *the_chain
185)
186{
187  return _Chain_Last( the_chain );
188}
189
190/**
191 *  @brief Return pointer the next node from this node
192 *
193 *  This function returns a pointer to the next node after this node.
194 *
195 *  @param[in] the_node is the node to be operated upon.
196 *
197 *  @return This method returns the next node on the chain.
198 */
199RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_next(
200  rtems_chain_node *the_node
201)
202{
203  return _Chain_Next( the_node );
204}
205
206/**
207 *  @brief Return pointer the previous node from this node
208 *
209 *  This function returns a pointer to the previous node on this chain.
210 *
211 *  @param[in] the_node is the node to be operated upon.
212 *
213 *  @return This method returns the previous node on the chain.
214 */
215RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_previous(
216  rtems_chain_node *the_node
217)
218{
219  return _Chain_Previous( the_node );
220}
221
222/**
223 *  @brief Are Two Nodes Equal
224 *
225 *  This function returns true if @a left and @a right are equal,
226 *  and false otherwise.
227 *
228 *  @param[in] left is the node on the left hand side of the comparison.
229 *  @param[in] right is the node on the left hand side of the comparison.
230 *
231 *  @return This function returns true if @a left and @a right are equal,
232 *          and false otherwise.
233 */
234RTEMS_INLINE_ROUTINE bool rtems_chain_are_nodes_equal(
235  const rtems_chain_node *left,
236  const rtems_chain_node *right
237)
238{
239  return _Chain_Are_nodes_equal( left, right );
240}
241
242/**
243 *  @brief Is the Chain Empty
244 *
245 *  This function returns true if there a no nodes on @a the_chain and
246 *  false otherwise.
247 *
248 *  @param[in] the_chain is the chain to be operated upon.
249 *
250 *  @return This function returns true if there a no nodes on @a the_chain and
251 *  false otherwise.
252 */
253RTEMS_INLINE_ROUTINE bool rtems_chain_is_empty(
254  rtems_chain_control *the_chain
255)
256{
257  return _Chain_Is_empty( the_chain );
258}
259
260/**
261 *  @brief Is this the First Node on the Chain
262 *
263 *  This function returns true if the_node is the first node on a chain and
264 *  false otherwise.
265 *
266 *  @param[in] the_node is the node the caller wants to know if it is
267 *             the first node on a chain.
268 *
269 *  @return This function returns true if @a the_node is the first node on
270 *          a chain and false otherwise.
271 */
272RTEMS_INLINE_ROUTINE bool rtems_chain_is_first(
273  const rtems_chain_node *the_node
274)
275{
276  return _Chain_Is_first( the_node );
277}
278
279/**
280 *  @brief Is this the Last Node on the Chain
281 *
282 *  This function returns true if @a the_node is the last node on a chain and
283 *  false otherwise.
284 *
285 *  @param[in] the_node is the node to check as the last node.
286 *
287 *  @return This function returns true if @a the_node is the last node on
288 *          a chain and false otherwise.
289 */
290RTEMS_INLINE_ROUTINE bool rtems_chain_is_last(
291  const rtems_chain_node *the_node
292)
293{
294  return _Chain_Is_last( the_node );
295}
296
297/**
298 *  @brief Does this Chain have only One Node
299 *
300 *  This function returns true if there is only one node on @a the_chain and
301 *  false otherwise.
302 *
303 *  @param[in] the_chain is the chain to be operated upon.
304 *
305 *  @return This function returns true if there is only one node on
306 *          @a the_chain and false otherwise.
307 */
308RTEMS_INLINE_ROUTINE bool rtems_chain_has_only_one_node(
309  const rtems_chain_control *the_chain
310)
311{
312  return _Chain_Has_only_one_node( the_chain );
313}
314
315/**
316 *  @brief Is this Node the Chain Head
317 *
318 *  This function returns true if @a the_node is the head of the_chain and
319 *  false otherwise.
320 *
321 *  @param[in] the_chain is the chain to be operated upon.
322 *  @param[in] the_node is the node to check for being the Chain Head.
323 *
324 *  @return This function returns true if @a the_node is the head of
325 *          @a the_chain and false otherwise.
326 */
327RTEMS_INLINE_ROUTINE bool rtems_chain_is_head(
328  rtems_chain_control    *the_chain,
329  const rtems_chain_node *the_node
330)
331{
332  return _Chain_Is_head( the_chain, the_node );
333}
334
335/**
336 *  @brief Is this Node the Chail Tail
337 *
338 *  This function returns true if the_node is the tail of the_chain and
339 *  false otherwise.
340 *
341 *  @param[in] the_chain is the chain to be operated upon.
342 *  @param[in] the_node is the node to check for being the Chain Tail.
343 */
344RTEMS_INLINE_ROUTINE bool rtems_chain_is_tail(
345  rtems_chain_control    *the_chain,
346  const rtems_chain_node *the_node
347)
348{
349  return _Chain_Is_tail( the_chain, the_node );
350}
351
352/**
353 *  @brief Extract the specified node from a chain
354 *
355 *  This routine extracts @a the_node from the chain on which it resides.
356 *  It disables interrupts to ensure the atomicity of the
357 *  extract operation.
358 *
359 *  @arg the_node specifies the node to extract
360 */
361RTEMS_INLINE_ROUTINE void rtems_chain_extract(
362  rtems_chain_node *the_node
363)
364{
365  _Chain_Extract( the_node );
366}
367
368/**
369 *  @brief Extract the specified node from a chain (unprotected).
370 *
371 *  This routine extracts @a the_node from the chain on which it resides.
372 *
373 *  @note It does NOT disable interrupts to ensure the atomicity of the
374 *  append operation.
375 */
376RTEMS_INLINE_ROUTINE void rtems_chain_extract_unprotected(
377  rtems_chain_node *the_node
378)
379{
380  _Chain_Extract_unprotected( the_node );
381}
382
383/**
384 *  @brief Obtain the first node on a chain
385 *
386 *  This function removes the first node from @a the_chain and returns
387 *  a pointer to that node.  If @a the_chain is empty, then NULL is returned.
388 *
389 *  @return This method returns a pointer a node.  If a node was removed,
390 *          then a pointer to that node is returned.  If @a the_chain was
391 *          empty, then NULL is returned.
392 *
393 *  @note It disables interrupts to ensure the atomicity of the get operation.
394 */
395RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_get(
396  rtems_chain_control *the_chain
397)
398{
399  return _Chain_Get( the_chain );
400}
401
402/**
403 * @brief See _Chain_Get_unprotected().
404 */
405RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_get_unprotected(
406  rtems_chain_control *the_chain
407)
408{
409  return _Chain_Get_unprotected( the_chain );
410}
411
412/**
413 *  @brief Insert a node on a chain
414 *
415 *  This routine inserts @a the_node on a chain immediately following
416 *  @a after_node. 
417 *
418 *  @note It disables interrupts to ensure the atomicity
419 *  of the extract operation.
420 */
421RTEMS_INLINE_ROUTINE void rtems_chain_insert(
422  rtems_chain_node *after_node,
423  rtems_chain_node *the_node
424)
425{
426  _Chain_Insert( after_node, the_node );
427}
428
429/**
430 * @brief See _Chain_Insert_unprotected().
431 */
432RTEMS_INLINE_ROUTINE void rtems_chain_insert_unprotected(
433  rtems_chain_node *after_node,
434  rtems_chain_node *the_node
435)
436{
437  _Chain_Insert_unprotected( after_node, the_node );
438}
439
440/**
441 *  @brief Append a node on the end of a chain
442 *
443 *  This routine appends @a the_node onto the end of @a the_chain.
444 *
445 *  @note It disables interrupts to ensure the atomicity of the
446 *  append operation.
447 */
448RTEMS_INLINE_ROUTINE void rtems_chain_append(
449  rtems_chain_control *the_chain,
450  rtems_chain_node    *the_node
451)
452{
453  _Chain_Append( the_chain, the_node );
454}
455
456/**
457 *  @brief Append a node on the end of a chain (unprotected)
458 *
459 *  This routine appends @a the_node onto the end of @a the_chain.
460 *
461 *  @note It does NOT disable interrupts to ensure the atomicity of the
462 *  append operation.
463 */
464RTEMS_INLINE_ROUTINE void rtems_chain_append_unprotected(
465  rtems_chain_control *the_chain,
466  rtems_chain_node    *the_node
467)
468{
469  _Chain_Append_unprotected( the_chain, the_node );
470}
471
472/** @brief Prepend a Node
473 *
474 *  This routine prepends the_node onto the front of the_chain.
475 *
476 *  @param[in] the_chain is the chain to be operated upon.
477 *  @param[in] the_node is the node to be prepended.
478 *
479 *  @note It disables interrupts to ensure the atomicity of the
480 *        prepend operation.
481 */
482RTEMS_INLINE_ROUTINE void rtems_chain_prepend(
483  rtems_chain_control *the_chain,
484  rtems_chain_node    *the_node
485)
486{
487  _Chain_Prepend( the_chain, the_node );
488}
489
490/** @brief Prepend a Node (unprotected)
491 *
492 *  This routine prepends the_node onto the front of the_chain.
493 *
494 *  @param[in] the_chain is the chain to be operated upon.
495 *  @param[in] the_node is the node to be prepended.
496 *
497 *  @note It does NOT disable interrupts to ensure the atomicity of the
498 *        prepend operation.
499 */
500RTEMS_INLINE_ROUTINE void rtems_chain_prepend_unprotected(
501  rtems_chain_control *the_chain,
502  rtems_chain_node    *the_node
503)
504{
505  _Chain_Prepend_unprotected( the_chain, the_node );
506}
507
508#endif
509/* end of include file */
Note: See TracBrowser for help on using the repository browser.