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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1 - (hide 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 aw0a 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