1 /*  ChvList.h  */
2 
3 #include "../Chv.h"
4 #include "../Lock.h"
5 
6 /*--------------------------------------------------------------------*/
7 /*
8    --------------------------------------------------------------------
9    this object handles a list of lists of Chv objects
10 
11    nlist  -- # of lists
12    heads  -- heads[ilist] contains a pointer
13              to the first Chv object in list ilist
14    counts -- when not-NULL, counts[ilist] contains the remaining number
15              of objects to be added to list ilist before it is complete
16    lock   -- mutex object, can be NULL
17    flags  -- when not NULL, a vector to specify when a list needs
18              to be locked before adding an object to it.
19       flags[ilist] = 'N' --> no need to lock
20       flags[ilist] = 'Y' --> must lock
21    nlocks -- number of times the list was locked
22    --------------------------------------------------------------------
23 */
24 typedef struct _ChvList   ChvList ;
25 struct _ChvList {
26    int       nlist   ;
27    Chv       **heads ;
28    int       *counts ;
29    Lock      *lock   ;
30    char      *flags  ;
31    int       nlocks  ;
32 } ;
33 /*--------------------------------------------------------------------*/
34 /*
35 ------------------------------------------------------------------------
36 ----- methods found in basics.c ----------------------------------------
37 ------------------------------------------------------------------------
38 */
39 /*
40    -----------------------
41    simplest constructor
42 
43    created -- 98may02, cca
44    -----------------------
45 */
46 ChvList *
47 ChvList_new (
48    void
49 ) ;
50 /*
51    -----------------------
52    set the default fields
53 
54    created -- 98may02, cca
55    -----------------------
56 */
57 void
58 ChvList_setDefaultFields (
59    ChvList   *chvlist
60 ) ;
61 /*
62    --------------------------------------------------
63    clear the data fields, releasing allocated storage
64 
65    created -- 98may02, cca
66    --------------------------------------------------
67 */
68 void
69 ChvList_clearData (
70    ChvList   *chvlist
71 ) ;
72 /*
73    ------------------------------------------
74    destructor, free's the object and its data
75 
76    created -- 98may02, cca
77    ------------------------------------------
78 */
79 void
80 ChvList_free (
81    ChvList   *chvlist
82 ) ;
83 
84 /*--------------------------------------------------------------------*/
85 /*
86 ------------------------------------------------------------------------
87 ----- methods found in init.c ------------------------------------------
88 ------------------------------------------------------------------------
89 */
90 /*
91    ------------------------------------------------------------------
92    purpose -- basic initializer
93 
94    nlist  -- number of lists to be held by this object
95    counts -- vector that contains number of items expected
96              for each list.
97       counts == NULL --> unknown number of items expected
98       counts != NULL --> known number of items expected
99    lockflag -- flag to specify lock status
100       lockflag = 0 --> mutex lock is not allocated or initialized
101       lockflag = 1 --> mutex lock is allocated and it can synchronize
102                        only threads in this process.
103       lockflag = 2 --> mutex lock is allocated and it can synchronize
104                        threads in this and other processes.
105    flags -- vector to specify whether to lock individual lists
106       flags == NULL --> none or all lists must be locked,
107                         use lockflag to determine
108       flags[ilist] = 'N' --> no need to lock list ilist
109       flags[ilist] = 'Y' --> must lock list ilist
110 
111    created -- 98may02, cca
112    ------------------------------------------------------------------
113 */
114 void
115 ChvList_init (
116    ChvList   *chvlist,
117    int       nlist,
118    int       counts[],
119    int       lockflag,
120    char      flags[]
121 ) ;
122 /*--------------------------------------------------------------------*/
123 /*
124 ------------------------------------------------------------------------
125 ----- methods found in IO.c --------------------------------------------
126 ------------------------------------------------------------------------
127 */
128 /*
129    ----------------------------------------
130    purpose -- to write the object to a file
131               in human readable form
132 
133    created -- 98may02, cca
134    ----------------------------------------
135 */
136 void
137 ChvList_writeForHumanEye (
138    ChvList   *chvlist,
139    FILE       *fp
140 ) ;
141 /*--------------------------------------------------------------------*/
142 /*
143 ------------------------------------------------------------------------
144 ----- methods found in util.c ------------------------------------------
145 ------------------------------------------------------------------------
146 */
147 /*
148    -----------------------------------
149    return 1 if list ilist is not empty
150    return 0 if list ilist is empty
151 
152    created -- 98may02, cca
153    -----------------------------------
154 */
155 int
156 ChvList_isListNonempty (
157    ChvList   *chvlist,
158    int       ilist
159 ) ;
160 /*
161    ---------------------------------------------------------
162    return 1 if the count for list ilist is zero
163    return 0 if the count for list ilist is greater than zero
164 
165    created -- 98may02, cca
166    ---------------------------------------------------------
167 */
168 int
169 ChvList_isCountZero (
170    ChvList   *chvlist,
171    int       ilist
172 ) ;
173 /*
174    ---------------------------------
175    if chv is not NULL then
176       add chv to list ilist
177    endif
178    decrement the count of list ilist
179 
180    created -- 98may02, cca
181    ---------------------------------
182 */
183 void
184 ChvList_addObjectToList (
185    ChvList   *chvlist,
186    Chv       *chv,
187    int       ilist
188 ) ;
189 /*
190    ------------------------------------
191    return pointer to head of list ilist
192    and set head to NULL
193 
194    created -- 98may02, cca
195    ------------------------------------
196 */
197 Chv *
198 ChvList_getList (
199    ChvList   *chvlist,
200    int       ilist
201 ) ;
202 /*--------------------------------------------------------------------*/
203