source: rtems/cpukit/sapi/inline/rtems/chain.inl @ 69f2a07

4.11
Last change on this file since 69f2a07 was 69f2a07, checked in by Sebastian Huber <sebastian.huber@…>, on Aug 24, 2010 at 2:29:55 PM

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

PR 1673/cpukit

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