/[ascend]/trunk/base/generic/compiler/arrayinst.h
ViewVC logotype

Contents of /trunk/base/generic/compiler/arrayinst.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1 - (show annotations) (download) (as text)
Fri Oct 29 20:54:12 2004 UTC (20 years ago) by aw0a
Original Path: trunk/ascend4/compiler/arrayinst.h
File MIME type: text/x-chdr
File size: 12288 byte(s)
Setting up web subdirectory in repository
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__ */

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22