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

/** addtogroup compiler Compiler
    @{
*/

/* 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	/** addtogroup compiler Compiler
94	@{
95	*/
96
97	/* Array child memory management */
98	#define CAC(acp) ((struct ArrayChild *)(acp))
99
100	extern pool_store_t g_array_child_pool;
101	/**<
102	* Pool of array children.
103	* Never ever dereference this except with MALLOCPOOLAC or FREEPOOLAC().
104	*/
105
106	#ifdef ASC_NO_POOL
107
108	/* slow version for debugging */
109	#define MALLOCPOOLAC CAC( ascmalloc(sizeof(struct ArrayChild)) )
110	/**<
111	* Get an element from the pool (slow, unpooled version).
112	* Only call after InitInstanceNanny().
113	*/
114	#define FREEPOOLAC(ac) ascfree(ac);
115	/**<
116	* Return element ac to the pool (slow, unpooled version).
117	* Only call after InitInstanceNanny().
118	*/
119
120	#else
121
122	#define MALLOCPOOLAC CAC(pool_get_element(g_array_child_pool))
123	/*< Get an element from the pool. Only call after InitInstanceNanny(). /
124	#define FREEPOOLAC(ac) pool_free_element(g_array_child_pool,(ac))
125	/*< Return element ac to the pool. Only call after InitInstanceNanny(). /
126
127	#endif /* ASC_NO_POOL */
128
129	extern void InitInstanceNanny(void);
130	/**<
131	* <!-- InitInstanceNanny(); -->
132	* Sets up array child instantiation gizmos. This must be called once
133	* before any arrays can be built, ideally at startup time.
134	* Do not call it again unless DestroyInstanceNanny is called first.
135	* If insufficient memory to compile anything at all, does exit(2). <br><br>
136	*
137	* Under no circumstances should you (an external client) be freeing
138	* a struct ArrayChild.
139	*/
140
141	extern void DestroyInstanceNanny(void);
142	/**<
143	* Destroy array child instantiation gizmos. This must be called to
144	* clean up before shutting down ASCEND.
145	* Do attempt to instantiate anything after you call this unless you
146	* have recalled InitInstanceNanny().
147	*/
148
149	extern void ReportInstanceNanny(FILE *f);
150	/**<
151	* Reports on the array child instantiator to f.
152	*/
153
154	/* Array management */
155
156	extern struct gl_list_t
157	CollectArrayInstances(CONST struct Instance i,
158	struct gl_list_t *list);
159	/**<
160	* Appends pointers of the set/MODEL/ATOM/constant instances found in
161	* the leaves of an array instance, i, sparse or dense.
162	* If list given by user is NULL, a list to be returned is made if
163	* necessary.
164	* If i is not an array, list returned will be NULL if list given is NULL.
165	* If i is an array, list returned may be empty, but not NULL.
166	* This function recurses through all the subscripts of the array.
167	*/
168
169	typedef void (AVProc)(struct Instance );
170	/*< A function taking an Instance and having no return value. */
171
172	extern void ArrayVisitLocalLeaves(struct Instance *mch, AVProc func);
173	/**<
174	This function visits the instances indicated by the name
175	given in the definition statement of mch.
176	func is as described in visitinst.h for VisitProc.
177	mch is an array instance that is the child of a MODEL.
178	*/
179
180	ASC_DLLSPEC struct InstanceChildByChar(CONST struct Instance i,
181	symchar *str);
182	/**<
183	* This returns to the pointer to a child, c, of parent,p, named by str.
184	* str must be a simple name. If child not found, returns NULL.
185	* str must be from the symbol table. If AscFindSymbol(str)==NULL,
186	* then this function should not be called because NO instance
187	* can have a child with a name which is not in the symbol table.
188	* func is as described in visitinst.h for VisitProc.
189	* mch is an array instance that is the child of a MODEL.
190	*/
191
192	/* Dense array procedures. (non-relations) */
193
194	extern int RectangleArrayExpanded(CONST struct Instance *i);
195	/**<
196	* Test if the array is fully expanded
197	* (i.e. all the sets for all the derefencing have been specified).<br><br>
198	*
199	* On sparse arrays, this operator might return a FALSE positive
200	* because it checks down the leading member of each defined
201	* subscript range. This error is precluded only by the fact that when
202	* instantiating, we do sparse arrays completely in one pass, therefore
203	* the leading members check is a sufficient test.
204	* In general, however, this should not be used on sparse arrays.
205	*/
206
207	extern int RectangleSubscriptsMatch(CONST struct Instance *context,
208	CONST struct Instance *ary,
209	CONST struct Name *subscripts);
210	/**<
211	* Test if the ary children expected from evaluating the
212	* nodes of subscripts (all set nodes) are all compatible
213	* with the children of the array instance given. The set
214	* expressions in Name elements are evaluated in the context given.
215	* Assumes the array has been fully expanded. <br><br>
216	*
217	* On array subscripts not yet resolvable, returns -2; try later. <br>
218	* On array shape mismatch, returns -1. <br>
219	* On subscripts mismatch, returns 0. <br>
220	* On match, returns 1. <br><br>
221	*
222	* On sparse arrays, this operator should NOT be used.
223	* A reasonably intelligent person could rewrite this to handle sparse
224	* arrays, with the addition of a for_table argument.
225	*/
226
227	extern unsigned long NextToExpand(CONST struct Instance *i);
228	/**<
229	* Return the number of the dereferencing that needs to be expanded. This
230	* returns 0 if none are needed; 1 is the first dereference.
231	*/
232
233	extern unsigned long NumberofDereferences(CONST struct Instance *i);
234	/**<
235	* This returns the number of dereferences that this array instance has
236	* before reaching what the array contains.
237	*/
238
239	extern CONST struct Set IndexSet(CONST struct Instance i, unsigned long num);
240	/**<
241	* Return the set that the num'th index is defined over. Don't make any
242	* changes to the structure that is returned!
243	* 1 <= num <= NumberofDereferences(i)
244	* Will return NULL on the final subscript of an ALIASES/IS_A
245	* inside a FOR loop.
246	*/
247
248	extern void ExpandArray(struct Instance *i,
249	unsigned long num,
250	struct set_t *set,
251	struct Instance *rhsinst,
252	struct Instance *arginst,
253	struct gl_list_t *rhslist);
254	/**<
255	* This will expand the num'th index over the set of index values given by
256	* set. set is returned unchanged.<br><br>
257	*
258	* If the array is being expanded by an IS_A, this may effect the pending
259	* instance list. All the instances it adds will be added below the top.<br><br>
260	*
261	* If the array is being expanded by an alias, rhsinst is not NULL and
262	* rhsinst is used as the array element and pending list is not affected.<br><br>
263	*
264	* If the array is being expanded by an aliases-IS_A, rhsinst is NULL,
265	* rhslist is used as the array elements source for copying,
266	* and the pending list is not affected.
267	* The contents of the list is a bunch of struct ArrayChild * which should
268	* have indices matching the last subscript of the array being expanded.
269	* Deallocating the contents of the rhs ist is the caller's responsibility,
270	* as is creating it -- it is copied as needed internally.<br><br>
271	*
272	* If the array being expanded is of a parametric type, the arginst
273	* will be used to construct the elements and pending list may be affected.
274	*/
275
276	/* Sparse arrays stuff. */
277
278	extern struct Instance FindOrAddIntChild(struct Instance i,
279	long v,
280	struct Instance *rhsinst,
281	struct Instance *arginst);
282	/**<
283	* Add sparse array child at location defined by current ForTable
284	* after instantiating child if rhsinst is NULL (an ISA).
285	* If instantiating, uses arginst if not NULL.
286	* Uses rhsinst if it is not NULL (an array element defined by alias).
287	*/
288
289	extern struct Instance FindOrAddStrChild(struct Instance i,
290	symchar *sym,
291	struct Instance *rhsinst,
292	struct Instance *arginst);
293	/**<
294	* Add sparse array child at location defined by current ForTable
295	* after instantiating child if rhsinst is NULL (an ISA).
296	* If instantiating, uses arginst if not NULL.
297	* Uses rhsinst if it is not NULL (an array element defined by alias).
298	*/
299
300	extern int CmpArrayInsts(struct Instance i1, struct Instance i2);
301	/**<
302	* Returns 0 if the arrays i1 and i2 are defined over equivalent subscript
303	* ranges and have leaf parts of shallowly equivalent types.
304	* (hint: relations and models are not deeply checked.)
305	* Returns 1 for any non-equivalency.
306	* Doesn't return if called with something other than arrays.
307	* NULL input --> 1 + warning, rather than exit.
308	*/
309
310	/* @} */
311
312	#endif /* ASC_ARRAYINST_H */