source: rtems/cpukit/sapi/inline/rtems/chain.inl @ 74e8ad7

4.9
Last change on this file since 74e8ad7 was 74e8ad7, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 20, 2008 at 9:11:38 PM

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

PR 1340/cpukit

  • sapi/inline/rtems/chain.inl: Add rtems_chain_initialize to public chain API.
  • Property mode set to 100644
File size: 9.7 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 Is the Chain Node Pointer NULL
78 *
79 *  This function returns true if the_node is NULL and false otherwise.
80 *
81 *  @param[in] the_node is the node pointer to check.
82 *
83 *  @return This method returns true if the_node is NULL and false otherwise.
84 */
85RTEMS_INLINE_ROUTINE bool rtems_chain_is_null_node(
86  const rtems_chain_node *the_node
87)
88{
89  return _Chain_Is_null_node( the_node );
90}
91
92/**
93 *  @brief Return pointer to Chain Head
94 *
95 *  This function returns a pointer to the first node on the chain.
96 *
97 *  @param[in] the_chain is the chain to be operated upon.
98 *
99 *  @return This method returns the permanent head node of the chain.
100 */
101RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_head(
102  rtems_chain_control *the_chain
103)
104{
105  return _Chain_Head( the_chain );
106}
107
108/**
109 *  @brief Return pointer to Chain Tail
110 *
111 *  This function returns a pointer to the last node on the chain.
112 *
113 *  @param[in] the_chain is the chain to be operated upon.
114 *
115 *  @return This method returns the permanent tail node of the chain.
116 */
117RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_tail(
118  rtems_chain_control *the_chain
119)
120{
121  return _Chain_Tail( the_chain );
122}
123
124/**
125 *  @brief Are Two Nodes Equal
126 *
127 *  This function returns true if @a left and @a right are equal,
128 *  and false otherwise.
129 *
130 *  @param[in] left is the node on the left hand side of the comparison.
131 *  @param[in] right is the node on the left hand side of the comparison.
132 *
133 *  @return This function returns true if @a left and @a right are equal,
134 *          and false otherwise.
135 */
136RTEMS_INLINE_ROUTINE bool rtems_chain_are_nodes_equal(
137  const rtems_chain_node *left,
138  const rtems_chain_node *right
139)
140{
141  return _Chain_Are_nodes_equal( left, right );
142}
143
144/**
145 *  @brief Is the Chain Empty
146 *
147 *  This function returns true if there a no nodes on @a the_chain and
148 *  false otherwise.
149 *
150 *  @param[in] the_chain is the chain to be operated upon.
151 *
152 *  @return This function returns true if there a no nodes on @a the_chain and
153 *  false otherwise.
154 */
155RTEMS_INLINE_ROUTINE bool rtems_chain_is_empty(
156  rtems_chain_control *the_chain
157)
158{
159  return _Chain_Is_empty( the_chain );
160}
161
162/**
163 *  @brief Is this the First Node on the Chain
164 *
165 *  This function returns true if the_node is the first node on a chain and
166 *  false otherwise.
167 *
168 *  @param[in] the_node is the node the caller wants to know if it is
169 *             the first node on a chain.
170 *
171 *  @return This function returns true if @a the_node is the first node on
172 *          a chain and false otherwise.
173 */
174RTEMS_INLINE_ROUTINE bool rtems_chain_is_first(
175  const rtems_chain_node *the_node
176)
177{
178  return _Chain_Is_first( the_node );
179}
180
181/**
182 *  @brief Is this the Last Node on the Chain
183 *
184 *  This function returns true if @a the_node is the last node on a chain and
185 *  false otherwise.
186 *
187 *  @param[in] the_node is the node to check as the last node.
188 *
189 *  @return This function returns true if @a the_node is the last node on
190 *          a chain and false otherwise.
191 */
192RTEMS_INLINE_ROUTINE bool rtems_chain_is_last(
193  const rtems_chain_node *the_node
194)
195{
196  return _Chain_Is_last( the_node );
197}
198
199/**
200 *  @brief Does this Chain have only One Node
201 *
202 *  This function returns true if there is only one node on @a the_chain and
203 *  false otherwise.
204 *
205 *  @param[in] the_chain is the chain to be operated upon.
206 *
207 *  @return This function returns true if there is only one node on
208 *          @a the_chain and false otherwise.
209 */
210RTEMS_INLINE_ROUTINE bool rtems_chain_has_only_one_node(
211  const rtems_chain_control *the_chain
212)
213{
214  return _Chain_Has_only_one_node( the_chain );
215}
216
217/**
218 *  @brief Is this Node the Chain Head
219 *
220 *  This function returns true if @a the_node is the head of the_chain and
221 *  false otherwise.
222 *
223 *  @param[in] the_chain is the chain to be operated upon.
224 *  @param[in] the_node is the node to check for being the Chain Head.
225 *
226 *  @return This function returns true if @a the_node is the head of
227 *          @a the_chain and false otherwise.
228 */
229RTEMS_INLINE_ROUTINE bool rtems_chain_is_head(
230  rtems_chain_control    *the_chain,
231  const rtems_chain_node *the_node
232)
233{
234  return _Chain_Is_head( the_chain, the_node );
235}
236
237/**
238 *  @brief Is this Node the Chail Tail
239 *
240 *  This function returns true if the_node is the tail of the_chain and
241 *  false otherwise.
242 *
243 *  @param[in] the_chain is the chain to be operated upon.
244 *  @param[in] the_node is the node to check for being the Chain Tail.
245 */
246RTEMS_INLINE_ROUTINE bool rtems_chain_is_tail(
247  rtems_chain_control    *the_chain,
248  const rtems_chain_node *the_node
249)
250{
251  return _Chain_Is_tail( the_chain, the_node );
252}
253
254/**
255 *  @brief Extract the specified node from a chain
256 *
257 *  This routine extracts @a the_node from the chain on which it resides.
258 *  It disables interrupts to ensure the atomicity of the
259 *  extract operation.
260 *
261 *  @arg the_node specifies the node to extract
262 */
263RTEMS_INLINE_ROUTINE void rtems_chain_extract(
264  rtems_chain_node *the_node
265)
266{
267  _Chain_Extract( the_node );
268}
269
270/**
271 *  @brief Obtain the first node on a chain
272 *
273 *  This function removes the first node from @a the_chain and returns
274 *  a pointer to that node.  If @a the_chain is empty, then NULL is returned.
275 *
276 *  @return This method returns a pointer a node.  If a node was removed,
277 *          then a pointer to that node is returned.  If @a the_chain was
278 *          empty, then NULL is returned.
279 *
280 *  @note It disables interrupts to ensure the atomicity of the get operation.
281 */
282RTEMS_INLINE_ROUTINE rtems_chain_node *rtems_chain_get(
283  rtems_chain_control *the_chain
284)
285{
286  return _Chain_Get( the_chain );
287}
288
289/**
290 *  @brief Insert a node on a chain
291 *
292 *  This routine inserts @a the_node on a chain immediately following
293 *  @a after_node. 
294 *
295 *  @note It disables interrupts to ensure the atomicity
296 *  of the extract operation.
297 */
298RTEMS_INLINE_ROUTINE void rtems_chain_insert(
299  rtems_chain_node *after_node,
300  rtems_chain_node *the_node
301)
302{
303  _Chain_Insert( after_node, the_node );
304}
305
306/**
307 *  @brief Append a node on the end of a chain
308 *
309 *  This routine appends @a the_node onto the end of @a the_chain.
310 *
311 *  @note It disables interrupts to ensure the atomicity of the
312 *  append operation.
313 */
314RTEMS_INLINE_ROUTINE void rtems_chain_append(
315  rtems_chain_control *the_chain,
316  rtems_chain_node    *the_node
317)
318{
319  _Chain_Append( the_chain, the_node );
320}
321
322/**
323 *  @brief Append a node on the end of a chain (unprotected)
324 *
325 *  This routine appends @a the_node onto the end of @a the_chain.
326 *
327 *  @note It does NOT disable interrupts to ensure the atomicity of the
328 *  append operation.
329 */
330RTEMS_INLINE_ROUTINE void rtems_chain_append_unprotected(
331  rtems_chain_control *the_chain,
332  rtems_chain_node    *the_node
333)
334{
335  _Chain_Append_unprotected( the_chain, the_node );
336}
337
338/** @brief Prepend a Node
339 *
340 *  This routine prepends the_node onto the front of the_chain.
341 *
342 *  @param[in] the_chain is the chain to be operated upon.
343 *  @param[in] the_node is the node to be prepended.
344 *
345 *  @note It disables interrupts to ensure the atomicity of the
346 *        prepend operation.
347 */
348RTEMS_INLINE_ROUTINE void rtems_chain_prepend(
349  rtems_chain_control *the_chain,
350  rtems_chain_node    *the_node
351)
352{
353  _Chain_Prepend( the_chain, the_node );
354}
355
356/** @brief Prepend a Node (unprotected)
357 *
358 *  This routine prepends the_node onto the front of the_chain.
359 *
360 *  @param[in] the_chain is the chain to be operated upon.
361 *  @param[in] the_node is the node to be prepended.
362 *
363 *  @note It does NOT disable interrupts to ensure the atomicity of the
364 *        prepend operation.
365 */
366RTEMS_INLINE_ROUTINE void rtems_chain_prepend_unprotected(
367  rtems_chain_control *the_chain,
368  rtems_chain_node    *the_node
369)
370{
371  _Chain_Prepend_unprotected( the_chain, the_node );
372}
373
374#endif
375/* end of include file */
Note: See TracBrowser for help on using the repository browser.