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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 2316 - (show annotations) (download) (as text)
Tue Dec 14 05:42:21 2010 UTC (13 years, 7 months ago) by jpye
File MIME type: text/x-chdr
File size: 10197 byte(s)
Documentation refactoring; trying to make the doxygen documentation generated for libascend a little more
navigable.
1 /* ASCEND modelling environment
2 Copyright (C) 2006 Carnegie Mellon University
3 Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
4
5 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
10 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 http://ascendwiki.cheme.cmu.edu/
47
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 http://ascendcode.cheme.cmu.edu/viewvc.cgi/code/branches/extfn/LICENSE.txt?view=markup
53 */
54
55 #ifndef ASC_INSTANTIATE_H
56 #define ASC_INSTANTIATE_H
57
58 #include "stattypes.h"
59
60 /** @addtogroup compiler_inst Compiler Instance Hierarchy
61 @{
62 */
63
64 /*
65 * Relation instantiation flags.
66 * If you add/remove/change these, update the comments in
67 * SetInstantiationRelnFlags().
68 */
69 #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 ASC_DLLSPEC long int g_compiler_counter;
77 /**< Unique id of calls to instantiator. */
78
79 extern void SetInstantiationRelnFlags(unsigned int flag);
80 /**<
81 * 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 */
94
95 extern unsigned int GetInstantiationRelnFlags(void);
96 /**<
97 * Retrieves the relation instantiation state of the instantiator.
98 * See SetInstantiationRelnFlags() for more information.
99 */
100
101 /*
102 * The following define allows us to manage the development phase of
103 * 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 #define Instantiate(a,b,c,d) NewInstantiate((a),(b),(c),(d))
112
113 /*
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 extern struct Instance *NewInstantiate(symchar *type, symchar *name,
126 int intset, symchar *defmethod);
127 /**<
128 * 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 * <pre>
137 * 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 * referenced by the whens must be findable or
187 * 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 * </pre>
194 */
195
196 ASC_DLLSPEC void NewReInstantiate(struct Instance *i);
197 /**<
198 * 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 ASC_DLLSPEC void UpdateInstance(struct Instance *root,
205 struct Instance *target,
206 CONST struct StatementList *slist);
207 /**<
208 * 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 symchar *name, int intset);
217 /**<
218 * 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 extern void ConfigureInstFromArgs(struct Instance *inst,
226 CONST struct Instance *arginst);
227 /**<
228 * 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 extern void ReConfigureInstFromArgs(struct Instance *inst,
238 CONST struct Instance *arginst);
239 /**<
240 * 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 extern void LinkToParentByPos(struct Instance *parent,
251 struct Instance *child,
252 unsigned long childnum);
253 /**<
254 * Add child as childnumth child of parent and add parent to child.
255 */
256
257 extern int IncompleteArray(CONST struct Instance *i);
258 /**<
259 * 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 /* @} */
265
266 #endif /* ASC_INSTANTIATE_H */
267

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