generic/compiler/arrayinst.h

/*  ASCEND modelling environment
    Copyright (C) 2006 Carnegie Mellon University
    Copyright (C) 1996, 1997 Ben Allan
    Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2, or (at your option)
    any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*//*
    by Tom Epperly 8/16/89, Ben Allan
    Last in CVS $Revision: 1.15 $ $Date: 1998/04/07 19:52:46 $ $Author: ballan $
*/

/** @file
 *  Ascend Instance Array Functions.
 *  <pre>
 *  When #including arrayinst.h, make sure these files are #included first:
 *         #include "utilities/ascConfig.h"
 *         #include "instance_enum.h"
 *         #include "compiler.h"
 *         #include "setvalinst.h"
 *         #include "pool.h"
 *         #include "list.h"
 *
 *  Notes on the structure implemented for ASCEND arrays.
 *
 *  ASCEND arrays are 'associative arrays.' That is they are
 *  not sequential in memory, rather they are accessed by
 *  names of the elements. So there really isn't a difference
 *  between a dense rectangular array and a sparse array except
 *  it is algorithmically easier to construct the dense array.
 *
 *  For example:
 *
 *       a[1..2]['a','f'] IS_A foo;
 *
 *  yields an internal data structure (a, uai1 and uai2
 *  are ArrayInstances as described in instance_types.h) like so:
 *
 *  a -------------------|-----------------------|    <=== gl_list_t
 *                       V                       V         *childlist.
 *                    ArrayChild{             ArrayChild{
 *                    name.int = 1            name.int = 2
 *              unnamed array inst|}    unnamed array inst|}
 *     /--------------------------/    /------------------/
 *    V                               V
 *    uai1 ------|-------|            uai2 -----|-----|  <=== gl_list_t's
 *               V       V                      V     V
 *             AC       AC                     AC     AC
 *       name.str='a'  name.str='f'      name.str='a'  name.str='f'
 *       inst --\      inst --\          inst --\      inst --\
 *              |             |                 |             |
 *              V             V                 V             V
 *        fooinst       fooinst            fooinst       fooinst
 *
 *  Unnamed array instances actually DO have a compiler generated
 *  internal name, but it is not useful for anything except avoiding
 *  core dumps in routines that assume all insts have names.
 *
 *  Navigating these structures during assembly is
 *  terribly dangerous so all that is handled by this file.
 *
 *  All the indirection in these structures makes interesting tricks
 *  for sparse and dense arrays possible.
 *
 *  One trick in particular, however, is NOT to be attempted because
 *  it plays havoc with the semantics of the ASCEND language:
 *  thou shalt not declare an array over one set and then later expand
 *  it to have more elements.  This would be trivial to implement
 *  because the elements exist in gl_lists, but so far every potential
 *  application proposed for it has been the result of sloppy and/or
 *  lazy thinking.  In the end we may find a need for a genuine
 *  multidimensional ListInstance that has much in common with arrays,
 *  but such a creature should be implemented as its own creature and
 *  not a sloppy graft on top of arrays.
 *  </pre>
 */

#ifndef ASC_ARRAYINST_H
#define ASC_ARRAYINST_H

/* Array child memory management */
#define CAC(acp) ((struct ArrayChild *)(acp))

extern pool_store_t g_array_child_pool;
/**< 
 *  Pool of array children.
 *  Never ever dereference this except with MALLOCPOOLAC or FREEPOOLAC(). 
 */

#ifdef ASC_NO_POOL

/* slow version for debugging */
#define MALLOCPOOLAC CAC( ascmalloc(sizeof(struct ArrayChild)) )
/**< 
 *  Get an element from the pool (slow, unpooled version).
 *  Only call after InitInstanceNanny(). 
 */
#define FREEPOOLAC(ac) ascfree(ac);
/**< 
 *  Return element ac to the pool (slow, unpooled version). 
 *  Only call after InitInstanceNanny(). 
 */

#else

#define MALLOCPOOLAC CAC(pool_get_element(g_array_child_pool))
/**< Get an element from the pool. Only call after InitInstanceNanny(). */
#define FREEPOOLAC(ac) pool_free_element(g_array_child_pool,(ac))
/**< Return element ac to the pool. Only call after InitInstanceNanny(). */

#endif /* ASC_NO_POOL */

extern void InitInstanceNanny(void);
/**<
 *  <!--  InitInstanceNanny();                                         -->
 *  Sets up array child instantiation gizmos. This must be called once
 *  before any arrays can be built, ideally at startup time.
 *  Do not call it again unless DestroyInstanceNanny is called first.
 *  If insufficient memory to compile anything at all, does exit(2). <br><br>
 *
 *  Under no circumstances should you (an external client) be freeing
 *  a struct ArrayChild.
 */

extern void DestroyInstanceNanny(void);
/**<
 *  Destroy array child instantiation gizmos. This must be called to
 *  clean up before shutting down ASCEND.
 *  Do attempt to instantiate anything after you call this unless you
 *  have recalled InitInstanceNanny().
 */

extern void ReportInstanceNanny(FILE *f);
/**<
 *  Reports on the array child instantiator to f.
 */

/* Array management */

extern struct gl_list_t
*CollectArrayInstances(CONST struct Instance *i,
                       struct gl_list_t *list);
/**<
 *  Appends pointers of the set/MODEL/ATOM/constant instances found in
 *  the leaves of an array instance, i, sparse or dense.
 *  If list given by user is NULL, a list to be returned is made if
 *  necessary.
 *  If i is not an array, list returned will be NULL if list given is NULL.
 *  If i is an array, list returned may be empty, but not NULL.
 *  This function recurses through all the subscripts of the array.
 */

