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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 529 - (show annotations) (download) (as text)
Sat Apr 22 06:26:23 2006 UTC (13 years, 9 months ago) by johnpye
File MIME type: text/x-chdr
File size: 24315 byte(s)
Working of debugging the mysterious PyGTK bug. Seems to be coming from a wrong
char *filename in an error_reporter call from the DEBUG_RELS sections of the
compiler code.
Also renamed the WSEM and WSNM macros for clarity, removed unused file pointer.
1 /* ASCEND modelling environment
2 Copyright (C) 1990, 1993, 1994 Thomas Guthrie Epperly, Kirk Abbott.
3 Copyright (C) 1997 Benjamin Allan
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 *//**
21 @file
22 User package management.
23
24 RequiresL:
25 #include <stdio.h>
26 #include "compiler.h"
27 #include "ascMalloc.h"
28 #include "extfunc.h" (going away soon)
29 #include "type_desc.h" (going away soon)
30 #include "module.h" (going away soon)
31 #include "library.h" (going away soon)
32 #include "relation.h" (going away soon)
33
34 Users of this header should not have to include anything
35 except instance_enum.h and list.h and whatever headers those
36 may require.
37
38 @todo Comments about header dependencies are contradictory.
39 *//*
40 by Ben Allan & Kirk Abbott
41 Created: July 4, 1994
42 Version: $Revision: 1.12 $
43 Version control file: $RCSfile: packages.h,v $
44 Date last modified: $Date: 1998/05/18 16:36:45 $
45 Last modified by: $Author: ballan $
46 */
47
48 #ifndef ASC_PACKAGES_H
49 #define ASC_PACKAGES_H
50
51 /**
52 Have included the follow here to simplify instructions for people
53 writing their own external packages:
54 */
55 #include <utilities/ascConfig.h>
56 #include "instance_enum.h"
57 #include <general/list.h>
58 #include "extfunc.h"
59
60 #ifndef ASC_CLIENTDATA_DECLARED
61 # ifdef __STDC__
62 typedef void *ascClientData;
63 # else
64 typedef int *ascClientData;
65 # endif
66 # define ASC_CLIENTDATA_DECLARED
67 #endif
68
69 /**
70 these are for external clients to return to us when they have
71 an error or other procedural message to report about flow of
72 control.
73 */
74 #define ASC_OK 0
75 #define ASC_ERROR 1
76 #define ASC_RETURN 2
77 #define ASC_BREAK 3
78 #define ASC_CONTINUE 4
79
80 typedef int (Asc_MethodProc) (ascClientData, CONST char *,
81 struct Instance *, struct gl_list_t *);
82
83 typedef int (Asc_MethodDelete) (ascClientData, CONST char *, Asc_MethodProc);
84
85 /**
86 Clients should use the operators below to access this enum and
87 associated structure.
88 */
89 enum argItemEnum {
90 argError, /**< should never be seen by client */
91 /* the first 3 characters of the comment lines are the
92 * equivalent of C conversion characters in printf when
93 * specifying the arguments desired in the parsestring.
94 */
95 argOldFileId, /**< OF name of an existing file (char *) */
96 argNewFileId, /**< NF name of new file (char *) */
97 argUnkFileId, /**< UF name of file, unknown status (char *) */
98 argFloat, /**< f maps ASCEND integer/real types to a float value */
99 argDouble, /**< g maps ASCEND integer/real types to a double value */
100 argLong, /**< ld maps ASCEND integer/boolean to long value. */
101 argDoublePtr, /**< pg maps ASCEND reals to a double * */
102 argLongPtr, /**< pld maps ASCEND integers to long * */
103 argInt, /**< d maps ASCEND integer/boolean to int value. */
104 argBoolean, /**< b maps ASCEND boolean or integer to 0,1 value */
105 argString, /**< s maps ASCEND symbol types to a C const char * */
106 argSetString, /**< ss maps ASCEND set types into a C const char * */
107 argNameString, /**< n maps ASCEND Name given into a C const char * */
108 argNameList, /**< N expand ASCEND Name given into a C const char * */
109 argTypeString, /**< T maps ASCEND type name given into a C const char * */
110 argInst, /**< i instance pointer may be any kind */
111 argInstReal, /**< R instance pointer must be REAL*INST */
112 argInstRealList, /**< LR flattens array of real insts into a gl_list */
113 argInstRealArray, /**< AR instance pointer must be an array of reals */
114 argDoubleConst, /**< CR pointer to new double value for unassigned const */
115 argInstInt, /**< I instance pointer must be INTEGER*INST */
116 argInstIntList, /**< LI flattens array of integer insts into a gl_list */
117 argInstIntArray, /**< AI instance pointer must be an array of integers */
118 argIntConst, /**< CI pointer to new long value for unassigned const */
119 argInstBool, /**< B instance must be BOOLEAN_[ATOM/CONSTANT]_INST */
120 argInstBoolList, /**< LB flattens array of boolean insts into a gl_list */
121 argInstBoolArray, /**< AB instance pointer must be an array of boolean */
122 argBoolConst, /**< CB pointer to new 0/1 value for unassigned const */
123 argInstSym, /**< S instance must be SYMBOL_[ATOM/CONSTANT]_INST */
124 argInstSymList, /**< LS flattens array of symbol insts into a gl_list */
125 argInstSymArray, /**< AS instance pointer must be an array of symbols */
126 argSymConst, /**< CS pointer to new char * value for unassigned const */
127 argInstSet, /**< SS instance must be SET_[ATOM/CONSTANT]_INST */
128 argInstSetList, /**< LSS flattens array of set insts into a gl_list */
129 argInstSetArray, /**< ASS instance pointer must be an array of sets */
130 argISetConst, /**< CSS pointer to gl_list of longs for unassigned set */
131 argESetConst, /**< DSS pointer to gl_list of char * for unassigned set */
132 argInstRel, /**< r instance must be RELATION_INST */
133 argInstRelList, /**< Lr flattens array of relation insts into a gl_list */
134 argInstRelArray, /**< Ar instance pointer must be an array of relations */
135 argInstLRel, /**< lr instance must be LOGREL_INST */
136 argInstLRelList, /**< Llr flattens array of logrelations into a gl_list */
137 argInstLRelArray, /**< Alr instance pointer must be an array of logrel */
138 argInstModel, /**< M MODEL instance pointer */
139 argInstModelList, /**< LM flattens array of MODEL insts into a gl_list */
140 argInstModelArray,/**< AM flattens array of MODEL insts into a gl_list */
141 argProcName, /**< P maps name of a method/call to a CONST char * */
142 argExpr, /**< V maps a reference to an ASCEND Expr into lval */
143 argSLit /**< Q a C string literal is expected. */
144 /* probably need to add type Q for double quoted text */
145 };
146
147 struct argItem {
148 enum argItemEnum kind;
149 int depth; /**< For Array and list arguments, sets the number of
150 * subscripts expected. If 0, any number is allowed.
151 * Internal use only.
152 */
153 union {
154 double dval; /**< double value */
155 long lival; /**< long int value */
156 double dptr; /**< double pointer */
157 long liptr; /**< long int pointer */
158 int ival; /**< int value */
159 int bval; /**< boolean value */
160 CONST char *cval; /**< const char * from an ascend set/symbol */
161 CONST char *nval; /**< string form of the ascend name given */
162 CONST char *fval; /**< file id string */
163 CONST struct gl_list_t *lval; /**< list according to enum */
164 struct Instance *i; /**< instance according to enum */
165 } u; /**< union of possible values */
166 short args; /**< 0 usually. 1 if item is ... at the end. Internal use. */
167 short exact; /**< 0 usually. 1 if type specifier to be match. 2 if exactly */
168 symchar *type_name; /**< typeidentifier from the symbol table */
169 };
170
171 #define Asc_argItemKind(aip) ((aip)->kind)
172 #define Asc_argItemDepth(aip) ((aip)->depth)
173 #define Asc_argItemInstance(aip) ((aip)->u.i)
174 #define Asc_argItemDoublePtr(aip) ((aip)->u.dptr)
175 #define Asc_argItemLongPtr(aip) ((aip)->u.liptr)
176 #define Asc_argItemDouble(aip) ((aip)->u.dval)
177 #define Asc_argItemLongVal(aip) ((aip)->u.lival)
178 #define Asc_argItemIntVal(aip) ((aip)->u.ival)
179 #define Asc_argItemBoolVal(aip) ((aip)->u.bval)
180 #define Asc_argItemStringVal(aip) ((aip)->u.cval)
181 #define Asc_argItemNameString(aip) ((aip)->u.nval)
182 #define Asc_argItemTypeName(aip) ((aip)->u.nval)
183 #define Asc_argItemFileString(aip) ((aip)->u.fval)
184 #define Asc_argItemListValue(aip) ((aip)->u.lval)
185 /**<
186 * All of the data in or referenced directly by an argItem
187 * should not be changed or destroyed by the user proc.
188 * The only exception is that the value pointed to by argItemDoublePtr
189 * or argItemLongPtr items may be changed.
190 */
191
192 /** Add a user method */
193 extern int Asc_AddUserMethod(CONST char *methodname,
194 Asc_MethodProc proc,
195 enum inst_t selfKind,
196 CONST char *parseString,
197 ascClientData cData,
198 Asc_MethodDelete deleteProc,
199 CONST char *description,
200 CONST char *details);
201 /**
202 @param methodname the name to be used in the ASCEND method.
203 @param proc the function pointer that will be called.
204 @param selfKind the kind of instance that this method must be called in the scope of.
205 If any is acceptable, or proc will check the kind, then selfKind should be DUMMY_INST.
206 If NULL is an acceptable value of self, ERROR_INST should be used.
207 @param parseString a string of arg type directives separated by semicolons. For example,
208 "g, ...M" has directives "g" and "...M". Whitespace in the parseString is ignored.
209 @param ascClientData is a void pointer that will be included in every call to proc. It may be NULL.
210 @param deleteProc is called by Asc_DeleteUserMethod with cData, methodname. and proc.
211 deleteProc may be NULL if no special delete action is wanted.
212 @param description a one-line description of the function. Cannot be NULL.
213 @param details is a longer piece of useful information or directions how and where to
214 obtain more information. Cannot be NULL.
215
216 We guarantee to not call proc until the arguments supplied in the call satisfy the conditions implied by the parseString. This frees the user method from a vast chunk of condition checking. In no case will the user method be called with the actual UNIVERSAL DummyInstance. Dummys are considered to always be erroneous input. The user method is responsible for handling all possible inputs which conform to the parse string.
217
218 Each directive is of the form WXYZ where:
219 <pre>
220 W is either the string "..." or empty
221 X is A,L,p or a positive integer decimal number or empty for Instance Y,
222 or X is O, N, or U for file Y.
223 Y is F, s,ss,d,ld,b,f,g,n,N,T,i,R,B,S,SS,I, or M.
224 Z is .<identifier> or +<identifier> for Y that are instances
225 W: ...XYZ indicates that any number of additional arguments
226 conforming to the directive remaining XYZ are permitted. If XYZ calls
227 for scalars and arrays are found, arrays will be expanded into scalar
228 instances.
229 ... can be used in the any directive, but "...XYZ;...XYZ"
230 is impossible to satisfy because the second slot is always empty
231 as the first slot eats up all XYZ arguments.
232 X: A indicates to expect an array of the kind required by the remaining
233 directive YZ. Applies only to Instance flavors of Y.
234 L indicates to expect a list cooked up from the elements of an array.
235 The elements of the array must conform to YZ.
236 O,N,U apply only when Y = "F"
237 O indicates an old file, N a new one, and U an unknown.
238 p indicates that the pointer to a double or long is desired.
239 callers can read/set values this way without knowing about
240 the details of real/integer instances. These pointers are
241 not stable, and the user should not cache them anywhere.
242 This modifier does not work for constant or other types:
243 anyone wanting to mess with other types must use our detailed headers.
244 All double values are stored in SI units.
245 <decimal number> indicates both the minium & maximum string length
246 allowed for arguments that are normally C strings (s,ss,n,N,Q,T).
247 C strings will be padded to this length with trailing blanks
248 This is for FORTRAN compatibility. Strings too long are invalid
249 and will not be passed. If the number is -1, then the string
250 argument will be expanded into two arguments: an int that specifies
251 the length and the string following.
252 Y: F indicates filename expected.
253 s indicates string value expected.
254 ss indicates string value of a set expected.
255 d indicates int value expected.
256 ld indicates long int value expected.
257 b indicates boolean int value expected.
258 f indicates float value expected.
259 g indicates double value expected.
260 n indicates string form of a name expected.
261 N indicates set expanded, comma separated string form of name.
262 T indicates the name of a known type is expected.
263 --- instance flavours ---
264 i indicates any single instance is acceptable.
265 S indicates a symbol instance is expected.
266 SS indicates a set instance is expected.
267 R indicates a real instance is expected.
268 B indicates a boolean instance is expected.
269 I indicates an integer instance is expected.
270 M indicates a MODEL instance is expected.
271 V indicates an ASCEND Expr is expected.
272 r indicates a relation instance is expected.
273 lr indicates a logical relation instance is expected.
274 Z: -typeidentifier further restricts any instances passing WXY
275 to be of exactly the type 'typeidentifier'.
276 +typeidentifier further restricts any instances passing WXY
277 to be of the type 'typeidentifier' or a refinement of that type.
278 .intdepth restricts array instances to have intdepth subscripts.
279 </pre>
280
281 @example
282 <pre>
283 int ClearWrapper(ascClientData cdata, CONST char *calledAs,
284 struct Instance *root, struct gl_list_t *argList
285 ){
286 unsigned long c,len;
287 len = gl_length(argList);
288 if (len == 0) {
289 Asc_ClearVarsInTree(root);
290 }else{
291 for (c = 1; c <= len; c++) {
292 item = (struct argItem *)gl_fetch(argList,c);
293 Asc_ClearVarsInTree(Asc_argItemInstance(item));
294 } // note that a simpler version with gl_iterate is possible.
295 }
296 return ASC_OK;
297 }
298 </pre>
299
300 NOTES:
301 * argList is a gl_list derived from the list of arguments the
302 * function caller supplies in the method.
303 * argList may be empty. It will never be NULL.
304 * argItem = (struct argItem *)gl_fetch(argList,k); returns the kth argument. The argItem is described by the enum above.
305
306 @example
307 AddUserMethod("ClearAllSolverVar",ClearWrapper,DUMMY_INST,"...M",NULL,NULL);
308 // leaves us able to call a method:
309 CALL ClearAllSolverVar(); (* clears self, we assume *)
310 CALL ClearAllSolverVar(SELF); (* redundant, but legal *)
311 CALL ClearAllSolverVar(foo,bar); (* ClearWrapper can clear several insts*)
312
313 ClearWrapper requires no state information saved between calls, so cData and deleteProc are NULL.
314
315 */
316
317 /** Find a method and undefine it, remove it from the package library. */
318 extern int Asc_DeleteUserMethod(char *mname);
319 /**<
320 @return 0 if success, else error code != 0
321 @param mname name of user method to undefine
322
323 Call the Asc_MethodDelete function specifed when adding the method. Redefining user methods requires deleting the old and calling Add with the new. If the same proc is registered under different names, only the named reference is deleted. This does not cause the unloading of dynamically loaded libraries, but it should be done to eliminate references to a library about to be unloaded.
324 */
325
326
327 /** Look up the brief help text for a named external method. */
328 extern CONST char *Asc_UserMethodDescription(char *mname);
329 /**<
330 @return description oneliner help string for a named method, or NULL if mname unknown.
331 @param mname name of the method
332 */
333
334
335 /** Loop up detailed help text for a named external method. */
336 extern CONST char *Asc_UserMethodDetails(char *mname);
337 /**<
338 @return long descriptive help text for the named method, or NULL if mname unknown.
339 @param mname name of the method
340 */
341
342
343 /** Get a list of all defined user methods in the user packages library. */
344 extern struct gl_list_t *Asc_UserMethodsDefined(void);
345 /**<
346 @return list of const char* pointers where registered method names are stored.
347
348 The caller should gl_destroy(mlist) when done with looking at it.
349 */
350
351 /** Give usage info for a named user method */
352 extern int Asc_UserMethodArguments(FILE *fp, char *mname);
353 /**<
354 @param fp file to which the output should be written
355 @param mname method name for which details are required
356
357 Writes a synopsis of the arguments required, based on information
358 derived from the parse-string to fp.
359 */
360
361 /*-------------------------------------------------------
362 This whole header is junk below here. Temporarily, it is functioning
363 extern * junk. We need to reimplement some and scrap the rest.
364 */
365
366 /** @file packages.h
367 Interface to external packages
368 @see @ref packagespage "Packages"
369 */
370
371 /** @page packagespage
372
373 This file implements an interface to external packages. These external packages may be invoked from the procedural section, say for doing external calculations, querying a database, and writing/ reading values from the instance tree. They may also be used in the declarative section for providing relations to augment those in the declarative section. These may be full models/ solvers capable of solving themselves or smarter models/matrix routines capable of operating in a single step mode. [This overloading has caused a protocol that serves neither very well.] The rest of the discussion here is based on packages in the procedural section, and packages in the declarative section that will solve themselves to completion at each major iteration of the solution scheme in which they are imbedded.
374
375 @section procedural Procedural section
376
377 The packages provided in the procedural section follow the 'foreign pointer' concept; i.e., they will be handed a pointer to a reference instance, and a list of list of arguments. They need to provide only the number of input arguements, and may freely manipulate the instance tree and whatever way they feel. The only *mandatory* function must respect the following function prototype:
378
379 @code
380 int (*proc) (struct Slv_Interp *interp
381 ,struct Instance *reference
382 ,struct gl_list_t *arglist
383 );
384 @endcode
385
386 An optional help string may be provided. We will *make a copy* of this string, if non-null. When invoked this package must do whatever arg checking that is necessary, do its thing, and return a nonzero error result if there are any errors.
387
388 @section declarative Declarative section
389
390 More information is need from the packages in the declarative section that provide relations. In particular a *presolve/init* routine must be provided, which the compiler/solver will invoke to make sure that all is ok. This package when registering itself has to provide: n_input_args -- the number of input args on its arglist. n_output_args -- the number of output args on its arglist. In addition to the presolve/init routine, the following functions for doing function and jacobian evaluations have to be provided. The deriv (jacobian evaluation routine) and higher order derivative routines may be left NULL, and finite difference via repeated function calls will be done. The calling protocal for all functions is as follows:
391
392 @code
393 int (*init) (struct Slv_Interp *interp,
394 struct Instance *model_data,
395 struct gl_list_t *arglist);
396
397 int (*value) (struct Slv_Interp *interp,
398 int ninputs, int noutputs,
399 double *inputs, double *outputs,
400 double *jacobian);
401
402 int (*deriv) (struct Slv_Interp *interp,
403 int ninputs, int noutputs,
404 double *inputs, double *outputs,
405 double *jacobian);
406 @endcode
407
408 deriv2 and any higher order derivatives that come along will follow same calling protocol as for value and deriv.
409
410 @note The arguement model_data is provided for external packages that need to get additional information from the instance tree so as to do there computations. This information, should ideally be retrieved during exection of the init function and cached away.
411
412 @section interpreter The Interpreter
413
414 The interpreter structure is the means of communication between external packages and the ASCEND instance tree and/or solvers. It is particularly necessary in the case of packages in the declarative section. The state of the bit flags must be monitored and appropriate action taken. In the case of an error, a nonzero result must be returned from all functions, and the reason indicated by writing to the interp->status field. At the moment 1 wild hook is provided for the convenience of users. A user may attach an object to this hook and it will be passed around to each of its function calls. As an example consider the following code fragment.
415
416 @code
417 int init(struct Slv_Interp *slv_interp
418 , struct Instance *data
419 ,struct gl_list_t *arglist)
420 {
421 struct my_solve_system *system;
422 double *my_inputs;
423 if(slv_interp->firstcall){
424 system = my_presolve(data,arglist);
425
426 if (system!=NULL) {
427 my_inputs = MakeVectorFromList(arglist);
428 system->inputs = my_inputs;
429 slv_interp->user_data = (void *)system;
430 }else{
431 slv_interp->status = calc__error;
432 return 1;
433 }
434 }else{
435 destroy_sys((my_solve_system *)slv_interp->user_data);
436 slv_interp->user_data = NULL;
437 }
438 slv_interp->status = calc_all_ok;
439 return 0;
440 }
441 @endcode
442
443 The arglist and all references to instances have been intentionally removed from the value (function evaluation) and deriv* routines so as to allow ease of interfacing to existing standalone packages.
444 */
445
446 extern void Init_Slv_Interp(struct Slv_Interp *slv_interp);
447 /**<
448 @deprecated { Needs revising @see packages.h }
449
450 Gets the interpreter back to a 'clean' state. The default settings are guaranteed to be as follows:
451 @li nodestamp = 0;
452 @li status = calc_all_ok;
453 @li first_call = (unsigned)0;
454 @li last_call = (unsigned)0;
455 @li check_args = (unsigned)0;
456 @li recalculate = (unsigned)0;
457 @li deriv_eval = (unsigned)0;
458 @li func_eval = (unsigned)0;
459 */
460
461 /** Reset the interpreter to its initial state. */
462 extern void Reset_Slv_Interp(struct Slv_Interp *slv_interp);
463 /*
464 @deprecated { Needs revising @see packages.h }
465 */
466
467 /** Register all statically-linked user packages */
468 extern void AddUserFunctions(void);
469 /**<
470 @deprecated { Needs revising @see packages.h }
471
472 If the compiler-time flag STATIC_PACKAGES was set, this function should load any statically linked packages into the user packages library. If the flag was not set, it should do nothing.
473 */
474
475 /** Calculate an external relation */
476 extern int CallExternalProcs(struct Instance *i);
477 /**<
478 @deprecated { Needs revising @see packages.h }
479
480 This function given a handle to a relation instance which represents an external relation, will attempt to invoke it and write the results to stdout.
481 */
482
483 extern symchar *MakeArchiveLibraryName(CONST char *prefix);
484 /**<
485 @deprecated
486 This function is obsolete and should not be used in new code. See ascDynaLoad.h for correct replacement.
487
488 @return platform-dependent shared-object name / symbol table entry (??)
489 @param prefix library filename prefix.
490
491 This function will try to construct a platform dependent name for a dynamically loadable archive. In the case of
492 @li sun, alphas, solaris -- lib<prefix>.so.1.0
493 @li hpux -- lib<prefix>.sl
494 @li mips -- ???
495 @li aix -- ???
496 @li linux -- lib<prefix>.so
497 */
498
499 /** Load an external library specified by 'short name'. */
500 extern int LoadArchiveLibrary(CONST char *name, CONST char *initfunc);
501 /**<
502 @param name the short name of the library. (include 'lib' prefix?)
503 @return 0 if success, 1 if failure.
504
505 @deprecated
506 This is a rather pointless wrapper to the ascDynaLoad functions. @see ascDynaLoad.h for correct replacement.
507
508 Given the name of a dynamically loadable library/archive (dll), and the name of an initialization routine to be found in this archive, this function will attempt to load the archive and to run the initialization routine. Will return a nonzero code in the event of failure. The calling protocol for the init routine is:
509
510 @code void Routine_init(void); @endcode
511 */
512
513 #endif /* ASC_PACKAGES_H */
514

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