generic/compiler/instance_io.h

/*  ASCEND modelling environment
    Copyright (C) 1990, 1993, 1994 Thomas Guthrie Weidner Epperly
    Copyright 1996 Benjamin Andrew Allan
    Copyright (C) 2006 Carnegie Mellon University

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2, or (at your option)
    any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program; if not, write to the Free Software
    Foundation, Inc., 59 Temple Place - Suite 330,
    Boston, MA 02111-1307, USA.
*//**
    @file
    Instance Output Routines.
*//*
    by Tom Epperly
    Created: 2/8/90
    Version: $Revision: 1.21 $
    Version control file: $RCSfile: instance_io.h,v $
    Date last modified: $Date: 1998/01/11 17:03:34 $
    Last modified by: $Author: ballan $
*/
/* blimey tom epperly you keep gaining middle-names */


#ifndef ASC_INSTANCE_IO_H
#define ASC_INSTANCE_IO_H

/** addtogroup compiler Compiler
    @{
*/

#include <utilities/ascConfig.h>
#include <general/dstring.h>
#include <compiler/compiler.h>
#include <compiler/symtab.h>
#include <compiler/instance_enum.h>

/**
    Return the instance's type name as given in instance_enum.h.
    This is a constant char pointer that the called does NOT own.

    Panics if the inst_t in the instance isn't found in our list of names.

    @return the name
*/ 
CONST char *instance_typename(CONST struct Instance *inst);

/**
 *  struct NameNode is used by the AllPaths() and WriteAliases() routines to
 *  keep track of an instance and which child name is used for a
 *  particular name chain.
 */
struct NameNode {
  CONST struct Instance *inst;
  unsigned long index;
};

extern struct gl_list_t *ShortestPath(CONST struct Instance *inst,
                                      CONST struct Instance *ref,
                                      /* CONST */ unsigned int height,
                                      /* CONST */ unsigned int best);
/**<
 *  Collect all instances in path connecting inst with ref and returns
 *  them in a list.  If path doesn't exist, it returns NULL.  Path will
 *  be such that the smallest number of intermediate instances are used.
 *  This is a recursive function so send in 0,UINT_MAX as the last two
 *  arguments to initiate the call.<br><br>
 *
 *  This returns a list of pointers to instances, and it should be
 *  deallocated with gl_destroy(path).
 */

extern struct gl_list_t *AllPaths(CONST struct Instance *inst);
/**<
 *  AllPaths makes and returns a list of lists of NameNode structures.
 *  Each member of list AllPaths returns is a path from the given instance
 *  to root.<br><br>
 *
 *  How to deallocate the result of AllPaths:
 *  Here is an example of how to deallocate the results.  Use it or
 *  something equivalent.
 *  <pre>
 *  struct gl_list_t *paths,*path;
 *  paths = AllPaths(i);
 *  ....whatever....
 *  for(c=1;c <= gl_length(paths);c++){
 *     gl_free_and_destroy(gl_fetch(paths,c));
 *  }
 *  gl_destroy(paths);
 *  </pre>
 */

extern struct gl_list_t *ISAPaths(CONST struct gl_list_t *pathlist);
/**<
 *  Given pathlist, the output of AllPaths, returns the list of
 *  names which are real: that is names which have been constructed
 *  without ALIASES or WILL_BE's intermediate.
 *  The list returned contains pointers to elements of the pathlist given,
 *  so it should be destroyed with gl_destroy(isalist) before the
 *  AllPaths destruction is applied to pathlist.
 *  In well written MODELs, the isalist returned will be one long.
 */

ASC_DLLSPEC int WriteInstanceName(FILE *f,
        CONST struct Instance *i,
        CONST struct Instance *ref);
/**<
    Print the instance's name to the specified file.  The name that is
    printed is derived from the shortest path between i and ref.  If
    ref is NULL, the shortest path to root is used. The number of
    characters written is returned, to assist in pretty printing or
    line breaking.
*/

extern void WriteInstanceNameDS(Asc_DString * dsPtr,
        CONST struct Instance *i,
        CONST struct Instance *ref);
/**<
    Print the instance's name to the specified dstring.  The name that is
    printed is derived from the shortest path between i and ref.  If
    ref is NULL, the shortest path to root is used.
    This does not put a . in at the beginning of a name, so you cannot
    build up proper names in a DS with it. It writes proper
    relative names instead, where the context is assumed to be ref.
*/

