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

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