/[ascend]/trunk/ascend/compiler/instantiate.h
ViewVC logotype

Annotation of /trunk/ascend/compiler/instantiate.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2376 - (hide annotations) (download) (as text)
Thu Feb 3 06:02:36 2011 UTC (13 years, 5 months ago) by jpye
File MIME type: text/x-chdr
File size: 10188 byte(s)
minor text changes
1 johnpye 767 /* ASCEND modelling environment
2     Copyright (C) 2006 Carnegie Mellon University
3     Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
4 aw0a 1
5 johnpye 767 This program is free software; you can redistribute it and/or modify
6     it under the terms of the GNU General Public License as published by
7     the Free Software Foundation; either version 2, or (at your option)
8     any later version.
9 aw0a 1
10 johnpye 767 This program is distributed in the hope that it will be useful,
11     but WITHOUT ANY WARRANTY; without even the implied warranty of
12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13     GNU General Public License for more details.
14    
15     You should have received a copy of the GNU General Public License
16     along with this program; if not, write to the Free Software
17     Foundation, Inc., 59 Temple Place - Suite 330,
18     Boston, MA 02111-1307, USA.
19     *//** @file
20     Ascend Interpreter(Instantiator).
21    
22     Requires:
23     #include "utilities/ascConfig.h"
24     #include "compiler/instance_enum.h"
25     #include "compiler/fractions.h"
26     #include "compiler/compiler.h"
27     #include "compiler/dimen.h"
28     #include "compiler/types.h"
29     #include "compiler/stattypes.h"
30     </pre>
31     *//*
32     by Tom Epperly
33     Created: 1/24/90
34     Last in CVS: $Revision: 1.18 $ $Date: 1998/03/25 00:32:03 $ $Author: ballan $
35     *//** @mainpage
36    
37     @section intro_sec Introduction
38    
39     This the the code documentation for 'libascend', which contains the 'base'
40     or 'core' components of the ASCEND modelling environment.
41    
42     The two main parts are the compiler and the solver. There are also a number
43     of general and utilities files, as well as some 'internal' packages.
44    
45     For further information about ASCEND, see the Developers' Wiki at
46 jpye 1793 http://ascendwiki.cheme.cmu.edu/
47 johnpye 767
48     @section license License
49    
50     ASCEND is licensed under the GNU General Public License. See the the file
51     'LICENSE.txt' for more information, which is available at:
52 jpye 2376 http://ascendcode.cheme.cmu.edu/viewvc.cgi/code/trunk/LICENSE.txt?view=markup
53 johnpye 767 */
54    
55 johnpye 67 #ifndef ASC_INSTANTIATE_H
56     #define ASC_INSTANTIATE_H
57 aw0a 1
58 jpye 1684 #include "stattypes.h"
59    
60 jpye 2316 /** @addtogroup compiler_inst Compiler Instance Hierarchy
61 johnpye 1066 @{
62     */
63    
64 johnpye 742 /*
65 jds 216 * Relation instantiation flags.
66 johnpye 742 * If you add/remove/change these, update the comments in
67 jds 216 * SetInstantiationRelnFlags().
68     */
69 aw0a 1 #define NORELS 0x0
70     #define GBOXRELS 0x1
71     #define BBOXRELS 0x2
72     #define TOKRELS 0x4
73     #define ALLRELS (GBOXRELS | BBOXRELS | TOKRELS)
74     #define EXTRELS (GBOXRELS | BBOXRELS)
75    
76 johnpye 1063 ASC_DLLSPEC long int g_compiler_counter;
77 jds 216 /**< Unique id of calls to instantiator. */
78 aw0a 1
79 jds 54 extern void SetInstantiationRelnFlags(unsigned int flag);
80     /**<
81 jds 216 * Sets the relation instantiation state of the instantiator.
82     * The flags control when and how how relations are instantiated.
83     * of relations. This allows more control over the sequence in
84     * which instantiation is done, and for so-called 'phased-compilation'.
85     *
86     * Valid flags are the following:
87     * - NORELS No relations should be instantiated
88     * - GBOXRELS Glassbox relations
89     * - BBOXRELS Blackbox relations
90     * - TOKRELS Token relations
91     * - ALLRELS Glassbox, Blackbox, and Token relations
92     * - EXTRELS Glassbox and Blackbox relations
93 jds 54 */
94    
95 aw0a 1 extern unsigned int GetInstantiationRelnFlags(void);
96 jds 54 /**<
97 jds 216 * Retrieves the relation instantiation state of the instantiator.
98     * See SetInstantiationRelnFlags() for more information.
99 aw0a 1 */
100    
101 jds 54 /*
102     * The following define allows us to manage the development phase of
103 aw0a 1 * the ASCEND IV instantiator so that the interface is independent
104     * of the absolute latest compiler hacks.
105     * A production interface should be written to use ONLY Instantiate
106     * and ReInstantiate macros.
107     * Hacker interfaces can define/modify Alt* functions.
108     * It is generally a dumb idea to do mix different types of
109     * Instantiate and ReInstantiate calls on the same instance.
110     */
111 jds 54 #define Instantiate(a,b,c,d) NewInstantiate((a),(b),(c),(d))
112 aw0a 1
113 jds 54 /*
114     * The following define allows us to manage the development phase of
115     * the ASCEND IV instantiator so that the interface is independent
116     * of the absolute latest compiler hacks.
117     * A production interface should be written to use ONLY Instantiate
118     * and ReInstantiate macros.
119     * Hacker interfaces can define/modify Alt* functions.
120     * It is generally a dumb idea to do mix different types of
121     * Instantiate and ReInstantiate calls on the same instance.
122     */
123     #define ReInstantiate(a) NewReInstantiate(a)
124    
125 johnpye 742 extern struct Instance *NewInstantiate(symchar *type, symchar *name,
126 jds 54 int intset, symchar *defmethod);
127     /**<
128 aw0a 1 * This routine will return an instance of type SIM_INST. It will make
129     * an instance of the given type this will be set as the *root* of the
130     * simulation. To access the root of the instance tree use the functions
131     * GetSimulationRoot in instquery.h
132     * intset is only used when you are making an instance of a set type.
133     * defmethod is a METHOD name we are to attempt calling
134     * on the created instance at the END of compilation. If it does not
135     * exist, we will return silently after instantiation.
136 jds 54 * <pre>
137 aw0a 1 * 5 phase Algorithm (approximately. here we ignore failure modes):
138     * Phase 1
139     * level
140     * 1 get type
141     * 1 create sim inst
142     * 1 call real_instantiate_1
143     * 2 call instantiate_model_1
144     * 3 steal and return universal instance of type, or
145     * 3 create model instance head
146     * 3 process pending instances of model
147     * 4 recursive instantiate, marking rels. logrels and whens done
148     * in arrays/bitlists without actually doing them.
149     * 4 if no pendings,
150     * 4 else error message about parts missing,
151     * and constants undefined.
152     * ...return all the way up eventually.
153     * Go back and mark all relation statements undone, put insts pending
154     * Phase 2
155     * 1 call real_instantiate_2
156     * 2 call instantiate_model_2
157     * 3 process pending instances of model
158     * 4 recursive instantiate, doing rels only and
159     * marking logrels and whens as done.
160     * Explain failed relations.
161     * 4 All statements are now determinate,
162     * All variables must be findable or they can't be.
163     * ...return all the way up eventually.
164     * Go back and mark all logrelation statements undone, put insts pending
165     * Phase 3
166     * 1 call real_instantiate_3
167     * 2 call instantiate_model_3
168     * 3 process pending instances of model
169     * 4 recursive instantiate, doing logrels only and
170     * marking whens as done. In phase 3 there are
171     * more than 1 iteration for the instantiation of
172     * logrels, since logrels can reference logrels
173     * (logrels inside conditional statements).
174     * Explain failed logrelations.
175     * 4 All logical variables and referenced rels and
176     * logrels must be findable or they can't be.
177     * ...return all the way up eventually.
178     * Go back and mark all when statements undone, put insts pending
179     * Phase 4
180     * 1 call real_instantiate_4
181     * 2 call instantiate_model_4
182     * 3 process pending instances of model
183     * 4 recursive instantiate, doing whens only.
184     * Explain failed whens.
185     * 4 All conditional variables, rels or logrels
186 jds 54 * referenced by the whens must be findable or
187 aw0a 1 * they can't be
188     * ...return all the way up eventually.
189     * Phase 5
190     * Execution of default statements. (we would like to delete phase 5).
191     * Phase 6
192     * Execute defmethod.
193 jds 54 * </pre>
194 aw0a 1 */
195    
196 johnpye 1063 ASC_DLLSPEC void NewReInstantiate(struct Instance *i);
197 jds 54 /**<
198 aw0a 1 * This routine is used to resume execution of an instance with unexecuted
199     * statements. It will reattempt to execute the unexecuted statement.
200     * If it is able to complete the instance, it will execute the DEFAULT
201     * assignments(assignments to reals and booleans).
202     */
203    
204 johnpye 1063 ASC_DLLSPEC void UpdateInstance(struct Instance *root,
205 jds 54 struct Instance *target,
206     CONST struct StatementList *slist);
207     /**<
208 aw0a 1 * Update instance takes a pointer to the root of a simulation (ie the
209     * instance tree), and will find instance target. It will then apply
210     * the statementlist to the given to the target instance.
211     * This is the start of some experimental encapsulation/parameterization
212     * schemes.
213     */
214    
215     extern struct Instance *InstantiatePatch(symchar *patch,
216 jds 54 symchar *name, int intset);
217     /**<
218 aw0a 1 * Instantiate patch takes the name of a patch that is supposed to be
219     * applied to a type. It partially instantiates the instance, then
220     * applies the patch. It returns the instance created. It uses
221     * UpdateInstance to do the real work. The applicability of the patch is
222     * hence determined by what that function supports.
223     */
224    
225 jds 54 extern void ConfigureInstFromArgs(struct Instance *inst,
226     CONST struct Instance *arginst);
227     /**<
228 aw0a 1 * inst and arginst must be of the same MODEL type.
229     * inst should have NO executed statements -- it should be fresh
230     * from CreateModelInstance.
231     * Neither inst nor arginst should have any parents yet, if ever.
232     * This function copies or references, depending on how declared
233     * in the parameter list of the type for both models, the non-NULL
234     * children of arginst into inst.
235     */
236    
237 johnpye 742 extern void ReConfigureInstFromArgs(struct Instance *inst,
238 jds 54 CONST struct Instance *arginst);
239     /**<
240 aw0a 1 * inst and arginst must be or are about to be of the same MODEL type.
241     * inst should have been created from a less refined version of the type
242     * and is in the process of being refined up to type of arginst.
243     * arginst should not have any parents.
244     * This function copies or references, depending on how declared
245     * in the parameter list of the type for both models, the non-NULL
246     * children of arginst into inst for the slots in inst that are not
247     * already occupied.
248     */
249    
250 jds 54 extern void LinkToParentByPos(struct Instance *parent,
251     struct Instance *child,
252     unsigned long childnum);
253     /**<
254 aw0a 1 * Add child as childnumth child of parent and add parent to child.
255     */
256    
257 jds 54 extern int IncompleteArray(CONST struct Instance *i);
258     /**<
259 aw0a 1 * Given an array instance i, returns 1 if incomplete, 0 if ok.
260     * This means all NONNULL children are done, with the possible
261     * exception of arrays of relations/logical_relations.
262     */
263    
264 johnpye 1066 /* @} */
265    
266 johnpye 67 #endif /* ASC_INSTANTIATE_H */
267 jds 54

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