ASC_DLLSPEC char*WriteInstanceNameString(CONST struct Instance *i,
        CONST struct Instance *ref);
/**<
    Return a string (that the caller then owns). The name that is
    printed is derived from the shortest path between i and ref. If
    ref is NULL, the shortest path to root is used.
    The name will not begin with a '.', even if the path ref
    is not a simulation or NULL.
*/

ASC_DLLSPEC int WriteAnyInstanceName(FILE *f, struct Instance *i);
/**<
 *  Print the instance's name to the specified file.
 *  Very similar to WriteInstanceName().  The name that is
 *  printed is derived from *any* path from i to NULL.
 *  This function was designed for speed, rather than good
 *  looks, and may be used for bulk writing of instance names. Returns
 *  the count of characters written.
 */

ASC_DLLSPEC unsigned long CountAliases(CONST struct Instance *i);
/**<
 *  Count all the known names of the instance given.
 */

ASC_DLLSPEC unsigned long CountISAs(CONST struct Instance *i);
/**<
 *  Count the names with which the instance given was created.
 */

extern void WriteAliases(FILE *f, CONST struct Instance *i);
/**<
 *  Print all the instance's names to the specified file.
 */

extern void WriteISAs(FILE *f, CONST struct Instance *i);
/**<
 *  Print the instance's constructed names to the specified file.
 *  (there may not be any in bizarre circumstances).
 */

ASC_DLLSPEC struct gl_list_t *WriteAliasStrings(CONST struct Instance *i);
/**<
 *  Return a list of strings of all the possible instance names for i.
 *  The list AND the strings on it are the user's responsibility to destroy.
 *  gl_free_and_destroy(aliases) would be convenient.
 */

ASC_DLLSPEC struct gl_list_t *WriteISAStrings(CONST struct Instance *i);
/**<
 *  Return a list of strings of all the constructed instance names for i.
 *  Names created by WILL_BE/ALIASES are not returned.
 *  Under bizarre circumstances, the list may be empty.
 *  The list AND the strings on it are the user's responsibility to destroy.
 *  gl_free_and_destroy(aliases) would be convenient.
 *
 *  @bug Returns IS_A'd parents as well. need to hunt down the path
 *  of instances being tracked and see if they were passed the original
 *  instance we queried about.
 */

extern void WriteClique(FILE *f, CONST struct Instance *i);
/**<
 *  Print all the instance's clique members.
 */

ASC_DLLSPEC void WriteInstance(FILE *f, CONST struct Instance *i);
/**<
 *  Print the information contained in i.
 */

extern int WritePath(FILE *f, CONST struct gl_list_t *path);
/**<
 *  Returns the number of name pieces written.
 */

extern char *WritePathString(CONST struct gl_list_t *path);
/**<
 *  <!--  str =  WritePathString(path);                                -->
 *  <!--  CONST struct gl_list_t *path;                                -->
 *  <!--  char *str;                                                   -->
 *  Returns the path in a string. The caller should free the string when
 *  done with it.
 */

ASC_DLLSPEC void SaveInstance(FILE *f, CONST struct Instance *inst, int dorelations);
/**<
 *  Save the information contained in inst in a format that will allow
 *  efficient reconstruction of the instance. This will be followed up
 *  with RestoreInstance.
 */

extern void WriteInstanceList(struct gl_list_t *list);
/**<
 *  This is a debugging aid and not intended for general use.
 *  It assumes that this is a list of instances and will try to write
 *  out the instance name for each element on the list.
 */

ASC_DLLSPEC void WriteAtomValue(FILE *fp, CONST struct Instance *i);
/**<
 *  Write an instance value to fp.
 */

