1 |
/* |
2 |
* Ascend Instance Array Functions |
3 |
* by Tom Epperly & Ben Allan |
4 |
* 8/16/89 |
5 |
* Version: $Revision: 1.15 $ |
6 |
* Version control file: $RCSfile: arrayinst.h,v $ |
7 |
* Date last modified: $Date: 1998/04/07 19:52:46 $ |
8 |
* Last modified by: $Author: ballan $ |
9 |
* |
10 |
* This file is part of the Ascend Language Interpreter. |
11 |
* |
12 |
* Copyright (C) 1996, 1997 Benjamin Andrew Allan |
13 |
* based on instance.c |
14 |
* Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly |
15 |
* |
16 |
* The Ascend Language Interpreter is free software; you can redistribute |
17 |
* it and/or modify it under the terms of the GNU General Public License as |
18 |
* published by the Free Software Foundation; either version 2 of the |
19 |
* License, or (at your option) any later version. |
20 |
* |
21 |
* The Ascend Language Interpreter is distributed in hope that it will be |
22 |
* useful, but WITHOUT ANY WARRANTY; without even the implied warranty of |
23 |
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU |
24 |
* General Public License for more details. |
25 |
* |
26 |
* You should have received a copy of the GNU General Public License |
27 |
* along with the program; if not, write to the Free Software Foundation, |
28 |
* Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named |
29 |
* COPYING. |
30 |
*/ |
31 |
|
32 |
#ifndef __ARRAYINST_H_SEEN__ |
33 |
#define __ARRAYINST_H_SEEN__ |
34 |
|
35 |
/* |
36 |
* When #including arrayinst.h, make sure these files are #included first: |
37 |
* #include "instance_enum.h" |
38 |
* #include "compiler.h" |
39 |
* #include "setvalinst.h" |
40 |
* #include "pool.h" |
41 |
* #include "list.h" |
42 |
*/ |
43 |
|
44 |
|
45 |
/* Array child memory management */ |
46 |
|
47 |
#define CAC(acp) ((struct ArrayChild *)(acp)) |
48 |
|
49 |
extern pool_store_t g_array_child_pool; |
50 |
/* never ever dereference this except with the following 2 macros: */ |
51 |
|
52 |
#define MALLOCPOOLAC CAC(pool_get_element(g_array_child_pool)) |
53 |
/* |
54 |
* Get an element from the pool. Only after InitInstanceNanny. |
55 |
*/ |
56 |
|
57 |
#define FREEPOOLAC(ac) pool_free_element(g_array_child_pool,(ac)) |
58 |
/* |
59 |
* Return an element, ac, to the pool. Only after InitInstanceNanny. |
60 |
*/ |
61 |
|
62 |
extern void InitInstanceNanny(void); |
63 |
/* |
64 |
* InitInstanceNanny(); |
65 |
* Sets up array child instantiation gizmos. This must be called once |
66 |
* before any arrays can be built, ideally at startup time. |
67 |
* Do not call it again unless DestroyInstanceNanny is called first. |
68 |
* If insufficient memory to compile anything at all, does exit(2). |
69 |
* |
70 |
* Under no circumstances should you (an external client) be freeing |
71 |
* a struct ArrayChild. |
72 |
*/ |
73 |
|
74 |
extern void DestroyInstanceNanny(void); |
75 |
/* |
76 |
* DestroyInstanceNanny(); |
77 |
* Destroy array child instantiation gizmos. This must be called to |
78 |
* clean up before shutting down ASCEND. |
79 |
* Do attempt to instantiate anything after you call this unless you |
80 |
* have recalled InitInstanceNanny. |
81 |
*/ |
82 |
|
83 |
extern void ReportInstanceNanny(FILE*); |
84 |
/* |
85 |
* ReportInstanceNanny(f); |
86 |
* FILE *f; |
87 |
* Reports on the array child instantiator to f. |
88 |
*/ |
89 |
|
90 |
/* |
91 |
* Notes on the structure implemented for ASCEND arrays. |
92 |
* |
93 |
* ASCEND arrays are 'associative arrays.' That is they are |
94 |
* not sequential in memory, rather they are accessed by |
95 |
* names of the elements. So there really isn't a difference |
96 |
* between a dense rectangular array and a sparse array except |
97 |
* it is algorithmically easier to construct the dense array. |
98 |
* |
99 |
* E.G. |
100 |
* a[1..2]['a','f'] IS_A foo; |
101 |
* yields an internal data structure (a, uai1 and uai1 |
102 |
* are ArrayInstances as described in instance_types.h) like so: |
103 |
* a -------------------|-----------------------| <=== gl_list_t |
104 |
* V V *childlist. |
105 |
* ArrayChild{ ArrayChild{ |
106 |
* name.int = 1 name.int = 2 |
107 |
* unnamed array inst|} unnamed array inst|} |
108 |
* /--------------------------/ /------------------/ |
109 |
* V V |
110 |
* uai1 ------|-------| uai2 -----|-----| <=== gl_list_t's |
111 |
* V V V V |
112 |
* AC AC AC AC |
113 |
* name.str='a' name.str='f' name.str='a' name.str='f' |
114 |
* inst --\ inst --\ inst --\ inst --\ |
115 |
* | | | | |
116 |
* V V V V |
117 |
* fooinst fooinst fooinst fooinst |
118 |
* |
119 |
* Unnamed array instances actually DO have a compiler generated |
120 |
* internal name, but it is not useful for anything except avoiding |
121 |
* core dumps in routines that assume all insts have names. |
122 |
* |
123 |
* Navigating these structures during assembly is |
124 |
* terribly dangerous so all that is handled by this file. |
125 |
* |
126 |
* All the indirection in these structures makes interesting tricks |
127 |
* for sparse and dense arrays possible. |
128 |
* |
129 |
* One trick in particular, |
130 |
* however, is NOT to be attempted because it plays havoc with the |
131 |
* semantics of the ASCEND language: thou shalt not declare an array |
132 |
* over one set and then later expand it to have more elements. |
133 |
* This would be trivial to implement because the elements exist in |
134 |
* gl_lists, but so far every potential application proposed for it |
135 |
* has been the result of sloppy thinking and/or lazy thinking. |
136 |
* In the end we may find a need for a genuine multidimensional |
137 |
* ListInstance that has much in common with arrays, but such a |
138 |
* creature should be implemented as it's own creature and not a |
139 |
* sloppy graft on top of arrays. |
140 |
*/ |
141 |
|
142 |
extern struct gl_list_t *CollectArrayInstances(CONST struct Instance *, |
143 |
struct gl_list_t *); |
144 |
/* |
145 |
* list = CollectArrayInstances(i,NULL); |
146 |
* const struct Instance *i; |
147 |
* struct gl_list_t *list; |
148 |
* Appends pointers of the set/MODEL/ATOM/constant instances found in |
149 |
* the leaves of an array instance, i, sparse or dense. |
150 |
* If list given by user is NULL, a list to be returned is made if |
151 |
* necessary. |
152 |
* If i is not an array, list returned will be NULL if list given is NULL. |
153 |
* If i is an array, list returned may be empty, but not NULL. |
154 |
* This function recurses through all the subscripts of the array. |
155 |
*/ |
156 |
|
157 |
typedef void (*AVProc)(struct Instance *); |
158 |
extern void ArrayVisitLocalLeaves(struct Instance *,AVProc); |
159 |
/* |
160 |
* ArrayVisitLocalLeaves(mch,func) |
161 |
* struct Instance *mch; |
162 |
* AVProc func; |
163 |
* func is as described in visitinst.h for VisitProc. |
164 |
* mch is an array instance that is the child of a MODEL. |
165 |
* This function visits the instances indicated by the name |
166 |
* given in the definition statement of mch. |
167 |
*/ |
168 |
|
169 |
/* |
170 |
* Dense array procedures. (non-relations) |
171 |
*/ |
172 |
|
173 |
extern int RectangleArrayExpanded(CONST struct Instance *); |
174 |
/* |
175 |
* int RectangleArrayExpanded(i) |
176 |
* const struct Instance *i; |
177 |
* Test if the array is fully expanded |
178 |
* (i.e. all the sets for all the derefencing have been specified). |
179 |
* |
180 |
* On sparse arrays, this operator might return a FALSE positive |
181 |
* because it checks down the leading member of each defined |
182 |
* subscript range. This error is precluded only by the fact that when |
183 |
* instantiating, we do sparse arrays completely in one pass, therefore |
184 |
* the leading members check is a sufficient test. |
185 |
* In general, however, this should not be used on sparse arrays. |
186 |
*/ |
187 |
|
188 |
extern int RectangleSubscriptsMatch(CONST struct Instance *, |
189 |
CONST struct Instance *, |
190 |
CONST struct Name *); |
191 |
/* |
192 |
* int RectangleSubscriptsMatch(context,ary,subscripts) |
193 |
* const struct Instance *context, *ary; |
194 |
* const struct Name *subscripts; |
195 |
* Test if the ary children expected from evaluating the |
196 |
* nodes of subscripts (all set nodes) are all compatible |
197 |
* with the children of the array instance given. The set |
198 |
* expressions in Name elements are evaluated in the context given. |
199 |
* Assumes the array has been fully expanded. |
200 |
* On array subscripts not yet resolvable, returns -2; try later. |
201 |
* On array shape mismatch, returns -1. |
202 |
* On subscripts mismatch, returns 0. |
203 |
* On match, returns 1. |
204 |
* |
205 |
* On sparse arrays, this operator should NOT be used. |
206 |
* A reasonably intelligent person could rewrite this to handle sparse |
207 |
* arrays, with the addition of a for_table argument. |
208 |
*/ |
209 |
|
210 |
extern unsigned long NextToExpand(CONST struct Instance *); |
211 |
/* |
212 |
* unsigned long NextToExpand(i) |
213 |
* const struct Instance *i; |
214 |
* Return the number of the dereferencing that needs to be expanded. This |
215 |
* returns 0 if none are needed; 1 is the first dereference. |
216 |
*/ |
217 |
|
218 |
extern unsigned long NumberofDereferences(CONST struct Instance *); |
219 |
/* |
220 |
* unsigned long NumberofDereferences(i) |
221 |
* const struct Instance *i; |
222 |
* This returns the number of dereferences that this array instance has |
223 |
* before reaching what the array contains. |
224 |
*/ |
225 |
|
226 |
extern CONST struct Set *IndexSet(CONST struct Instance *,unsigned long); |
227 |
/* |
228 |
* struct Set *IndexSet(i,num) |
229 |
* struct Instance *i; |
230 |
* unsigned long num; |
231 |
* Return the set that the num'th index is defined over. Don't make any |
232 |
* changes to the structure that is returned! |
233 |
* 1 <= num <= NumberofDereferences(i) |
234 |
* Will return NULL on the final subscript of an ALIASES/IS_A |
235 |
* inside a FOR loop. |
236 |
*/ |
237 |
|
238 |
extern void ExpandArray(struct Instance *, |
239 |
unsigned long, |
240 |
struct set_t *, |
241 |
struct Instance *, |
242 |
struct Instance *, |
243 |
struct gl_list_t *); |
244 |
/* |
245 |
* void ExpandArray(i,num,set,rhsinst,arginst,rhslist) |
246 |
* struct Instance *i; |
247 |
* unsigned long num; |
248 |
* struct set_t *set; |
249 |
* struct Instance *arginst, *rhsinst; |
250 |
* struct gl_list_t *rhslist; |
251 |
* |
252 |
* This will expand the num'th index over the set of index values given by |
253 |
* set. set is returned unchanged. |
254 |
* |
255 |
* If the array is being expanded by an IS_A, this may effect the pending |
256 |
* instance list. All the instances it adds will be added below the top. |
257 |
* |
258 |
* If the array is being expanded by an alias, rhsinst is not NULL and |
259 |
* rhsinst is used as the array element and pending list is not affected. |
260 |
* |
261 |
* If the array is being expanded by an aliases-IS_A, rhsinst is NULL, |
262 |
* rhslist is used as the array elements source for copying, |
263 |
* and the pending list is not affected. |
264 |
* The contents of the list is a bunch of struct ArrayChild * which should |
265 |
* have indices matching the last subscript of the array being expanded. |
266 |
* Deallocating the contents of the rhs ist is the caller's responsibility, |
267 |
* as is creating it -- it is copied as needed internally. |
268 |
* |
269 |
* If the array being expanded is of a parametric type, the arginst |
270 |
* will be used to construct the elements and pending list may be affected. |
271 |
*/ |
272 |
|
273 |
/* |
274 |
* Sparse arrays stuff. |
275 |
*/ |
276 |
|
277 |
extern struct Instance *FindOrAddIntChild(struct Instance *,long, |
278 |
struct Instance *, |
279 |
struct Instance *); |
280 |
/* |
281 |
* struct Instance *FindOrAddIntChild(i,v,rhsinst,arginst) |
282 |
* struct Instance *i,*rhsinst, *arginst; |
283 |
* long v; |
284 |
* Add sparse array child at location defined by current ForTable |
285 |
* after instantiating child if rhsinst is NULL (an ISA). |
286 |
* If instantiating, uses arginst if not NULL. |
287 |
* Uses rhsinst if it is not NULL (an array element defined by alias). |
288 |
*/ |
289 |
|
290 |
extern struct Instance *FindOrAddStrChild(struct Instance *,symchar *, |
291 |
struct Instance *, |
292 |
struct Instance *); |
293 |
/* |
294 |
* struct Instance *FindOrAddStrChild(i,sym,rhsinst,arginst) |
295 |
* struct Instance *i, *rhsinst, *arginst; |
296 |
* symchar *sym; |
297 |
* Add sparse array child at location defined by current ForTable |
298 |
* after instantiating child if rhsinst is NULL (an ISA). |
299 |
* If instantiating, uses arginst if not NULL. |
300 |
* Uses rhsinst if it is not NULL (an array element defined by alias). |
301 |
*/ |
302 |
|
303 |
extern int CmpArrayInsts(struct Instance *, struct Instance *); |
304 |
/* |
305 |
* int CmpArrayInsts(i1,i2) |
306 |
* struct Instance *i1, *i2; |
307 |
* Returns 0 if the arrays i1 and i2 are defined over equivalent subscript |
308 |
* ranges and have leaf parts of shallowly equivalent types. |
309 |
* (hint: relations and models are not deeply checked.) |
310 |
* Returns 1 for any non-equivalency. |
311 |
* Doesn't return if called with something other than arrays. |
312 |
* NULL input --> 1 + warning, rather than exit. |
313 |
*/ |
314 |
|
315 |
#endif |
316 |
/* __ARRAYINST_H_SEEN__ */ |