1 | @c |
---|
2 | @c COPYRIGHT (c) 1988-2008. |
---|
3 | @c On-Line Applications Research Corporation (OAR). |
---|
4 | @c All rights reserved. |
---|
5 | @c |
---|
6 | @c $Id$ |
---|
7 | @c |
---|
8 | |
---|
9 | @chapter Chains |
---|
10 | |
---|
11 | @cindex chains |
---|
12 | |
---|
13 | @section Introduction |
---|
14 | |
---|
15 | The Chains API is an interface to the Super Core (score) chain |
---|
16 | implementation. The Super Core uses chains for all list type |
---|
17 | functions. This includes wait queues and task queues. The Chains API |
---|
18 | provided by RTEMS is: |
---|
19 | |
---|
20 | @itemize @bullet |
---|
21 | @c build_id |
---|
22 | @item @code{@value{DIRPREFIX}chain_node} - Chain node used in user objects |
---|
23 | @item @code{@value{DIRPREFIX}chain_control} - Chain control node |
---|
24 | @item @code{@value{DIRPREFIX}chain_initialize_empty} - initialize the chain as empty |
---|
25 | @item @code{@value{DIRPREFIX}chain_is_null_node} - Is the node NULL ? |
---|
26 | @item @code{@value{DIRPREFIX}chain_head} - Return the chain's head |
---|
27 | @item @code{@value{DIRPREFIX}chain_tail} - Return the chain's tail |
---|
28 | @item @code{@value{DIRPREFIX}chain_are_nodes_equal} - Are the node's equal ? |
---|
29 | @item @code{@value{DIRPREFIX}chain_is_empty} - Is the chain empty ? |
---|
30 | @item @code{@value{DIRPREFIX}chain_is_first} - Is the Node the first in the chain ? |
---|
31 | @item @code{@value{DIRPREFIX}chain_is_last} - Is the Node the last in the chain ? |
---|
32 | @item @code{@value{DIRPREFIX}chain_has_only_one_node} - Does the node have one node ? |
---|
33 | @item @code{@value{DIRPREFIX}chain_is_head} - Is the node the head ? |
---|
34 | @item @code{@value{DIRPREFIX}chain_is_tail} - Is the node the tail ? |
---|
35 | @item @code{@value{DIRPREFIX}chain_extract} - Extract the node from the chain ? |
---|
36 | @item @code{@value{DIRPREFIX}chain_get} - Return the first node on the chain ? |
---|
37 | @item @code{@value{DIRPREFIX}chain_insert} - Insert the node into the chain ? |
---|
38 | @item @code{@value{DIRPREFIX}chain_append} - Append the node to chain ? |
---|
39 | @item @code{@value{DIRPREFIX}chain_prepend} - Prepend the node to the end of the chain ? |
---|
40 | @end itemize |
---|
41 | |
---|
42 | @section Background |
---|
43 | |
---|
44 | The Chains API maps to the Super Core Chains API. Chains are |
---|
45 | implemented as a double linked list of nodes anchored to a control |
---|
46 | node. The list starts at the control node and is terminated at the |
---|
47 | control node. A node has previous and next pointers. Being a double |
---|
48 | linked list nodes can be inserted and removed without the need to |
---|
49 | travse the chain. |
---|
50 | |
---|
51 | Chains have a small memory footprint and can be used in interrupt |
---|
52 | service routines and are thread safe in a multi-threaded |
---|
53 | environment. The directives list which operations disable interrupts. |
---|
54 | |
---|
55 | Chains are very useful in Board Support packages and applications. |
---|
56 | |
---|
57 | @subsection Nodes |
---|
58 | |
---|
59 | A chain is made up from nodes that orginate from a chain control |
---|
60 | object. A node is of type @code{@value{DIRPREFIX}chain_node}. The node |
---|
61 | is designed to be part of a user data structure and a cast is used to |
---|
62 | move from the node address to the user data structure address. For |
---|
63 | example: |
---|
64 | |
---|
65 | @example |
---|
66 | typedef struct foo |
---|
67 | @{ |
---|
68 | @value{DIRPREFIX}chain_node node; |
---|
69 | int bar; |
---|
70 | @} foo; |
---|
71 | @end example |
---|
72 | |
---|
73 | creates a type @code{foo} that can be placed on a chain. To get the |
---|
74 | foo structure from the list you perform the following: |
---|
75 | |
---|
76 | @example |
---|
77 | foo* get_foo(@value{DIRPREFIX}chain_control* control) |
---|
78 | @{ |
---|
79 | return (foo*) @value{DIRPREFIX}chain_get(control); |
---|
80 | @} |
---|
81 | @end example |
---|
82 | |
---|
83 | The node is placed at the start of the user's structure to allow the |
---|
84 | node address on the chain to be easly cast to the user's structure |
---|
85 | address. |
---|
86 | |
---|
87 | @subsection Controls |
---|
88 | |
---|
89 | A chain is anchored with a control object. Chain control provide the |
---|
90 | user with access to the nodes on the chain. The control is head of the |
---|
91 | node. |
---|
92 | |
---|
93 | |
---|
94 | @example |
---|
95 | Control |
---|
96 | next -------------------------> |
---|
97 | permanent_null <--------------- NODE |
---|
98 | last -------------------------> |
---|
99 | @end example |
---|
100 | |
---|
101 | The implementation does not require special checks for manipulating |
---|
102 | the first and last nodes on the chain. To accomplish this the |
---|
103 | @code{@value{DIRPREFIX}chain_control} structure is treated as two |
---|
104 | overlapping @code{@value{DIRPREFIX}chain_node} structures. The |
---|
105 | permanent head of the chain overlays a node structure on the first and |
---|
106 | @code{permanent_null} fields. The @code{permanent_tail} of the chain |
---|
107 | overlays a node structure on the @code{permanent_null} and @code{last} |
---|
108 | elements of the structure. |
---|
109 | |
---|
110 | @section Operations |
---|
111 | |
---|
112 | @subsection Multi-threading |
---|
113 | |
---|
114 | Chains are designed to be used in a multi-threading environment. The |
---|
115 | directives list which operations mask interrupts. Chains supports |
---|
116 | tasks and interrupt service routines appending and extracting nodes |
---|
117 | with out the need for extra locks. Chains how-ever cannot insure the |
---|
118 | integrity of a chain for all operations. This is the responsibility of |
---|
119 | the user. For example an interrupt service routine extracting nodes |
---|
120 | while a task is iterating over the chain can have unpredictable |
---|
121 | results. |
---|
122 | |
---|
123 | @subsection Creating a Chain |
---|
124 | |
---|
125 | To create a chain you need to declare a chain control then add nodes |
---|
126 | to the control. Consider a user structure and chain control: |
---|
127 | |
---|
128 | @example |
---|
129 | typedef struct foo |
---|
130 | @{ |
---|
131 | @value{DIRPREFIX}chain_node node; |
---|
132 | uint8_t char* data; |
---|
133 | @} foo; |
---|
134 | |
---|
135 | @value{DIRPREFIX}chain_control chain; |
---|
136 | @end example |
---|
137 | |
---|
138 | Add nodes with the following code: |
---|
139 | |
---|
140 | @example |
---|
141 | @value{DIRPREFIX}chain_initialize_empty (&chain); |
---|
142 | |
---|
143 | for (i = 0; i < count; i++) |
---|
144 | @{ |
---|
145 | foo* bar = malloc (sizeof (foo)); |
---|
146 | if (!foo) |
---|
147 | return -1; |
---|
148 | bar->data = malloc (size); |
---|
149 | @value{DIRPREFIX}chain_append (&chain, &bar->node); |
---|
150 | @} |
---|
151 | @end example |
---|
152 | |
---|
153 | The chain is initialized and the nodes allocated and appended to the |
---|
154 | chain. This is an example of a pool of buffers. |
---|
155 | |
---|
156 | @subsection Iterating a Chain |
---|
157 | |
---|
158 | @cindex chain iterate |
---|
159 | |
---|
160 | Iterating a chain is a common function. The example shows how to |
---|
161 | iterate the buffer pool chain created in the last section to find |
---|
162 | buffers starting with a specific string. If the buffer is located it is |
---|
163 | extracted from the chain and placed on another chain: |
---|
164 | |
---|
165 | @example |
---|
166 | void foobar (const char* match, |
---|
167 | @value{DIRPREFIX}chain_control* chain, |
---|
168 | @value{DIRPREFIX}chain_control* out) |
---|
169 | @{ |
---|
170 | @value{DIRPREFIX}chain_node* node; |
---|
171 | foo* bar; |
---|
172 | |
---|
173 | @value{DIRPREFIX}chain_initialize_empty (out); |
---|
174 | |
---|
175 | node = chain->first; |
---|
176 | |
---|
177 | while (!@value{DIRPREFIX}chain_is_tail (chain, node)) |
---|
178 | @{ |
---|
179 | bar = (foo*) node; |
---|
180 | |
---|
181 | if (strcmp (match, bar->data) == 0) |
---|
182 | @{ |
---|
183 | @value{DIRPREFIX}chain_node* next_node = node->next; |
---|
184 | @value{DIRPREFIX}chain_extract (node); |
---|
185 | @value{DIRPREFIX}chain_append (out, node); |
---|
186 | node = next_node; |
---|
187 | @} |
---|
188 | @} |
---|
189 | @} |
---|
190 | @end example |
---|
191 | |
---|
192 | @section Directives |
---|
193 | |
---|
194 | The section details the Chains directives. |
---|
195 | |
---|
196 | @c |
---|
197 | @c Initialize this Chain as Empty |
---|
198 | @c |
---|
199 | @page |
---|
200 | @subsection Initialise Empty |
---|
201 | |
---|
202 | @cindex chain initialise empty |
---|
203 | |
---|
204 | @subheading CALLING SEQUENCE: |
---|
205 | |
---|
206 | @ifset is-C |
---|
207 | @findex @value{DIRPREFIX}chain_initialize_empty |
---|
208 | @example |
---|
209 | void @value{DIRPREFIX}chain_initialize_empty( |
---|
210 | @value{DIRPREFIX}chain_control *the_chain |
---|
211 | ); |
---|
212 | @end example |
---|
213 | @end ifset |
---|
214 | |
---|
215 | @subheading RETURNS |
---|
216 | |
---|
217 | Returns nothing. |
---|
218 | |
---|
219 | @subheading DESCRIPTION: |
---|
220 | |
---|
221 | This function take in a pointer to a chain control and initializes it |
---|
222 | to empty. |
---|
223 | |
---|
224 | @subheading NOTES: |
---|
225 | |
---|
226 | This call will discard any nodes on the chain. |
---|
227 | |
---|
228 | @c |
---|
229 | @c |
---|
230 | @c |
---|
231 | @page |
---|
232 | @subsection Is Null Node ? |
---|
233 | |
---|
234 | @cindex chain is node null |
---|
235 | |
---|
236 | @subheading CALLING SEQUENCE: |
---|
237 | |
---|
238 | @ifset is-C |
---|
239 | @findex @value{DIRPREFIX}chain_is_null_node |
---|
240 | @example |
---|
241 | bool @value{DIRPREFIX}chain_is_null_node( |
---|
242 | const @value{DIRPREFIX}chain_node *the_node |
---|
243 | ); |
---|
244 | @end example |
---|
245 | @end ifset |
---|
246 | |
---|
247 | @subheading RETURNS |
---|
248 | |
---|
249 | Returns true is the node point is NULL and false if the node is not |
---|
250 | NULL. |
---|
251 | |
---|
252 | @subheading DESCRIPTION: |
---|
253 | |
---|
254 | Tests the node to see if it is a NULL returning true if a null. |
---|
255 | |
---|
256 | @c |
---|
257 | @c |
---|
258 | @c |
---|
259 | @page |
---|
260 | @subsection Head |
---|
261 | |
---|
262 | @cindex chain get head |
---|
263 | |
---|
264 | @subheading CALLING SEQUENCE: |
---|
265 | |
---|
266 | @ifset is-C |
---|
267 | @findex @value{DIRPREFIX}chain_head |
---|
268 | @example |
---|
269 | @value{DIRPREFIX}chain_node *@value{DIRPREFIX}chain_head( |
---|
270 | @value{DIRPREFIX}chain_control *the_chain |
---|
271 | ) |
---|
272 | @end example |
---|
273 | @end ifset |
---|
274 | |
---|
275 | @subheading RETURNS |
---|
276 | |
---|
277 | Returns the permanent head node of the chain. |
---|
278 | |
---|
279 | @subheading DESCRIPTION: |
---|
280 | |
---|
281 | This function returns a pointer to the first node on the chain. |
---|
282 | |
---|
283 | @c |
---|
284 | @c |
---|
285 | @c |
---|
286 | @page |
---|
287 | @subsection Tail |
---|
288 | |
---|
289 | @cindex chain get tail |
---|
290 | |
---|
291 | @subheading CALLING SEQUENCE: |
---|
292 | |
---|
293 | @ifset is-C |
---|
294 | @findex @value{DIRPREFIX}chain_tail |
---|
295 | @example |
---|
296 | @value{DIRPREFIX}chain_node *@value{DIRPREFIX}chain_tail( |
---|
297 | @value{DIRPREFIX}chain_control *the_chain |
---|
298 | ); |
---|
299 | @end example |
---|
300 | @end ifset |
---|
301 | |
---|
302 | @subheading RETURNS |
---|
303 | |
---|
304 | Returns the permanent tail node of the chain. |
---|
305 | |
---|
306 | @subheading DESCRIPTION: |
---|
307 | |
---|
308 | This function returns a pointer to the last node on the chain. |
---|
309 | |
---|
310 | @c |
---|
311 | @c |
---|
312 | @c |
---|
313 | @page |
---|
314 | @subsection Are Two Nodes Equal ? |
---|
315 | |
---|
316 | @cindex chare are nodes equal |
---|
317 | |
---|
318 | @subheading CALLING SEQUENCE: |
---|
319 | |
---|
320 | @ifset is-C |
---|
321 | @findex @value{DIRPREFIX}chain_are_nodes_equal |
---|
322 | @example |
---|
323 | bool @value{DIRPREFIX}chain_are_nodes_equal( |
---|
324 | const @value{DIRPREFIX}chain_node *left, |
---|
325 | const @value{DIRPREFIX}chain_node *right |
---|
326 | ); |
---|
327 | @end example |
---|
328 | @end ifset |
---|
329 | |
---|
330 | @subheading RETURNS |
---|
331 | |
---|
332 | This function returns true if the left node and the right node are |
---|
333 | equal, and false otherwise. |
---|
334 | |
---|
335 | @subheading DESCRIPTION: |
---|
336 | |
---|
337 | This function returns true if the left node and the right node are |
---|
338 | equal, and false otherwise. |
---|
339 | |
---|
340 | @c |
---|
341 | @c |
---|
342 | @c |
---|
343 | @page |
---|
344 | @subsection Is the Chain Empty |
---|
345 | |
---|
346 | @cindex chain is chain empty |
---|
347 | |
---|
348 | @subheading CALLING SEQUENCE: |
---|
349 | |
---|
350 | @ifset is-C |
---|
351 | @findex @value{DIRPREFIX}chain_is_empty |
---|
352 | @example |
---|
353 | bool @value{DIRPREFIX}chain_is_empty( |
---|
354 | @value{DIRPREFIX}chain_control *the_chain |
---|
355 | ); |
---|
356 | @end example |
---|
357 | @end ifset |
---|
358 | |
---|
359 | @subheading RETURNS |
---|
360 | |
---|
361 | This function returns true if there a no nodes on the chain and false |
---|
362 | otherwise. |
---|
363 | |
---|
364 | @subheading DESCRIPTION: |
---|
365 | |
---|
366 | This function returns true if there a no nodes on the chain and false |
---|
367 | otherwise. |
---|
368 | |
---|
369 | @c |
---|
370 | @c |
---|
371 | @c |
---|
372 | @page |
---|
373 | @subsection Is this the First Node on the Chain ? |
---|
374 | |
---|
375 | @cindex chain is node the first |
---|
376 | |
---|
377 | @subheading CALLING SEQUENCE: |
---|
378 | |
---|
379 | @ifset is-C |
---|
380 | @findex @value{DIRPREFIX}chain_is_first |
---|
381 | @example |
---|
382 | bool @value{DIRPREFIX}chain_is_first( |
---|
383 | const @value{DIRPREFIX}chain_node *the_node |
---|
384 | ); |
---|
385 | @end example |
---|
386 | @end ifset |
---|
387 | |
---|
388 | @subheading RETURNS |
---|
389 | |
---|
390 | This function returns true if the node is the first node on a chain |
---|
391 | and false otherwise. |
---|
392 | |
---|
393 | @subheading DESCRIPTION: |
---|
394 | |
---|
395 | This function returns true if the node is the first node on a chain |
---|
396 | and false otherwise. |
---|
397 | |
---|
398 | @c |
---|
399 | @c |
---|
400 | @c |
---|
401 | @page |
---|
402 | @subsection Is this the Last Node on the Chain ? |
---|
403 | |
---|
404 | @cindex chain is node the last |
---|
405 | |
---|
406 | @subheading CALLING SEQUENCE: |
---|
407 | |
---|
408 | @ifset is-C |
---|
409 | @findex @value{DIRPREFIX}chain_is_last |
---|
410 | @example |
---|
411 | bool @value{DIRPREFIX}chain_is_last( |
---|
412 | const @value{DIRPREFIX}chain_node *the_node |
---|
413 | ); |
---|
414 | @end example |
---|
415 | @end ifset |
---|
416 | |
---|
417 | @subheading RETURNS |
---|
418 | |
---|
419 | This function returns true if the node is the last node on a chain and |
---|
420 | false otherwise. |
---|
421 | |
---|
422 | @subheading DESCRIPTION: |
---|
423 | |
---|
424 | This function returns true if the node is the last node on a chain and |
---|
425 | false otherwise. |
---|
426 | |
---|
427 | @c |
---|
428 | @c |
---|
429 | @c |
---|
430 | @page |
---|
431 | @subsection Does this Chain have only One Node ? |
---|
432 | |
---|
433 | @cindex chain only one node |
---|
434 | |
---|
435 | @subheading CALLING SEQUENCE: |
---|
436 | |
---|
437 | @ifset is-C |
---|
438 | @findex @value{DIRPREFIX}chain_has_only_one_node |
---|
439 | @example |
---|
440 | bool @value{DIRPREFIX}chain_has_only_one_node( |
---|
441 | const @value{DIRPREFIX}chain_control *the_chain |
---|
442 | ); |
---|
443 | @end example |
---|
444 | @end ifset |
---|
445 | |
---|
446 | @subheading RETURNS |
---|
447 | |
---|
448 | This function returns true if there is only one node on the chain and |
---|
449 | false otherwise. |
---|
450 | |
---|
451 | @subheading DESCRIPTION: |
---|
452 | |
---|
453 | This function returns true if there is only one node on the chain and |
---|
454 | false otherwise. |
---|
455 | |
---|
456 | @c |
---|
457 | @c |
---|
458 | @c |
---|
459 | @page |
---|
460 | @subsection Is this Node the Chain Head ? |
---|
461 | |
---|
462 | @cindex chain is node the head |
---|
463 | |
---|
464 | @subheading CALLING SEQUENCE: |
---|
465 | |
---|
466 | @ifset is-C |
---|
467 | @findex @value{DIRPREFIX}chain_is_head |
---|
468 | @example |
---|
469 | bool @value{DIRPREFIX}chain_is_head( |
---|
470 | @value{DIRPREFIX}chain_control *the_chain, |
---|
471 | @value{DIRPREFIX}const chain_node *the_node |
---|
472 | ); |
---|
473 | @end example |
---|
474 | @end ifset |
---|
475 | |
---|
476 | @subheading RETURNS |
---|
477 | |
---|
478 | This function returns true if the node is the head of the chain and |
---|
479 | false otherwise. |
---|
480 | |
---|
481 | @subheading DESCRIPTION: |
---|
482 | |
---|
483 | This function returns true if the node is the head of the chain and |
---|
484 | false otherwise. |
---|
485 | |
---|
486 | @c |
---|
487 | @c |
---|
488 | @c |
---|
489 | @page |
---|
490 | @subsection Is this Node the Chain Tail ? |
---|
491 | |
---|
492 | @cindex chain is node the tail |
---|
493 | |
---|
494 | @subheading CALLING SEQUENCE: |
---|
495 | |
---|
496 | @ifset is-C |
---|
497 | @findex @value{DIRPREFIX}chain_is_tail |
---|
498 | @example |
---|
499 | bool @value{DIRPREFIX}chain_is_tail( |
---|
500 | @value{DIRPREFIX}chain_control *the_chain, |
---|
501 | const @value{DIRPREFIX}chain_node *the_node |
---|
502 | ) |
---|
503 | @end example |
---|
504 | @end ifset |
---|
505 | |
---|
506 | @subheading RETURNS |
---|
507 | |
---|
508 | This function returns true if the node is the tail of the chain and |
---|
509 | false otherwise. |
---|
510 | |
---|
511 | @subheading DESCRIPTION: |
---|
512 | |
---|
513 | This function returns true if the node is the tail of the chain and |
---|
514 | false otherwise. |
---|
515 | |
---|
516 | @c |
---|
517 | @c |
---|
518 | @c |
---|
519 | @page |
---|
520 | @subsection Extract a Node |
---|
521 | |
---|
522 | @cindex chain extract a node |
---|
523 | |
---|
524 | @subheading CALLING SEQUENCE: |
---|
525 | |
---|
526 | @ifset is-C |
---|
527 | @findex @value{DIRPREFIX}chain_extract |
---|
528 | @example |
---|
529 | void @value{DIRPREFIX}chain_extract( |
---|
530 | @value{DIRPREFIX}chain_node *the_node |
---|
531 | ); |
---|
532 | @end example |
---|
533 | @end ifset |
---|
534 | |
---|
535 | @subheading RETURNS |
---|
536 | |
---|
537 | Returns nothing. |
---|
538 | |
---|
539 | @subheading DESCRIPTION: |
---|
540 | |
---|
541 | This routine extracts the node from the chain on which it resides. |
---|
542 | |
---|
543 | @subheading NOTES: |
---|
544 | |
---|
545 | Interrupts are disabled while extracting the node to ensure the |
---|
546 | atomicity of the operation. |
---|
547 | |
---|
548 | @c |
---|
549 | @c |
---|
550 | @c |
---|
551 | @page |
---|
552 | @subsection Get the First Node |
---|
553 | |
---|
554 | @cindex chain get first node |
---|
555 | |
---|
556 | @subheading CALLING SEQUENCE: |
---|
557 | |
---|
558 | @ifset is-C |
---|
559 | @findex @value{DIRPREFIX}chain_get |
---|
560 | @example |
---|
561 | @value{DIRPREFIX}chain_node *@value{DIRPREFIX}chain_get( |
---|
562 | @value{DIRPREFIX}chain_control *the_chain |
---|
563 | ); |
---|
564 | @end example |
---|
565 | @end ifset |
---|
566 | |
---|
567 | @subheading RETURNS |
---|
568 | |
---|
569 | Returns a pointer a node. If a node was removed, then a pointer to |
---|
570 | that node is returned. If the chain was empty, then NULL is |
---|
571 | returned. |
---|
572 | |
---|
573 | @subheading DESCRIPTION: |
---|
574 | |
---|
575 | This function removes the first node from the chain and returns a |
---|
576 | pointer to that node. If the chain is empty, then NULL is returned. |
---|
577 | |
---|
578 | @subheading NOTES: |
---|
579 | |
---|
580 | Interrupts are disabled while obtaining the node to ensure the |
---|
581 | atomicity of the operation. |
---|
582 | |
---|
583 | @c |
---|
584 | @c |
---|
585 | @c |
---|
586 | @page |
---|
587 | @subsection Insert a Node |
---|
588 | |
---|
589 | @cindex chain insert a node |
---|
590 | |
---|
591 | @subheading CALLING SEQUENCE: |
---|
592 | |
---|
593 | @ifset is-C |
---|
594 | @findex @value{DIRPREFIX}chain_insert |
---|
595 | @example |
---|
596 | void @value{DIRPREFIX}chain_insert( |
---|
597 | @value{DIRPREFIX}chain_node *after_node, |
---|
598 | @value{DIRPREFIX}chain_node *the_node |
---|
599 | ); |
---|
600 | @end example |
---|
601 | @end ifset |
---|
602 | |
---|
603 | @subheading RETURNS |
---|
604 | |
---|
605 | Returns nothing. |
---|
606 | |
---|
607 | @subheading DESCRIPTION: |
---|
608 | |
---|
609 | This routine inserts a node on a chain immediately following the |
---|
610 | specified node. |
---|
611 | |
---|
612 | @subheading NOTES: |
---|
613 | |
---|
614 | Interrupts are disabled during the insert to ensure the atomicity of |
---|
615 | the operation. |
---|
616 | |
---|
617 | @c |
---|
618 | @c |
---|
619 | @c |
---|
620 | @page |
---|
621 | @subsection Append a Node |
---|
622 | |
---|
623 | @cindex chain append a node |
---|
624 | |
---|
625 | @subheading CALLING SEQUENCE: |
---|
626 | |
---|
627 | @ifset is-C |
---|
628 | @findex @value{DIRPREFIX}chain_append |
---|
629 | @example |
---|
630 | void @value{DIRPREFIX}chain_append( |
---|
631 | @value{DIRPREFIX}chain_control *the_chain, |
---|
632 | @value{DIRPREFIX}chain_node *the_node |
---|
633 | ); |
---|
634 | @end example |
---|
635 | @end ifset |
---|
636 | |
---|
637 | @subheading RETURNS |
---|
638 | |
---|
639 | Returns nothing. |
---|
640 | |
---|
641 | @subheading DESCRIPTION: |
---|
642 | |
---|
643 | This routine appends a node to the end of a chain. |
---|
644 | |
---|
645 | @subheading NOTES: |
---|
646 | |
---|
647 | Interrupts are disabled during the append to ensure the atomicity of |
---|
648 | the operation. |
---|
649 | |
---|
650 | @c |
---|
651 | @c |
---|
652 | @c |
---|
653 | @page |
---|
654 | @subsection Prepend a Node |
---|
655 | |
---|
656 | @cindex prepend node |
---|
657 | |
---|
658 | @subheading CALLING SEQUENCE: |
---|
659 | |
---|
660 | @ifset is-C |
---|
661 | @findex @value{DIRPREFIX}chain_prepend |
---|
662 | @example |
---|
663 | void @value{DIRPREFIX}chain_prepend( |
---|
664 | @value{DIRPREFIX}chain_control *the_chain, |
---|
665 | @value{DIRPREFIX}chain_node *the_node |
---|
666 | ); |
---|
667 | @end example |
---|
668 | @end ifset |
---|
669 | |
---|
670 | @subheading RETURNS |
---|
671 | |
---|
672 | Returns nothing. |
---|
673 | |
---|
674 | @subheading DESCRIPTION: |
---|
675 | |
---|
676 | This routine prepends a node to the front of the chain. |
---|
677 | |
---|
678 | @subheading NOTES: |
---|
679 | |
---|
680 | Interrupts are disabled during the prepend to ensure the atomicity of |
---|
681 | the operation. |
---|