typedef VOIDPTR (*IPFunc)(struct Instance *,VOIDPTR);
/**<
 *  This is the type of function you should write for use with
 *  PushInterfacePtrs(). It will be applied to the instances in the
 *  tree. If your function returns anything other than NULL, then
 *  we will make the instance's interface pointer be the pointer you
 *  returned.<br><br>
 *  In constructing instance bridges it is good to be able to attach
 *  temporary data structures to instances during construction. These
 *  temporary structures should not be left laying about. Rather, you
 *  should call the following Push and Pop functions like so:
 *  <pre>
 *     int build_my_bridge(struct Instance *i, ...)
 *     {
 *        struct gl_list_t *oldips = NULL;
 *        oldips =  PushInterfacePtrs(i,YourCreateFunc,0,1,vp);
 *          Do whatever you need to here, making the assumption
 *          that the instance's YourFunc was interested in have
 *          the data created by YourFunc in their interface_ptrs.
 *        PopInterfacePtrs(oldips,YourDestroyFunc,vp);
 *     }
 *  </pre>
 *  If everyone follows this rule, it is easy to see that we can
 *  support nested transient clients so long as they don't go
 *  sneaking around in each others guts.  Abstraction is your friend.
 *  Clients, such as a horribly sloppy GUI, may work without using the
 *  push and pop functions, but sanity insurance is then THAT client's
 *  responsibility and none of ours.
 */

extern struct gl_list_t *PushInterfacePtrs(struct Instance *i,
                                           IPFunc ipcreatef,
                                           unsigned long int iest,
                                           int visitorder,
                                           VOIDPTR vp);
/**<
 *  Creates a gl_list and returns it to you.
 *  It contains the information needed to restore the state of the
 *  instance interface pointers ipcreatef returns non-NULL values for.
 *  Remember that not all instance types have interface pointers.
 *  Push does not visit subatomic instances (ATOM/reln children).<br><br>
 *  The algorithm is as follows:
 *  - Create an initial gl_list of capacity = 2 * iest (we keep pairs).
 *    (Thus, iest allows you to give us a hint about how many insts
 *    you expect to be interested in. iest need not be a perfect hint.)
 *  - Visit the instance tree (visitorder is treated as order is in
 *    the VisitInstanceTree function). Each place that ipcreatef
 *    returns non-NULL, save ip state information in the gl_list and
 *    replace it in the instance with your ip data.
 *  - Return gllist.
 *  The gl_list returned here can only be safely destroyed by a call
 *  following to PopInterfacePtrs.
 *  The gl_list returned may be NULL if malloc fails or you forgot
 *  ipcreatef.<br><br>
 *
 *  ASSUMPTION: For the duration of the Push/Pop sequence you will be
 *  taking NO compiler action that deletes, relocates, or merges any
 *  part of the subtree rooted at instance i.
 *  Violate this rule and we die most probably.
 *  This is not a hard assumption to meet in single thread code.
 */

typedef VOIDPTR (*IPDeleteFunc)(struct Instance *, VOIDPTR, VOIDPTR);
/**<
 *  This is a function you supply. It will be called with the pointer
 *  you returned in IPFunc and the matching instance and the void
 *  you passed to PopInterfacePtrs.
 *  This is so you may do any destruction of the objects returned by IPFunc.
 */

extern void PopInterfacePtrs(struct gl_list_t *oldips,
                             IPDeleteFunc ipdestroyf,
                             VOIDPTR vp);
/**<
 *  This function restores the previous state of interface pointers.
 *  oldips is from a call to PushInterfacePtrs.
 *  ipdestroyf is a function you provide.  If you provide NULL
 *  (meaning that no deallocation of objects pointed at by interface_ptr)
 *  we simply restore the old state. If ipdestroyf is not NULL, we
 *  will call it on the instances in oldips.
 *  We deallocate oldips, this is not your job.
 */

ASC_DLLSPEC int ArrayIsRelation(struct Instance *i);
/**<
 *  Returns 1 if the instance sent in is a good relation array or relation,
 *  0 OTHERWISE.
 */

ASC_DLLSPEC int ArrayIsLogRel(struct Instance *i);
/**<
 *  Returns 1 if the instance sent in is a good logical relation array
 *  or logical relation, 0 OTHERWISE.
 */

ASC_DLLSPEC int ArrayIsWhen(struct Instance *i);
/**<
 *  Returns 1 if the instance sent in is a good when array
 *  or when, 0 OTHERWISE.
 */

extern int ArrayIsModel(struct Instance *i);
/**<
 *  Returns 1 if the instance sent in is a good model array
 *  or when, 0 OTHERWISE.
 */

/* @} */

#endif /* ASC_INSTANCE_IO_H */

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