1 /*
2  * = = == === ===== ======== ============= =====================
3  * == pt::rde (critcl) - Data Structures - Generic stack
4  */
5 
6 #ifndef _RDE_DS_STACK_H
7 #define _RDE_DS_STACK_H 1
8 
9 #include <util.h> /* Scoping */
10 
11 /*
12  * The stack data structure declared in this file is an array of void*
13  * cells, with each cell either directly containing the data, or being
14  * a pointer to it.
15  *
16  * The structure maintains a max-size field, reallocating the array if
17  * and only if we go over this size. Each allocation doubles the
18  * available room.
19  *
20  * A pointer to a delete function is maintained, to delete cells which
21  * are references to the actual data.
22  */
23 
24 typedef void (*RDE_STACK_CELL_FREE) (void* cell);
25 typedef struct RDE_STACK_* RDE_STACK;
26 
27 static const int RDE_STACK_INITIAL_SIZE = 256;
28 
29 /*
30  * Notes
31  * - push -- Item allocation is responsibility of caller.
32  *           Stack takes ownership of the item.
33  * - pop  -- Stack frees allocated item.
34  * - trim -- Ditto
35  * - top  -- Provides top item, no transfer of ownership.
36  * - del  -- Releases stack, cell array, and items, if any.
37  * - drop -- Like pop, but doesn't free, assumes that caller
38  *           is taking ownership of the pointer.
39  */
40 
41 /* SKIP START */
42 SCOPE RDE_STACK rde_stack_new  (RDE_STACK_CELL_FREE freeCellProc);
43 SCOPE void      rde_stack_del  (RDE_STACK s);
44 
45 SCOPE void*    rde_stack_top  (RDE_STACK s);
46 SCOPE void     rde_stack_push (RDE_STACK s, void* item);
47 SCOPE void     rde_stack_pop  (RDE_STACK s, long int n);
48 SCOPE void     rde_stack_trim (RDE_STACK s, long int n);
49 SCOPE void     rde_stack_drop (RDE_STACK s, long int n);
50 SCOPE void     rde_stack_move (RDE_STACK dst, RDE_STACK src);
51 SCOPE void     rde_stack_get  (RDE_STACK s, long int* cn, void*** cc);
52 SCOPE long int rde_stack_size (RDE_STACK s);
53 /* SKIP END */
54 #endif /* _RDE_DS_STACK_H */
55 
56 /*
57  * Local Variables:
58  * mode: c
59  * c-basic-offset: 4
60  * fill-column: 78
61  * End:
62  */
63