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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 236 - (show annotations) (download) (as text)
Mon Jan 30 06:09:52 2006 UTC (14 years, 6 months ago) by johnpye
File MIME type: text/x-chdr
File size: 19027 byte(s)
Minor #ifdef changes
1 /*
2 * Instance Output Routines
3 * by Tom Epperly
4 * Created: 2/8/90
5 * Version: $Revision: 1.21 $
6 * Version control file: $RCSfile: instance_io.h,v $
7 * Date last modified: $Date: 1998/01/11 17:03:34 $
8 * Last modified by: $Author: ballan $
9 *
10 * This file is part of the Ascend Language Interpreter.
11 *
12 * Copyright (C) 1990, 1993, 1994 Thomas Guthrie Weidner Epperly
13 * Copyright 1996 Benjamin Andrew Allan
14 *
15 * The Ascend Language Interpreter is free software; you can redistribute
16 * it and/or modify it under the terms of the GNU General Public License as
17 * published by the Free Software Foundation; either version 2 of the
18 * License, or (at your option) any later version.
19 *
20 * The Ascend Language Interpreter is distributed in hope that it will be
21 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
22 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23 * General Public License for more details.
24 *
25 * You should have received a copy of the GNU General Public License
26 * along with the program; if not, write to the Free Software Foundation,
27 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
28 * COPYING.
29 */
30
31 /** @file
32 * Instance Output Routines.
33 * <pre>
34 * When #including instance_io.h, make sure these files are #included first:
35 * #include "utilities/ascConfig.h"
36 * #include "general/dstring.h"
37 * #include "compiler/compiler.h"
38 * #include "compiler/symtab.h"
39 * #include "compiler/instance_enum.h"
40 * </pre>
41 */
42
43 #ifndef ASC_INSTANCE_IO_H
44 #define ASC_INSTANCE_IO_H
45
46 /**
47 * struct NameNode is used by the AllPaths() and WriteAliases() routines to
48 * keep track of an instance and which child name is used for a
49 * particular name chain.
50 */
51 struct NameNode {
52 CONST struct Instance *inst;
53 unsigned long index;
54 };
55
56 extern struct gl_list_t *ShortestPath(CONST struct Instance *inst,
57 CONST struct Instance *ref,
58 /* CONST */ unsigned int height,
59 /* CONST */ unsigned int best);
60 /**<
61 * <!-- struct gl_list_t *ShortestPath(inst,ref,height,best) -->
62 * <!-- const struct Instance *inst, *ref; -->
63 * <!-- const unsigned int height,best; -->
64 * Collect all instances in path connecting inst with ref and returns
65 * them in a list. If path doesn't exist, it returns NULL. Path will
66 * be such that the smallest number of intermediate instances are used.
67 * This is a recursive function so send in 0,UINT_MAX as the last two
68 * arguments to initiate the call.<br><br>
69 *
70 * This returns a list of pointers to instances, and it should be
71 * deallocated with gl_destroy(path).
72 */
73
74 extern struct gl_list_t *AllPaths(CONST struct Instance *inst);
75 /**<
76 * <!-- struct gl_list_t *AllPaths(inst) -->
77 * <!-- const struct Instance *i; -->
78 *
79 * AllPaths makes and returns a list of lists of NameNode structures.
80 * Each member of list AllPaths returns is a path from the given instance
81 * to root.<br><br>
82 *
83 * How to deallocate the result of AllPaths:
84 * Here is an example of how to deallocate the results. Use it or
85 * something equivalent.
86 * <pre>
87 * struct gl_list_t *paths,*path;
88 * paths = AllPaths(i);
89 * ....whatever....
90 * for(c=1;c <= gl_length(paths);c++){
91 * gl_free_and_destroy(gl_fetch(paths,c));
92 * }
93 * gl_destroy(paths);
94 * </pre>
95 */
96
97 extern struct gl_list_t *ISAPaths(CONST struct gl_list_t *pathlist);
98 /**<
99 * <!-- struct gl_list_t *ISAPaths(pathlist) -->
100 * <!-- struct gl_list_t *pathlist, *list; -->
101 * <!-- isalist = ISAPaths(pathlist); -->
102 *
103 * Given pathlist, the output of AllPaths, returns the list of
104 * names which are real: that is names which have been constructed
105 * without ALIASES or WILL_BE's intermediate.
106 * The list returned contains pointers to elements of the pathlist given,
107 * so it should be destroyed with gl_destroy(isalist) before the
108 * AllPaths destruction is applied to pathlist.
109 * In well written MODELs, the isalist returned will be one long.
110 */
111
112 extern int WriteInstanceName(FILE *f,
113 CONST struct Instance *i,
114 CONST struct Instance *ref);
115 /**<
116 * <!-- int WriteInstanceName(f,i,ref) -->
117 * <!-- const struct Instance *i,*ref; -->
118 * <!-- FILE *f; -->
119 * Print the instance's name to the specified file. The name that is
120 * printed is derived from the shortest path between i and ref. If
121 * ref is NULL, the shortest path to root is used. The number of
122 * characters written is returned, to assist in pretty printing or
123 * line breaking.
124 */
125
126 extern void WriteInstanceNameDS(Asc_DString * dsPtr,
127 CONST struct Instance *i,
128 CONST struct Instance *ref);
129 /**<
130 * <!-- WriteInstanceNameDS(dsPtr,i,ref) -->
131 * <!-- const struct Instance *i,*ref; -->
132 * <!-- Asc_DString *dsPtr; -->
133 * Print the instance's name to the specified dstring. The name that is
134 * printed is derived from the shortest path between i and ref. If
135 * ref is NULL, the shortest path to root is used.
136 * This does not put a . in at the beginning of a name, so you cannot
137 * build up proper names in a DS with it. It writes proper
138 * relative names instead, where the context is assumed to be ref.
139 */
140
141 extern char *WriteInstanceNameString(CONST struct Instance *i,
142 CONST struct Instance *ref);
143 /**<
144 * <!-- result = WriteInstanceNameString(i,ref) -->
145 * <!-- const struct Instance *i,*ref; -->
146 * <!-- char *result; -->
147 * Return a string (that the user must destroy eventually). The name that is
148 * printed is derived from the shortest path between i and ref. If
149 * ref is NULL, the shortest path to root is used.
150 * The name will not begin with a ., even if the path ref
151 * is not a simulation or NULL.
152 */
153
154 extern int WriteAnyInstanceName(FILE *f, struct Instance *i);
155 /**<
156 * <!-- int WriteAnyInstanceName(f,i); -->
157 * <!-- struct Instance *i; -->
158 * <!-- FILE *f; -->
159 * Print the instance's name to the specified file.
160 * Very similar to WriteInstanceName(). The name that is
161 * printed is derived from *any* path from i to NULL.
162 * This function was designed for speed, rather than good
163 * looks, and may be used for bulk writing of instance names. Returns
164 * the count of characters written.
165 */
166
167 extern unsigned long CountAliases(CONST struct Instance *i);
168 /**<
169 * <!-- unsigned long CountAliases(i) -->
170 * Count all the known names of the instance given.
171 */
172
173 extern unsigned long CountISAs(CONST struct Instance *i);
174 /**<
175 * <!-- unsigned long CountISAs(i) -->
176 * Count the names with which the instance given was created.
177 */
178
179 extern void WriteAliases(FILE *f, CONST struct Instance *i);
180 /**<
181 * <!-- void WriteAliases(f,i) -->
182 * <!-- FILE *f; -->
183 * <!-- struct Instance *i; -->
184 * Print all the instance's names to the specified file.
185 */
186
187 extern void WriteISAs(FILE *f, CONST struct Instance *i);
188 /**<
189 * <!-- void WriteISAs(f,i) -->
190 * <!-- FILE *f; -->
191 * <!-- struct Instance *i; -->
192 * Print the instance's constructed names to the specified file.
193 * (there may not be any in bizarre circumstances).
194 */
195
196 extern struct gl_list_t *WriteAliasStrings(CONST struct Instance *i);
197 /**<
198 * <!-- aliases=WriteAliasStrings(i); -->
199 * <!-- struct Instance *i; -->
200 * <!-- struct gl_list_t *aliases; -->
201 *
202 * Return a list of strings of all the possible instance names for i.
203 * The list AND the strings on it are the user's responsibility to destroy.
204 * gl_free_and_destroy(aliases) would be convenient.
205 */
206
207 extern struct gl_list_t *WriteISAStrings(CONST struct Instance *i);
208 /**<
209 * <!-- aliases=WriteISAStrings(i); -->
210 * <!-- struct Instance *i; -->
211 * <!-- struct gl_list_t *aliases; -->
212 *
213 * Return a list of strings of all the constructed instance names for i.
214 * Names created by WILL_BE/ALIASES are not returned.
215 * Under bizarre circumstances, the list may be empty.
216 * The list AND the strings on it are the user's responsibility to destroy.
217 * gl_free_and_destroy(aliases) would be convenient.
218 *
219 * @bug Returns IS_A'd parents as well. need to hunt down the path
220 * of instances being tracked and see if they were passed the original
221 * instance we queried about.
222 */
223
224 extern void WriteClique(FILE *f, CONST struct Instance *i);
225 /**<
226 * <!-- void WriteClique(f,i) -->
227 * <!-- FILE *f; -->
228 * <!-- struct Instance *i; -->
229 * Print all the instance's clique members.
230 */
231
232 extern void WriteInstance(FILE *f, CONST struct Instance *i);
233 /**<
234 * <!-- void WriteInstance(f,i) -->
235 * <!-- FILE *f; -->
236 * <!-- struct Instance *i; -->
237 * Print the information contained in i.
238 */
239
240 extern int WritePath(FILE *f, CONST struct gl_list_t *path);
241 /**<
242 * <!-- l = WritePath(f,path); -->
243 * <!-- FILE *f; -->
244 * <!-- CONST struct gl_list_t *path; -->
245 * <!-- int l; -->
246 * Returns the number of name pieces written.
247 */
248
249 extern char *WritePathString(CONST struct gl_list_t *path);
250 /**<
251 * <!-- str = WritePathString(path); -->
252 * <!-- CONST struct gl_list_t *path; -->
253 * <!-- char *str; -->
254 * Returns the path in a string. The caller should free the string when
255 * done with it.
256 */
257
258 extern void SaveInstance(FILE *f, CONST struct Instance *inst, int dorelations);
259 /**<
260 * <!-- void SaveInstance(fp,inst,dorelations); -->
261 * <!-- FILE *fp, -->
262 * <!-- const struct Instance *inst; -->
263 * <!-- int dorelations; -->
264 * Save the information contained in inst in a format that will allow
265 * efficient reconstruction of the instance. This will be followed up
266 * with RestoreInstance.
267 */
268
269 extern void WriteInstanceList(struct gl_list_t *list);
270 /**<
271 * <!-- void WriteInstanceList(list); -->
272 * <!-- struct gl_list_t *list; -->
273 * This is a debugging aid and not intended for general use.
274 * It assumes that this is a list of instances and will try to write
275 * out the instance name for each element on the list.
276 */
277
278 extern void WriteAtomValue(FILE *fp, CONST struct Instance *i);
279 /**<
280 * <!-- void WriteAtomValue(fp,i); -->
281 * <!-- FILE *fp; -->
282 * <!-- CONST struct Instance *i; -->
283 * Write an instance value to fp.
284 */
285
286 typedef VOIDPTR (*IPFunc)(struct Instance *,VOIDPTR);
287 /**<
288 * This is the type of function you should write for use with
289 * PushInterfacePtrs(). It will be applied to the instances in the
290 * tree. If your function returns anything other than NULL, then
291 * we will make the instance's interface pointer be the pointer you
292 * returned.<br><br>
293 * In constructing instance bridges it is good to be able to attach
294 * temporary data structures to instances during construction. These
295 * temporary structures should not be left laying about. Rather, you
296 * should call the following Push and Pop functions like so:
297 * <pre>
298 * int build_my_bridge(struct Instance *i, ...)
299 * {
300 * struct gl_list_t *oldips = NULL;
301 * oldips = PushInterfacePtrs(i,YourCreateFunc,0,1,vp);
302 * Do whatever you need to here, making the assumption
303 * that the instance's YourFunc was interested in have
304 * the data created by YourFunc in their interface_ptrs.
305 * PopInterfacePtrs(oldips,YourDestroyFunc,vp);
306 * }
307 * </pre>
308 * If everyone follows this rule, it is easy to see that we can
309 * support nested transient clients so long as they don't go
310 * sneaking around in each others guts. Abstraction is your friend.
311 * Clients, such as a horribly sloppy GUI, may work without using the
312 * push and pop functions, but sanity insurance is then THAT client's
313 * responsibility and none of ours.
314 */
315
316 extern struct gl_list_t *PushInterfacePtrs(struct Instance *i,
317 IPFunc ipcreatef,
318 unsigned long int iest,
319 int visitorder,
320 VOIDPTR vp);
321 /**<
322 * <!-- oldips = PushInterfacePtrs(i,ipcreatef,iest,visitorder,vp); -->
323 * <!-- struct Instance *i; -->
324 * <!-- IPFunc ipcreatef; -->
325 * <!-- unsigned long iest; -->
326 * <!-- int visitorder; -->
327 * <!-- struct gl_list_t *oldips; -->
328 * <!-- VOIDPTR vp; -->
329 *
330 * Creates a gl_list and returns it to you.
331 * It contains the information needed to restore the state of the
332 * instance interface pointers ipcreatef returns non-NULL values for.
333 * Remember that not all instance types have interface pointers.
334 * Push does not visit subatomic instances (ATOM/reln children).<br><br>
335 * The algorithm is as follows:
336 * - Create an initial gl_list of capacity = 2 * iest (we keep pairs).
337 * (Thus, iest allows you to give us a hint about how many insts
338 * you expect to be interested in. iest need not be a perfect hint.)
339 * - Visit the instance tree (visitorder is treated as order is in
340 * the VisitInstanceTree function). Each place that ipcreatef
341 * returns non-NULL, save ip state information in the gl_list and
342 * replace it in the instance with your ip data.
343 * - Return gllist.
344 * The gl_list returned here can only be safely destroyed by a call
345 * following to PopInterfacePtrs.
346 * The gl_list returned may be NULL if malloc fails or you forgot
347 * ipcreatef.<br><br>
348 *
349 * ASSUMPTION: For the duration of the Push/Pop sequence you will be
350 * taking NO compiler action that deletes, relocates, or merges any
351 * part of the subtree rooted at instance i.
352 * Violate this rule and we die most probably.
353 * This is not a hard assumption to meet in single thread code.
354 */
355
356 typedef VOIDPTR (*IPDeleteFunc)(struct Instance *, VOIDPTR, VOIDPTR);
357 /**<
358 * <!-- func(i,ipdata,vp); -->
359 * <!-- struct Instance *i; -->
360 * <!-- VOIDPTR ipdata; (you gave us with your IPFunc) -->
361 * <!-- VOIDPTR vp; (the vp you pass to PopInterfacePtrs) -->
362 * This is a function you supply. It will be called with the pointer
363 * you returned in IPFunc and the matching instance and the void
364 * you passed to PopInterfacePtrs.
365 * This is so you may do any destruction of the objects returned by IPFunc.
366 */
367
368 extern void PopInterfacePtrs(struct gl_list_t *oldips,
369 IPDeleteFunc ipdestroyf,
370 VOIDPTR vp);
371 /**<
372 * <!-- PopInterfacePtrs(oldips,ipdestroyf,vp); -->
373 * <!-- IPDeleteFunc ipdestroyf; -->
374 * <!-- struct gl_list_t *oldips; -->
375 * <!-- VOIDPTR userdata; -->
376 * This function restores the previous state of interface pointers.
377 * oldips is from a call to PushInterfacePtrs.
378 * ipdestroyf is a function you provide. If you provide NULL
379 * (meaning that no deallocation of objects pointed at by interface_ptr)
380 * we simply restore the old state. If ipdestroyf is not NULL, we
381 * will call it on the instances in oldips.
382 * We deallocate oldips, this is not your job.
383 */
384
385 extern int ArrayIsRelation(struct Instance *i);
386 /**<
387 * <!-- r = ArrayIsRelation(i); -->
388 * <!-- struct Instance *i; -->
389 * <!-- int r; -->
390 * Returns 1 if the instance sent in is a good relation array or relation,
391 * 0 OTHERWISE.
392 */
393
394 extern int ArrayIsLogRel(struct Instance *i);
395 /**<
396 * <!-- r = ArrayIsLogRel(i); -->
397 * <!-- struct Instance *i; -->
398 * <!-- int r; -->
399 * Returns 1 if the instance sent in is a good logical relation array
400 * or logical relation, 0 OTHERWISE.
401 */
402
403 extern int ArrayIsWhen(struct Instance *i);
404 /**<
405 * <!-- r = ArrayIsWhen(i); -->
406 * <!-- struct Instance *i; -->
407 * <!-- int r; -->
408 * Returns 1 if the instance sent in is a good when array
409 * or when, 0 OTHERWISE.
410 */
411
412 extern int ArrayIsModel(struct Instance *i);
413 /**<
414 * <!-- r = ArrayIsModel(i); -->
415 * <!-- struct Instance *i; -->
416 * <!-- int r; -->
417 * Returns 1 if the instance sent in is a good model array
418 * or when, 0 OTHERWISE.
419 */
420
421 #endif /* ASC_INSTANCE_IO_H */
422

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