/[ascend]/trunk/base/generic/compiler/instquery.h
ViewVC logotype

Contents of /trunk/base/generic/compiler/instquery.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 521 - (show annotations) (download) (as text)
Fri Apr 21 05:35:59 2006 UTC (14 years, 9 months ago) by johnpye
File MIME type: text/x-chdr
File size: 14167 byte(s)
Getting the modular version the Tcl/Tk GUI working. In progress.
1 /* ASCEND modelling environment
2 Copyright (C) 1996 Ben Allan
3 Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly
4 Copyright (C) 2006 Carnegie Mellon University
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 *//** @file
21 Ascend Instance Miscellaneous Queries.
22
23 based on instance.c
24
25 Requires:
26 #include "utilities/ascConfig.h"
27 #include "instance_enum.h"
28 #include "compiler.h"
29 *//*
30 by Tom Epperly & Ben Allan
31 8/16/89
32 Version: $Revision: 1.13 $
33 Version control file: $RCSfile: instquery.h,v $
34 Date last modified: $Date: 1998/02/05 16:36:48 $
35 Last modified by: $Author: ballan $
36 */
37
38 #ifndef ASC_INSTQUERY_H
39 #define ASC_INSTQUERY_H
40
41 #include <utilities/ascConfig.h>
42
43 /*
44 * The following InterfacePtr functions are to support a global,
45 * persistent client (most likely a GUI) that for some reason
46 * insists (brain dead idiot) that it must decorate the instance
47 * tree with persistent pointers to information packets of its own
48 * devising.
49 * These functions are used by the compiler to handle data an
50 * interface may have left hanging off the instance when an incremental
51 * compile (delete, move, merge) action is in progress. They should never
52 * OTHERWISE be active.
53 *
54 * For a more robust, transient protocol see instance_io.h.
55 */
56
57 extern void (*InterfacePtrDelete)();
58 /**<
59 * This global variable should be provided by the interface. It is a
60 * pointer to a void function(procedure). This procedure will be called
61 * when an instance is deleted. Its purpose is to dispose of the
62 * interface ptr, in other words to clean up/or save the object that the
63 * interfaceptr is looking at. Below is a trivial example. The instance
64 * pointer i may not be a complete instance. So you should not call
65 * any instance routines on it.
66 * <pre>
67 * void InterfacePtrDeleteProc(i,ptr)
68 * struct Instance *i;
69 * struct InterfacePtr *ptr;
70 * {
71 * if (ptr!=NULL) free((VOIDPTR)ptr);
72 * }
73 * main(argc,argv)
74 * {
75 * ....other initialization junk....;
76 * InterfacePtrDelete = InterfacePtrDeleteProc;
77 * ...etc...;
78 * }
79 * </pre>
80 */
81
82 extern void (*InterfaceNotify)();
83 /**<
84 * This global variable should be provided by the interface. It is a
85 * pointer to a void function(procedure). This procedure will be called
86 * when an instance is moved in memory. It is provided in case the
87 * interface has a link to the instance. The old pointer should not be
88 * dereferenced. Below is a trivial example:
89 * <pre>
90 * void InterfaceNotifyProc(ptr,old,new)
91 * struct InterfacePtr *ptr;
92 * struct Instance *old,*new; the old and new address of the instance
93 * {
94 * if(ptr!=NULL){
95 * ptr->inst = new;
96 * }
97 * }
98 *
99 * main(argc,argv)
100 * {
101 * ...other initialization junk...;
102 * InterfaceNotify = InterfaceNotifyProc;
103 * ...etc...;
104 * }
105 * </pre>
106 */
107
108 extern void (*InterfacePtrATS)();
109 /**<
110 * This global variable should be provided by the interface. It is a
111 * pointer to a void function(procedure). The function will be called
112 * when two instances are going to be ARE_THE_SAME'd. The function's
113 * job is to perform any actions that the interface might want done.
114 * It should not destroy any memory. This will be done by destroy
115 * Instance.
116 * Below is a trivial example:
117 * <pre>
118 * void InterfacePtrATSFunc(i1,i2)
119 * struct Instance *i1, *i2;
120 * {
121 * struct InterfacePtr *ptr1,*ptr2;
122 * if (i1 && i2){
123 * ptr1 = GetInterfacePtr(i1);
124 * ptr2 = GetInterfacePtr(i2);
125 * if (ptr2!=NULL) {
126 * if (ptr1!=NULL) {
127 * }
128 * }
129 * }
130 * main(argc,argv)
131 * {
132 * ....other initialization junk...;
133 * InterfacePtrATS = InterfacePtrATSFunc;
134 * ...etc...;
135 * }
136 * </pre>
137 */
138
139 /**<
140 * General instance interogation routines
141 */
142
143 #ifndef NDEBUG
144 #define InstanceKind(i) InstanceKindF(i)
145 #else
146 #define InstanceKind(i) ((i==NULL) ? ERROR_INST : ((struct Instance *)(i))->t)
147 #endif
148 /**<
149 * Return the enumerated inst_t that indicates the type of Instance* i.
150 * @see InstanceKindF()
151 */
152 ASC_DLLSPEC(enum inst_t) InstanceKindF(CONST struct Instance *i);
153 /**<
154 * <!-- enum inst_t InstanceKind(i); -->
155 * <!-- const struct Instance *i; -->
156 *
157 * <!-- Return the enumerated type that indicates the type of i. -->
158 * Implementation function for InstanceKind(). Do not use
159 * this function directly - use InstanceKind() instead.
160 */
161
162 #define IsConstantInstance(i) ((i)->t & ICONS)
163 /**< Returns TRUE (some value >0) if i is a constant instance. */
164 #define IsFundamentalInstance(i) ((i)->t & IFUND)
165 /**< Returns TRUE (some value >0) if i is a fundamental instance. */
166 #define IsAtomicInstance(i) ((i)->t & IATOM)
167 /**< Returns TRUE (some value >0) if i is an atomic instance. */
168 #define IsCompoundInstance(i) ((i)->t & ICOMP)
169 /**< Returns TRUE (some value >0) if i is a compound instance. */
170 #define IsArrayInstance(i) ((i)->t & IARR)
171 /**< Returns TRUE (some value >0) if i is an array instance. */
172 #define IsChildlessInstance(i) ((i)->t & ICHILDLESS)
173 /**< Returns TRUE (some value >0) if i is a childless instance. */
174 /**<
175 * <!-- int Is*Instance(i); -->
176 * <!-- const struct Instance *i; -->
177 * <!-- TRUE (some value >0) if i is of the instance class indicated.-->
178 */
179
180 extern unsigned long InstanceDepth(CONST struct Instance *i);
181 /**<
182 * <!-- unsigned long InstanceDepth(i) -->
183 * <!-- const struct Instance *i; -->
184 * Return the longest distance between i and root. The depth of NULL is 0.
185 * The root instance is at depth 1.
186 */
187
188 extern unsigned long InstanceShortDepth(CONST struct Instance *i);
189 /**<
190 * <!-- unsigned long InstanceShortDepth(i) -->
191 * <!-- const struct Instance *i; -->
192 * Return the shortest distance between i and root. The depth of NULL
193 * is 0, and the depth of root is 1.
194 */
195
196
197 extern void SetNextCliqueMember(struct Instance *i, struct Instance *ptr);
198 /**<
199 * <!-- SetNextCliqueMember(i,ptr) -->
200 * Sets i->alike_ptr to ptr for types that have alike_ptrs.
201 * Exits on types that don't or bad input.
202 * Instantiator use only! Clients should never ever touch this.
203 * This is not an intelligent function.
204 */
205
206 ASC_DLLSPEC(struct Instance*) NextCliqueMember(CONST struct Instance *i);
207 /**<
208 * <!-- struct Instance *NextCliqueMember(i); -->
209 * <!-- const struct Instance *i; -->
210 *
211 * This is defined to give clients access to the cliques(ARE_ALIKE) links
212 * between instances. Each instance has a clique pointer which points to
213 * the next member of the clique list. These pointers form a circularly
214 * linked list. The following loop can be used to access each member of
215 * the clique.
216 * <pre>
217 * struct Instance *i,*start;
218 * (* i points the instance whose clique is to be examined *)
219 * start = i;
220 * do {
221 * (* insert your code here *)
222 * i = NextCliqueMember(i);
223 * } while(i!=start);
224 * </pre>
225 * This loop will execute the inserted code for each member of the clique.
226 * This function can be call on *any* type of instance.
227 */
228
229 ASC_DLLSPEC(VOIDPTR) GetInterfacePtr(CONST struct Instance *i);
230 /**<
231 * <!-- VOIDPTR GetInterfacePtr(i) -->
232 * <!-- const struct Instance *i; -->
233 * Return the interface pointer. The compiler initializes this to NULL
234 * when it creates an instance of the following kinds, and hence should
235 * only be called on them.
236 *
237 * - SIM_INST
238 * - MODEL_INST
239 * - SET_ATOM_INST
240 * - REL_INST
241 * - LREL_INST
242 * - WHEN_INST
243 * - REAL_ATOM_INST
244 * - INTEGER_ATOM_INST
245 * - SYMBOL_ATOM_INST
246 * - BOOLEAN_ATOM_INST
247 * - ARRAY_ENUM_INST
248 * - ARRAY_INT_INST
249 * - REAL_CONSTANT_INST
250 * - INTEGER_CONSTANT_INST
251 * - SYMBOL_CONSTANT_INST
252 * - BOOLEAN_CONSTANT_INST
253 *
254 * Those not supported are:
255 * - (atom children)
256 * - REAL_INST
257 * - INTEGER_INST
258 * - SYMBOL_INST
259 * - BOOLEAN_INST
260 * - SET_INST
261 *
262 * It is up to the interface to give this pointer meaning.
263 * In a multiple interface environment this pointer needs to be
264 * managed carefully. Any really sane environment will not use
265 * this pointer except in a transient fashion with Push/Pop in
266 * instance_io.h.
267 */
268
269 ASC_DLLSPEC(void) SetInterfacePtr(struct Instance *i, VOIDPTR c);
270 /**<
271 * <!-- void SetInterfacePtr(i,c) -->
272 * <!-- struct Instance *i; -->
273 * <!-- VOIDPTR c; -->
274 * Set the interface pointer. The interface must set and maintain this
275 * pointer. See the note for GetInterfacePtr about applicability of this
276 * function.
277 */
278
279 extern unsigned int GetAnonFlags(CONST struct Instance *i);
280 /**<
281 * <!-- unsigned int GetAnonFlags(i) -->
282 * <!-- const struct Instance *i; -->
283 * Returns the flags associated with an instance. This is a utility
284 * service provided for clients who need access to flags associated with
285 * an instance. These flags may also be set with the below function.
286 * Works for all instance kinds except subatomic ones.
287 */
288
289 extern void SetAnonFlags(struct Instance *i, unsigned int flags);
290 /**<
291 * <!-- void SetAnonFlags(i,flags) -->
292 * <!-- const struct Instance *i; -->
293 * <!-- unsigned int flags; -->
294 * Sets the flags associated with an instance. This is a utility
295 * service provided for clients who need access to flags associated with
296 * Works for all instance kinds except subatomic ones.
297 */
298
299 extern struct BitList *InstanceBitList(CONST struct Instance *i);
300 /**<
301 * <!-- struct BitList *InstanceBitList(i) -->
302 * <!-- const struct Instance *i; -->
303 * Return the bit list which indicates which statements have and have not
304 * been executed. NULL indicates that there aren't any unexecuted statements.
305 * Only MODEL_INST have bitlists.
306 */
307
308 /*
309 * Instance querying routines
310 *
311 * These are general instance querying routines.
312 */
313
314 extern symchar *InstanceType(CONST struct Instance *i);
315 /**<
316 * <!-- symchar *InstanceType(i) -->
317 * <!-- CONST struct Instance *i; -->
318 * Return a string indicating the type of instance i. This works for
319 * all types of instances. It returns the blank string for arrays and
320 * relations though.
321 */
322
323 ASC_DLLSPEC(struct TypeDescription*) InstanceTypeDesc(CONST struct Instance *i);
324 /**<
325 * <!-- struct TypeDescription *InstanceTypeDesc(i) -->
326 * <!-- const struct Instance *i; -->
327 * Return the instance's type description. This returns NULL for fundamental
328 * instances.
329 */
330
331 extern unsigned long InstanceIndirected(CONST struct Instance *i);
332 /**<
333 * Returns the indirected field of array instances and LONG_MAX
334 * for other kinds of instances.
335 * Does not tolerate NULL.
336 */
337
338 extern unsigned long InstanceSize(CONST struct Instance *i);
339 /**<
340 * <!-- unsigned long InstanceSize(i); -->
341 * <!-- CONST struct Instance *i; -->
342 * Returns the number of bytes chargeable to the given instance i.
343 * This is not recursive.
344 * Fundamental types (which occur only as children of atoms/relations)
345 * are charged to their parent atom/relation and hence have a 'cost'
346 * of 0 according to this function.
347 * Symbol table, set_t, and dimen items associated with instances
348 * are not charged.
349 */
350
351 #define InstanceUniversal(i) \
352 (GetUniversalFlag(InstanceTypeDesc(i)) != 0)
353 /**<
354 * <!-- macro InstanceUniversal(i); -->
355 * Returns TRUE if i is a UNIVERSAL instance.
356 */
357
358 extern int IntegerSetInstance(CONST struct Instance *i);
359 /**<
360 * <!-- int IntegerSetInstance(i) -->
361 * <!-- const struct Instance *i; -->
362 * It will return true if the set is of integers and false otherwise.
363 * This should only be called on set instances.
364 */
365
366 ASC_DLLSPEC(symchar *) GetSimulationName(struct Instance *i);
367 /**<
368 * <!-- const char *GetSimulationName(i); -->
369 * <!-- struct Instance *i; -->
370 * Returns the name of the simulation instance.
371 * i must be a SIM_INST kind.
372 */
373
374 extern struct gl_list_t *FindSimulationAncestors(struct Instance *i);
375 /**<
376 * <!-- sl = FindSimulationAncestors(i); -->
377 * Returns a list of all the simulation ancestors of i.
378 * Caller should destroy the list (but obviously not its content).
379 */
380
381 ASC_DLLSPEC(struct Instance*) GetSimulationRoot(struct Instance *i);
382 /**<
383 * <!-- struct Instance *GetSimulationRoot(i); -->
384 * <!-- struct Instance *i; -->
385 * Returns the root instance of the simulation. This is where most if not
386 * all useful queries of a simulation should be based.
387 * i must be a sim instance.
388 */
389
390 #endif /* ASC_INSTQUERY_H */
391

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