| 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 |
https://pse.cheme.cmu.edu/wiki/view/Ascend/WebHome |
| 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 |
https://pse.cheme.cmu.edu/svn-view/ascend/code/trunk/LICENSE.txt?view=markup |
| 53 |
*/ |
| 54 |
|
| 55 |
#ifndef ASC_INSTANTIATE_H |
| 56 |
#define ASC_INSTANTIATE_H |
| 57 |
|
| 58 |
/** addtogroup compiler Compiler |
| 59 |
@{ |
| 60 |
*/ |
| 61 |
|
| 62 |
/* |
| 63 |
* Relation instantiation flags. |
| 64 |
* If you add/remove/change these, update the comments in |
| 65 |
* SetInstantiationRelnFlags(). |
| 66 |
*/ |
| 67 |
#define NORELS 0x0 |
| 68 |
#define GBOXRELS 0x1 |
| 69 |
#define BBOXRELS 0x2 |
| 70 |
#define TOKRELS 0x4 |
| 71 |
#define ALLRELS (GBOXRELS | BBOXRELS | TOKRELS) |
| 72 |
#define EXTRELS (GBOXRELS | BBOXRELS) |
| 73 |
|
| 74 |
ASC_DLLSPEC long int g_compiler_counter; |
| 75 |
/**< Unique id of calls to instantiator. */ |
| 76 |
|
| 77 |
extern void SetInstantiationRelnFlags(unsigned int flag); |
| 78 |
/**< |
| 79 |
* Sets the relation instantiation state of the instantiator. |
| 80 |
* The flags control when and how how relations are instantiated. |
| 81 |
* of relations. This allows more control over the sequence in |
| 82 |
* which instantiation is done, and for so-called 'phased-compilation'. |
| 83 |
* |
| 84 |
* Valid flags are the following: |
| 85 |
* - NORELS No relations should be instantiated |
| 86 |
* - GBOXRELS Glassbox relations |
| 87 |
* - BBOXRELS Blackbox relations |
| 88 |
* - TOKRELS Token relations |
| 89 |
* - ALLRELS Glassbox, Blackbox, and Token relations |
| 90 |
* - EXTRELS Glassbox and Blackbox relations |
| 91 |
*/ |
| 92 |
|
| 93 |
extern unsigned int GetInstantiationRelnFlags(void); |
| 94 |
/**< |
| 95 |
* Retrieves the relation instantiation state of the instantiator. |
| 96 |
* See SetInstantiationRelnFlags() for more information. |
| 97 |
*/ |
| 98 |
|
| 99 |
/* |
| 100 |
* The following define allows us to manage the development phase of |
| 101 |
* the ASCEND IV instantiator so that the interface is independent |
| 102 |
* of the absolute latest compiler hacks. |
| 103 |
* A production interface should be written to use ONLY Instantiate |
| 104 |
* and ReInstantiate macros. |
| 105 |
* Hacker interfaces can define/modify Alt* functions. |
| 106 |
* It is generally a dumb idea to do mix different types of |
| 107 |
* Instantiate and ReInstantiate calls on the same instance. |
| 108 |
*/ |
| 109 |
#define Instantiate(a,b,c,d) NewInstantiate((a),(b),(c),(d)) |
| 110 |
|
| 111 |
/* |
| 112 |
* The following define allows us to manage the development phase of |
| 113 |
* the ASCEND IV instantiator so that the interface is independent |
| 114 |
* of the absolute latest compiler hacks. |
| 115 |
* A production interface should be written to use ONLY Instantiate |
| 116 |
* and ReInstantiate macros. |
| 117 |
* Hacker interfaces can define/modify Alt* functions. |
| 118 |
* It is generally a dumb idea to do mix different types of |
| 119 |
* Instantiate and ReInstantiate calls on the same instance. |
| 120 |
*/ |
| 121 |
#define ReInstantiate(a) NewReInstantiate(a) |
| 122 |
|
| 123 |
extern struct Instance *NewInstantiate(symchar *type, symchar *name, |
| 124 |
int intset, symchar *defmethod); |
| 125 |
/**< |
| 126 |
* This routine will return an instance of type SIM_INST. It will make |
| 127 |
* an instance of the given type this will be set as the *root* of the |
| 128 |
* simulation. To access the root of the instance tree use the functions |
| 129 |
* GetSimulationRoot in instquery.h |
| 130 |
* intset is only used when you are making an instance of a set type. |
| 131 |
* defmethod is a METHOD name we are to attempt calling |
| 132 |
* on the created instance at the END of compilation. If it does not |
| 133 |
* exist, we will return silently after instantiation. |
| 134 |
* <pre> |
| 135 |
* 5 phase Algorithm (approximately. here we ignore failure modes): |
| 136 |
* Phase 1 |
| 137 |
* level |
| 138 |
* 1 get type |
| 139 |
* 1 create sim inst |
| 140 |
* 1 call real_instantiate_1 |
| 141 |
* 2 call instantiate_model_1 |
| 142 |
* 3 steal and return universal instance of type, or |
| 143 |
* 3 create model instance head |
| 144 |
* 3 process pending instances of model |
| 145 |
* 4 recursive instantiate, marking rels. logrels and whens done |
| 146 |
* in arrays/bitlists without actually doing them. |
| 147 |
* 4 if no pendings, |
| 148 |
* 4 else error message about parts missing, |
| 149 |
* and constants undefined. |
| 150 |
* ...return all the way up eventually. |
| 151 |
* Go back and mark all relation statements undone, put insts pending |
| 152 |
* Phase 2 |
| 153 |
* 1 call real_instantiate_2 |
| 154 |
* 2 call instantiate_model_2 |
| 155 |
* 3 process pending instances of model |
| 156 |
* 4 recursive instantiate, doing rels only and |
| 157 |
* marking logrels and whens as done. |
| 158 |
* Explain failed relations. |
| 159 |
* 4 All statements are now determinate, |
| 160 |
* All variables must be findable or they can't be. |
| 161 |
* ...return all the way up eventually. |
| 162 |
* Go back and mark all logrelation statements undone, put insts pending |
| 163 |
* Phase 3 |
| 164 |
* 1 call real_instantiate_3 |
| 165 |
* 2 call instantiate_model_3 |
| 166 |
* 3 process pending instances of model |
| 167 |
* 4 recursive instantiate, doing logrels only and |
| 168 |
* marking whens as done. In phase 3 there are |
| 169 |
* more than 1 iteration for the instantiation of |
| 170 |
* logrels, since logrels can reference logrels |
| 171 |
* (logrels inside conditional statements). |
| 172 |
* Explain failed logrelations. |
| 173 |
* 4 All logical variables and referenced rels and |
| 174 |
* logrels must be findable or they can't be. |
| 175 |
* ...return all the way up eventually. |
| 176 |
* Go back and mark all when statements undone, put insts pending |
| 177 |
* Phase 4 |
| 178 |
* 1 call real_instantiate_4 |
| 179 |
* 2 call instantiate_model_4 |
| 180 |
* 3 process pending instances of model |
| 181 |
* 4 recursive instantiate, doing whens only. |
| 182 |
* Explain failed whens. |
| 183 |
* 4 All conditional variables, rels or logrels |
| 184 |
* referenced by the whens must be findable or |
| 185 |
* they can't be |
| 186 |
* ...return all the way up eventually. |
| 187 |
* Phase 5 |
| 188 |
* Execution of default statements. (we would like to delete phase 5). |
| 189 |
* Phase 6 |
| 190 |
* Execute defmethod. |
| 191 |
* </pre> |
| 192 |
*/ |
| 193 |
|
| 194 |
ASC_DLLSPEC void NewReInstantiate(struct Instance *i); |
| 195 |
/**< |
| 196 |
* This routine is used to resume execution of an instance with unexecuted |
| 197 |
* statements. It will reattempt to execute the unexecuted statement. |
| 198 |
* If it is able to complete the instance, it will execute the DEFAULT |
| 199 |
* assignments(assignments to reals and booleans). |
| 200 |
*/ |
| 201 |
|
| 202 |
ASC_DLLSPEC void UpdateInstance(struct Instance *root, |
| 203 |
struct Instance *target, |
| 204 |
CONST struct StatementList *slist); |
| 205 |
/**< |
| 206 |
* Update instance takes a pointer to the root of a simulation (ie the |
| 207 |
* instance tree), and will find instance target. It will then apply |
| 208 |
* the statementlist to the given to the target instance. |
| 209 |
* This is the start of some experimental encapsulation/parameterization |
| 210 |
* schemes. |
| 211 |
*/ |
| 212 |
|
| 213 |
extern struct Instance *InstantiatePatch(symchar *patch, |
| 214 |
symchar *name, int intset); |
| 215 |
/**< |
| 216 |
* Instantiate patch takes the name of a patch that is supposed to be |
| 217 |
* applied to a type. It partially instantiates the instance, then |
| 218 |
* applies the patch. It returns the instance created. It uses |
| 219 |
* UpdateInstance to do the real work. The applicability of the patch is |
| 220 |
* hence determined by what that function supports. |
| 221 |
*/ |
| 222 |
|
| 223 |
extern void ConfigureInstFromArgs(struct Instance *inst, |
| 224 |
CONST struct Instance *arginst); |
| 225 |
/**< |
| 226 |
* inst and arginst must be of the same MODEL type. |
| 227 |
* inst should have NO executed statements -- it should be fresh |
| 228 |
* from CreateModelInstance. |
| 229 |
* Neither inst nor arginst should have any parents yet, if ever. |
| 230 |
* This function copies or references, depending on how declared |
| 231 |
* in the parameter list of the type for both models, the non-NULL |
| 232 |
* children of arginst into inst. |
| 233 |
*/ |
| 234 |
|
| 235 |
extern void ReConfigureInstFromArgs(struct Instance *inst, |
| 236 |
CONST struct Instance *arginst); |
| 237 |
/**< |
| 238 |
* inst and arginst must be or are about to be of the same MODEL type. |
| 239 |
* inst should have been created from a less refined version of the type |
| 240 |
* and is in the process of being refined up to type of arginst. |
| 241 |
* arginst should not have any parents. |
| 242 |
* This function copies or references, depending on how declared |
| 243 |
* in the parameter list of the type for both models, the non-NULL |
| 244 |
* children of arginst into inst for the slots in inst that are not |
| 245 |
* already occupied. |
| 246 |
*/ |
| 247 |
|
| 248 |
extern void LinkToParentByPos(struct Instance *parent, |
| 249 |
struct Instance *child, |
| 250 |
unsigned long childnum); |
| 251 |
/**< |
| 252 |
* Add child as childnumth child of parent and add parent to child. |
| 253 |
*/ |
| 254 |
|
| 255 |
extern int IncompleteArray(CONST struct Instance *i); |
| 256 |
/**< |
| 257 |
* Given an array instance i, returns 1 if incomplete, 0 if ok. |
| 258 |
* This means all NONNULL children are done, with the possible |
| 259 |
* exception of arrays of relations/logical_relations. |
| 260 |
*/ |
| 261 |
|
| 262 |
/* @} */ |
| 263 |
|
| 264 |
#endif /* ASC_INSTANTIATE_H */ |
| 265 |
|
Parent Directory
| 
Revision Log