typedef void (*AVProc)(struct Instance *);
/**< A function taking an Instance* and having no return value. */

extern void ArrayVisitLocalLeaves(struct Instance *mch, AVProc func);
/**<
    This function visits the instances indicated by the name
    given in the definition statement of mch.
    func is as described in visitinst.h for VisitProc.
    mch is an array instance that is the child of a MODEL.
*/

ASC_DLLSPEC(struct Instance*) ChildByChar(CONST struct Instance *i,
                                    symchar *str);
/**<
 *  This returns to the pointer to a child, c, of parent,p, named by str.
 *  str must be a simple name. If child not found, returns NULL.
 *  str must be from the symbol table. If AscFindSymbol(str)==NULL,
 *  then this function should not be called because NO instance
 *  can have a child with a name which is not in the symbol table.
 *  func is as described in visitinst.h for VisitProc.
 *  mch is an array instance that is the child of a MODEL.
 */

/* Dense array procedures. (non-relations) */

extern int RectangleArrayExpanded(CONST struct Instance *i);
/**<
 *  Test if the array is fully expanded
 *  (i.e. all the sets for all the derefencing have been specified).<br><br>
 *
 *  On sparse arrays, this operator might return a FALSE positive
 *  because it checks down the leading member of each defined
 *  subscript range. This error is precluded only by the fact that when
 *  instantiating, we do sparse arrays completely in one pass, therefore
 *  the leading members check is a sufficient test.
 *  In general, however, this should not be used on sparse arrays.
 */

extern int RectangleSubscriptsMatch(CONST struct Instance *context,
                                    CONST struct Instance *ary,
                                    CONST struct Name *subscripts);
/**<
 *  Test if the ary children expected from evaluating the
 *  nodes of subscripts (all set nodes) are all compatible
 *  with the children of the array instance given. The set
 *  expressions in Name elements are evaluated in the context given.
 *  Assumes the array has been fully expanded. <br><br>
 *
 *  On array subscripts not yet resolvable, returns -2; try later. <br>
 *  On array shape mismatch, returns -1. <br>
 *  On subscripts mismatch, returns 0. <br>
 *  On match, returns 1. <br><br>
 *
 *  On sparse arrays, this operator should NOT be used.
 *  A reasonably intelligent person could rewrite this to handle sparse
 *  arrays, with the addition of a for_table argument.
 */

extern unsigned long NextToExpand(CONST struct Instance *i);
/**<
 *  Return the number of the dereferencing that needs to be expanded.  This
 *  returns 0 if none are needed; 1 is the first dereference.
 */

extern unsigned long NumberofDereferences(CONST struct Instance *i);
/**<
 *  This returns the number of dereferences that this array instance has
 *  before reaching what the array contains.
 */

extern CONST struct Set *IndexSet(CONST struct Instance *i, unsigned long num);
/**<
 *  Return the set that the num'th index is defined over.  Don't make any
 *  changes to the structure that is returned!
 *  1 <= num <= NumberofDereferences(i)
 *  Will return NULL on the final subscript of an ALIASES/IS_A
 *  inside a FOR loop.
 */

extern void ExpandArray(struct Instance *i,
                        unsigned long num,
                        struct set_t *set,
                        struct Instance *rhsinst,
                        struct Instance *arginst,
                        struct gl_list_t *rhslist);
/**<
 *  This will expand the num'th index over the set of index values given by
 *  set.  set is returned unchanged.<br><br>
 *
 *  If the array is being expanded by an IS_A, this may effect the pending
 *  instance list.  All the instances it adds will be added below the top.<br><br>
 *
 *  If the array is being expanded by an alias, rhsinst is not NULL and
 *  rhsinst is used as the array element and pending list is not affected.<br><br>
 *
 *  If the array is being expanded by an aliases-IS_A, rhsinst is NULL,
 *  rhslist is used as the array elements source for copying,
 *  and the pending list is not affected.
 *  The contents of the list is a bunch of struct ArrayChild * which should
 *  have indices matching the last subscript of the array being expanded.
 *  Deallocating the contents of the rhs ist is the caller's responsibility,
 *  as is creating it -- it is copied as needed internally.<br><br>
 *
 *  If the array being expanded is of a parametric type, the arginst
 *  will be used to construct the elements and pending list may be affected.
 */

/* Sparse arrays stuff. */

extern struct Instance *FindOrAddIntChild(struct Instance *i,
                                          long v,
                                          struct Instance *rhsinst,
                                          struct Instance *arginst);
/**<
 *  Add sparse array child at location defined by current ForTable
 *  after instantiating child if rhsinst is NULL (an ISA).
 *  If instantiating, uses arginst if not NULL.
 *  Uses rhsinst if it is not NULL (an array element defined by alias).
 */

extern struct Instance *FindOrAddStrChild(struct Instance *i,
                                          symchar *sym,
                                          struct Instance *rhsinst,
                                          struct Instance *arginst);
/**<
 *  Add sparse array child at location defined by current ForTable
 *  after instantiating child if rhsinst is NULL (an ISA).
 *  If instantiating, uses arginst if not NULL.
 *  Uses rhsinst if it is not NULL (an array element defined by alias).
 */

extern int CmpArrayInsts(struct Instance *i1, struct Instance *i2);
/**<
 *  Returns 0 if the arrays i1 and i2 are defined over equivalent subscript
 *  ranges and have leaf parts of shallowly equivalent types.
 *  (hint: relations and models are not deeply checked.)
 *  Returns 1 for any non-equivalency.
 *  Doesn't return if called with something other than arrays.
 *  NULL input --> 1 + warning, rather than exit.
 */

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