/[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 272 - (show annotations) (download) (as text)
Sun Feb 5 06:43:19 2006 UTC (18 years, 4 months ago) by johnpye
File MIME type: text/x-chdr
File size: 13012 byte(s)
Documentation changes.
Modified one slv3 error message.
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 * Collect all instances in path connecting inst with ref and returns
62 * them in a list. If path doesn't exist, it returns NULL. Path will
63 * be such that the smallest number of intermediate instances are used.
64 * This is a recursive function so send in 0,UINT_MAX as the last two
65 * arguments to initiate the call.<br><br>
66 *
67 * This returns a list of pointers to instances, and it should be
68 * deallocated with gl_destroy(path).
69 */
70
71 extern struct gl_list_t *AllPaths(CONST struct Instance *inst);
72 /**<
73 * AllPaths makes and returns a list of lists of NameNode structures.
74 * Each member of list AllPaths returns is a path from the given instance
75 * to root.<br><br>
76 *
77 * How to deallocate the result of AllPaths:
78 * Here is an example of how to deallocate the results. Use it or
79 * something equivalent.
80 * <pre>
81 * struct gl_list_t *paths,*path;
82 * paths = AllPaths(i);
83 * ....whatever....
84 * for(c=1;c <= gl_length(paths);c++){
85 * gl_free_and_destroy(gl_fetch(paths,c));
86 * }
87 * gl_destroy(paths);
88 * </pre>
89 */
90
91 extern struct gl_list_t *ISAPaths(CONST struct gl_list_t *pathlist);
92 /**<
93 * Given pathlist, the output of AllPaths, returns the list of
94 * names which are real: that is names which have been constructed
95 * without ALIASES or WILL_BE's intermediate.
96 * The list returned contains pointers to elements of the pathlist given,
97 * so it should be destroyed with gl_destroy(isalist) before the
98 * AllPaths destruction is applied to pathlist.
99 * In well written MODELs, the isalist returned will be one long.
100 */
101
102 extern int WriteInstanceName(FILE *f,
103 CONST struct Instance *i,
104 CONST struct Instance *ref);
105 /**<
106 * Print the instance's name to the specified file. The name that is
107 * printed is derived from the shortest path between i and ref. If
108 * ref is NULL, the shortest path to root is used. The number of
109 * characters written is returned, to assist in pretty printing or
110 * line breaking.
111 */
112
113 extern void WriteInstanceNameDS(Asc_DString * dsPtr,
114 CONST struct Instance *i,
115 CONST struct Instance *ref);
116 /**<
117 * Print the instance's name to the specified dstring. The name that is
118 * printed is derived from the shortest path between i and ref. If
119 * ref is NULL, the shortest path to root is used.
120 * This does not put a . in at the beginning of a name, so you cannot
121 * build up proper names in a DS with it. It writes proper
122 * relative names instead, where the context is assumed to be ref.
123 */
124
125 extern char *WriteInstanceNameString(CONST struct Instance *i,
126 CONST struct Instance *ref);
127 /**<
128 * Return a string (that the user must destroy eventually). The name that is
129 * printed is derived from the shortest path between i and ref. If
130 * ref is NULL, the shortest path to root is used.
131 * The name will not begin with a ., even if the path ref
132 * is not a simulation or NULL.
133 */
134
135 extern int WriteAnyInstanceName(FILE *f, struct Instance *i);
136 /**<
137 * Print the instance's name to the specified file.
138 * Very similar to WriteInstanceName(). The name that is
139 * printed is derived from *any* path from i to NULL.
140 * This function was designed for speed, rather than good
141 * looks, and may be used for bulk writing of instance names. Returns
142 * the count of characters written.
143 */
144
145 extern unsigned long CountAliases(CONST struct Instance *i);
146 /**<
147 * Count all the known names of the instance given.
148 */
149
150 extern unsigned long CountISAs(CONST struct Instance *i);
151 /**<
152 * Count the names with which the instance given was created.
153 */
154
155 extern void WriteAliases(FILE *f, CONST struct Instance *i);
156 /**<
157 * Print all the instance's names to the specified file.
158 */
159
160 extern void WriteISAs(FILE *f, CONST struct Instance *i);
161 /**<
162 * Print the instance's constructed names to the specified file.
163 * (there may not be any in bizarre circumstances).
164 */
165
166 extern struct gl_list_t *WriteAliasStrings(CONST struct Instance *i);
167 /**<
168 * Return a list of strings of all the possible instance names for i.
169 * The list AND the strings on it are the user's responsibility to destroy.
170 * gl_free_and_destroy(aliases) would be convenient.
171 */
172
173 extern struct gl_list_t *WriteISAStrings(CONST struct Instance *i);
174 /**<
175 * Return a list of strings of all the constructed instance names for i.
176 * Names created by WILL_BE/ALIASES are not returned.
177 * Under bizarre circumstances, the list may be empty.
178 * The list AND the strings on it are the user's responsibility to destroy.
179 * gl_free_and_destroy(aliases) would be convenient.
180 *
181 * @bug Returns IS_A'd parents as well. need to hunt down the path
182 * of instances being tracked and see if they were passed the original
183 * instance we queried about.
184 */
185
186 extern void WriteClique(FILE *f, CONST struct Instance *i);
187 /**<
188 * Print all the instance's clique members.
189 */
190
191 extern void WriteInstance(FILE *f, CONST struct Instance *i);
192 /**<
193 * Print the information contained in i.
194 */
195
196 extern int WritePath(FILE *f, CONST struct gl_list_t *path);
197 /**<
198 * Returns the number of name pieces written.
199 */
200
201 extern char *WritePathString(CONST struct gl_list_t *path);
202 /**<
203 * <!-- str = WritePathString(path); -->
204 * <!-- CONST struct gl_list_t *path; -->
205 * <!-- char *str; -->
206 * Returns the path in a string. The caller should free the string when
207 * done with it.
208 */
209
210 extern void SaveInstance(FILE *f, CONST struct Instance *inst, int dorelations);
211 /**<
212 * Save the information contained in inst in a format that will allow
213 * efficient reconstruction of the instance. This will be followed up
214 * with RestoreInstance.
215 */
216
217 extern void WriteInstanceList(struct gl_list_t *list);
218 /**<
219 * This is a debugging aid and not intended for general use.
220 * It assumes that this is a list of instances and will try to write
221 * out the instance name for each element on the list.
222 */
223
224 extern void WriteAtomValue(FILE *fp, CONST struct Instance *i);
225 /**<
226 * Write an instance value to fp.
227 */
228
229 typedef VOIDPTR (*IPFunc)(struct Instance *,VOIDPTR);
230 /**<
231 * This is the type of function you should write for use with
232 * PushInterfacePtrs(). It will be applied to the instances in the
233 * tree. If your function returns anything other than NULL, then
234 * we will make the instance's interface pointer be the pointer you
235 * returned.<br><br>
236 * In constructing instance bridges it is good to be able to attach
237 * temporary data structures to instances during construction. These
238 * temporary structures should not be left laying about. Rather, you
239 * should call the following Push and Pop functions like so:
240 * <pre>
241 * int build_my_bridge(struct Instance *i, ...)
242 * {
243 * struct gl_list_t *oldips = NULL;
244 * oldips = PushInterfacePtrs(i,YourCreateFunc,0,1,vp);
245 * Do whatever you need to here, making the assumption
246 * that the instance's YourFunc was interested in have
247 * the data created by YourFunc in their interface_ptrs.
248 * PopInterfacePtrs(oldips,YourDestroyFunc,vp);
249 * }
250 * </pre>
251 * If everyone follows this rule, it is easy to see that we can
252 * support nested transient clients so long as they don't go
253 * sneaking around in each others guts. Abstraction is your friend.
254 * Clients, such as a horribly sloppy GUI, may work without using the
255 * push and pop functions, but sanity insurance is then THAT client's
256 * responsibility and none of ours.
257 */
258
259 extern struct gl_list_t *PushInterfacePtrs(struct Instance *i,
260 IPFunc ipcreatef,
261 unsigned long int iest,
262 int visitorder,
263 VOIDPTR vp);
264 /**<
265 * Creates a gl_list and returns it to you.
266 * It contains the information needed to restore the state of the
267 * instance interface pointers ipcreatef returns non-NULL values for.
268 * Remember that not all instance types have interface pointers.
269 * Push does not visit subatomic instances (ATOM/reln children).<br><br>
270 * The algorithm is as follows:
271 * - Create an initial gl_list of capacity = 2 * iest (we keep pairs).
272 * (Thus, iest allows you to give us a hint about how many insts
273 * you expect to be interested in. iest need not be a perfect hint.)
274 * - Visit the instance tree (visitorder is treated as order is in
275 * the VisitInstanceTree function). Each place that ipcreatef
276 * returns non-NULL, save ip state information in the gl_list and
277 * replace it in the instance with your ip data.
278 * - Return gllist.
279 * The gl_list returned here can only be safely destroyed by a call
280 * following to PopInterfacePtrs.
281 * The gl_list returned may be NULL if malloc fails or you forgot
282 * ipcreatef.<br><br>
283 *
284 * ASSUMPTION: For the duration of the Push/Pop sequence you will be
285 * taking NO compiler action that deletes, relocates, or merges any
286 * part of the subtree rooted at instance i.
287 * Violate this rule and we die most probably.
288 * This is not a hard assumption to meet in single thread code.
289 */
290
291 typedef VOIDPTR (*IPDeleteFunc)(struct Instance *, VOIDPTR, VOIDPTR);
292 /**<
293 * This is a function you supply. It will be called with the pointer
294 * you returned in IPFunc and the matching instance and the void
295 * you passed to PopInterfacePtrs.
296 * This is so you may do any destruction of the objects returned by IPFunc.
297 */
298
299 extern void PopInterfacePtrs(struct gl_list_t *oldips,
300 IPDeleteFunc ipdestroyf,
301 VOIDPTR vp);
302 /**<
303 * This function restores the previous state of interface pointers.
304 * oldips is from a call to PushInterfacePtrs.
305 * ipdestroyf is a function you provide. If you provide NULL
306 * (meaning that no deallocation of objects pointed at by interface_ptr)
307 * we simply restore the old state. If ipdestroyf is not NULL, we
308 * will call it on the instances in oldips.
309 * We deallocate oldips, this is not your job.
310 */
311
312 extern int ArrayIsRelation(struct Instance *i);
313 /**<
314 * Returns 1 if the instance sent in is a good relation array or relation,
315 * 0 OTHERWISE.
316 */
317
318 extern int ArrayIsLogRel(struct Instance *i);
319 /**<
320 * Returns 1 if the instance sent in is a good logical relation array
321 * or logical relation, 0 OTHERWISE.
322 */
323
324 extern int ArrayIsWhen(struct Instance *i);
325 /**<
326 * Returns 1 if the instance sent in is a good when array
327 * or when, 0 OTHERWISE.
328 */
329
330 extern int ArrayIsModel(struct Instance *i);
331 /**<
332 * Returns 1 if the instance sent in is a good model array
333 * or when, 0 OTHERWISE.
334 */
335
336 #endif /* ASC_INSTANCE_IO_H */
337

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