source: rtems/cpukit/score/include/rtems/score/chain.h @ 11874561

4.104.114.84.95
Last change on this file since 11874561 was 11874561, checked in by Ralf Corsepius <ralf.corsepius@…>, on Nov 21, 2004 at 7:17:38 AM

Adjust doxygen @file.

  • Property mode set to 100644
File size: 4.9 KB
Line 
1/**
2 *  @file  rtems/score/chain.h
3 *
4 *  This include file contains all the constants and structures associated
5 *  with the Doubly-Linked Chain Handler.
6 */
7
8/*
9 *  COPYRIGHT (c) 1989-2004.
10 *  On-Line Applications Research Corporation (OAR).
11 *
12 *  The license and distribution terms for this file may be
13 *  found in the file LICENSE in this distribution or at
14 *  http://www.rtems.com/license/LICENSE.
15 *
16 *  $Id$
17 */
18
19#ifndef __RTEMS_CHAIN_h
20#define __RTEMS_CHAIN_h
21
22/**
23 *  @defgroup ScoreChain Chain Handler
24 *
25 *  The Chain Handler contains XXX
26 */
27/**@{*/
28
29#ifdef __cplusplus
30extern "C" {
31#endif
32
33#include <rtems/score/address.h>
34
35/**
36 *  @typedef Chain_Node
37 *
38 *  This type definition promotes the name for the Chain Node used by
39 *  all RTEMS code.  It is a separate type definition because a forward
40 *  reference is required to define it.
41 */
42typedef struct Chain_Node_struct Chain_Node;
43
44/**
45 *  @struct Chain_Node_struct
46 *
47 *  This is used to manage each element (node) which is placed
48 *  on a chain.
49 *
50 *  @note Typically, a more complicated structure will use the
51 *        chain package.  The more complicated structure will
52 *        include a chain node as the first element in its
53 *        control structure.  It will then call the chain package
54 *        with a pointer to that node element.  The node pointer
55 *        and the higher level structure start at the same address
56 *        so the user can cast the pointers back and forth.
57 *
58 */
59struct Chain_Node_struct {
60  /** This points to the node after to this one on this chain. */
61  Chain_Node *next;
62  /** This points to the node immediate prior to this one on this chain. */
63  Chain_Node *previous;
64};
65
66/**
67 *  @struct Chain_Control
68 *
69 * This is used to manage a chain.  A chain consists of a doubly
70 * linked list of zero or more nodes.
71 *
72 * @note This implementation does not require special checks for
73 *   manipulating the first and last elements on the chain.
74 *   To accomplish this the @a Chain_Control structure is
75 *   treated as two overlapping @ref Chain_Node structures.
76 *   The permanent head of the chain overlays a node structure on the
77 *   @a first and @a permanent_null fields.  The permanent tail
78 *   of the chain overlays a node structure on the
79 *   @a permanent_null and @a last elements of the structure.
80 *
81 */
82typedef struct {
83  /** This points to the first node on this chain. */
84  Chain_Node *first;
85  /** This field is always 0. */
86  Chain_Node *permanent_null;
87  /** This points to the last node on this chain. */
88  Chain_Node *last;
89} Chain_Control;
90
91/**
92 *  @brief Initialize a Chain Header
93 *
94 *  This routine initializes @a the_chain structure to manage the
95 *  contiguous array of @a number_nodes nodes which starts at
96 *  @a starting_address.  Each node is of @a node_size bytes.
97 *
98 *  @param the_chain (in) specifies the chain to initialize
99 *  @param starting_address (in) is the starting address of the array
100 *         of elements
101 *  @param number_nodes (in) is the numebr of nodes that will be in the chain
102 *  @param node_size (in) is the size of each node
103 */
104void _Chain_Initialize(
105  Chain_Control *the_chain,
106  void          *starting_address,
107  unsigned32     number_nodes,
108  unsigned32     node_size
109);
110
111#ifndef RTEMS_INLINES
112/**
113 *  @brief Get the first node (do not disable interrupts)
114 *
115 *  This method attempts to obtain the first node from \a the_chain.
116 *
117 *  @param the_chain (in) points to the chain to operate upon
118 *  @return If successful, a chain node is returned.  Otherwise, NULL
119 *  is returned.
120 */
121Chain_Node *_Chain_Get_first_unprotected(
122  Chain_Control *the_chain
123);
124#endif
125
126/**
127 *  @brief Extract the specified node from a chain
128 *
129 *  This routine extracts \a the_node from the chain on which it resides.
130 *  It disables interrupts to insure the atomicity of the
131 *  extract operation.
132 *
133 *  @arg the_node specifies the node to extract
134 */
135void _Chain_Extract(
136  Chain_Node *the_node
137);
138
139/**
140 *  @brief Obtain the first node on a chain
141 *
142 *  This function removes the first node from \a the_chain and returns
143 *  a pointer to that node.  If \a the_chain is empty, then NULL is returned.
144 *
145 *  @note It disables interrupts to insure the atomicity of the
146 *  get operation.
147 */
148Chain_Node *_Chain_Get(
149  Chain_Control *the_chain
150);
151
152/**
153 *  @brief Insert a node on a chain
154 *
155 *  This routine inserts \a the_node on a chain immediately following
156 *  \a after_node. 
157 *
158 *  @note It disables interrupts to insure the atomicity
159 *  of the extract operation.
160 */
161void _Chain_Insert(
162  Chain_Node *after_node,
163  Chain_Node *the_node
164);
165
166/**
167 *  @brief Append a node on the end of a chain
168 *
169 *  This routine appends \a the_node onto the end of \a the_chain.
170 *
171 *  @note It disables interrupts to insure the atomicity of the
172 *  append operation.
173 */
174void _Chain_Append(
175  Chain_Control *the_chain,
176  Chain_Node    *the_node
177);
178
179#ifndef __RTEMS_APPLICATION__
180#include <rtems/score/chain.inl>
181#endif
182
183#ifdef __cplusplus
184}
185#endif
186
187/**@}*/
188
189#endif
190/* end of include file */
Note: See TracBrowser for help on using the repository browser.