/[ascend]/trunk/base/generic/utilities/ascDynaLoad.h
ViewVC logotype

Contents of /trunk/base/generic/utilities/ascDynaLoad.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1072 - (show annotations) (download) (as text)
Tue Jan 9 00:37:25 2007 UTC (15 years, 5 months ago) by johnpye
File MIME type: text/x-chdr
File size: 7286 byte(s)
Fixed 'const char *envv' in SearchArchiveLibraryPath prototype decl.
1 /* ASCEND modelling environment
2 Copyright (C) 2006 Carnegie Mellon University
3
4 This program is free software; you can redistribute it and/or modify
5 it under the terms of the GNU General Public License as published by
6 the Free Software Foundation; either version 2, or (at your option)
7 any later version.
8
9 This program is distributed in the hope that it will be useful,
10 but WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 GNU General Public License for more details.
13
14 You should have received a copy of the GNU General Public License
15 along with this program; if not, write to the Free Software
16 Foundation, Inc., 59 Temple Place - Suite 330,
17 Boston, MA 02111-1307, USA.
18 *//**
19 @file
20 Dynamic library routines.
21
22 Requires:
23 #include "utilities/ascConfig.h"
24 </pre>
25 *//*
26 ChangeLog
27 Added Asc_DynamicUnLoad. Ben Allan (ballan@cs.cmu.edu) Jan 1998.
28 Your mileage may vary.
29 UnLoad alleged for sun, hp, sgi, and alpha/osf. It probably works
30 only as well as their dlclose and shl_unload do.
31 Split Asc_DynamicSymbol() into Asc_DynamicVariable() and
32 Asc_DynamicFunction() so callers don't have to cast between
33 data and function pointers (forbidden by ISO C). JDS Dec 2005
34 */
35
36 #ifndef ASC_ASCDYNALOAD_H
37 #define ASC_ASCDYNALOAD_H
38
39 #include <utilities/ascConfig.h>
40
41 char *SearchArchiveLibraryPath(const char *name, char *dpath, const char *envv);
42 /**<
43 Search the archive library path for a file matching the given
44 (platform specific, with extension?) library filename.
45
46 @param name Name of library being searched for
47 @param envv Name of environment var containing the ASCEND search path
48 @param dpath Default search path for the case where the env var is not defined
49
50 @return a pointer to a string space holding the full path
51 name of the file to be opened. The returned pointer may be NULL
52
53 If the returned pointer is not NULL, then it points to space that must be
54 FREEd when no longer needed.
55
56 @NOTE
57 This function has been moved out of compiler/packages.c into
58 utilities/ascDynaLoad.c so that it can be shared with the solver for use
59 in dynamic loading of external solver DLLs.
60 */
61
62 ASC_DLLSPEC int Asc_DynamicLoad(CONST char *path, CONST char *initFunc);
63 /**<
64 * Loads a dynamic library and calls its initialization function.
65 * This is our function wrapping dlopen/LoadLibrary. It makes
66 * provision for dynamic unloading using Asc_DynamicUnLoad().<br><br>
67 *
68 * Returns 1 if it fails to load the library named in path and find
69 * the symbol initFunc as an int function. Otherwise, it returns
70 * the result of the call to (*initFunc). If initFunc == NULL,
71 * nothing is called and 0 is returned after opening the library.
72 * If path == NULL, 1 is always returned.<br><br>
73 *
74 * A consequence of this behavior is that initFunc had better not
75 * return 1, or you won't be able to tell whether the library was
76 * successfully loaded or not. If it's under your control, have
77 * initFunc only return values other than 1 so you can detect the
78 * proper status.<br><br>
79 *
80 * @param path Path to the dynamic library to load (non-NULL).
81 * @param initFunc The DL initialization function to call.
82 *
83 * @return The return value from initFunc is returned if specified.
84 * Otherwise, 0 is returned if the library is successfully
85 * loaded, 1 if it is not.
86 */
87
88 ASC_DLLSPEC int Asc_DynamicUnLoad(CONST char *path);
89 /**<
90 * Attempts to unload a dynamic library.
91 * This function tries to look up the previously-loaded library
92 * in path and unload it. Only libraries successfully loaded using
93 * Asc_DynamicLoad() may be unloaded using this function.<br><br>
94 *
95 * This is our function wrapping dlclose/shl_unload/FreeLibrary
96 * which provides unloading. Once all references to the
97 * previously-loaded library have been scheduled to be removed
98 * without further ado, it can be unloaded on most architectures.
99 * Once you call this function, you damn well better not reference
100 * functions or data that came from the path given. Passing a NULL
101 * path will always result in an error condition (-3) being returned.
102 *
103 * @param path Path to the dynamic library to unload.
104 * @return Returns 0 if the library was successfully located and unloaded,
105 * -3 if the library was not located, or the return value of
106 * dlclose/shl_unload/FreeLibrary otherwise. Note that the
107 * return value conventions differ between platforms, so if you
108 * get a return value that is not 0 or -3, you are in platform-
109 * specific hell.
110 */
111
112 #define Asc_DynamicSymbol(a,b) Asc_DynamicVariable((a),(b))
113 /**< For backward compatibility to old name of Asc_DynamicVariable() */
114
115 ASC_DLLSPEC void *Asc_DynamicVariable(CONST char *libraryname,
116 CONST char *varname);
117 /**<
118 * Returns a pointer to a variable exported from a dynamically-linked
119 * library. It will generally be necessary to cast the returned
120 * pointer to the correct data type before use. If either parameter
121 * is NULL, or if the library or symbol cannot be located, then NULL
122 * will be returned.<br><br>
123 *
124 * This function was previously called Asc_DynamicSymbol() and could
125 * be used to retrieve either variables or functions from a library.
126 * This necessitated casting the returned void* to a function pointer
127 * for exported functions, which is forbidden by ISO C. Functions
128 * may now be retrieved using Asc_DynamicFunction(), thus avoiding the
129 * need for the caller to cast between data and function pointers.
130 * Never mind what the implementation does to achieve this.
131 * <pre>
132 * Example:
133 * int *value;
134 * value = (int *)Asc_DynamicVariable("lib.dll", "g_variable");
135 * </pre>
136 * @param libraryname Name of the dynamic library to query.
137 * @param varname Name of variable to look up in the library.
138 * @return A pointer to the variable in memory, or NULL if not found.
139 */
140
141 typedef void (*DynamicF)(void);
142 /**< Function pointer type returned by Asc_DynamicFunction(). */
143
144 ASC_DLLSPEC DynamicF Asc_DynamicFunction(CONST char *libraryname,
145 CONST char *funcname);
146 /**<
147 * Returns a pointer to a function exported from a dynamically-linked
148 * library. It will generally be necessary to cast the returned pointer
149 * to the correct function type before use. If either parameter
150 * is NULL, or if the library or function cannot be located, then NULL
151 * will be returned.
152 * <pre>
153 * Example:
154 * typedef double (*calcfunc)(double *, double *);
155 * calcfunc calc;
156 * calc = (calcfunc))Asc_DynamicFunction("lib.dll","calc");
157 * </pre>
158 * @param libraryname Name of the dynamic library to query.
159 * @param funcname Name of function to look up in the library.
160 * @return A pointer to the function in memory, or NULL if not found.
161 */
162
163 #if defined(__GNUC__) || (defined(__HPUX__) || defined(__ALPHA_OSF__) || \
164 defined(__WIN32__) || defined(__SUN_SOLARIS__) || \
165 defined(__SUN_SUNOS__) || defined(__SGI_IRIX__))
166 #define HAVE_DL_UNLOAD 1
167 /**<
168 * Set if a platform has a library unload function.
169 * We don't know about aix, and others.
170 */
171 #endif /* gnu,hp,alpha,win,solaris,sunos,irix */
172
173 #endif /* ASC_ASCDYNALOAD_H */

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