generic/utilities/ascDynaLoad.h

/* ASCEND modelling environment
   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.  */

/* ChangeLog
 * Added Asc_DynamicUnLoad. Ben Allan (ballan@cs.cmu.edu) Jan 1998.
 * Your mileage may vary.
 * UnLoad alleged for sun, hp, sgi, and alpha/osf. It probably works
 * only as well as their dlclose and shl_unload do.
 *
 * Split Asc_DynamicSymbol() into Asc_DynamicVariable() and
 * Asc_DynamicFunction() so callers don't have to cast between
 * data and function pointers (forbidden by ISO C).  JDS Dec 2005
 */

/** @file
 *  Dynamic library routines.
 *  <pre>
 *  Reaquires:
 *        #include "utilities/ascConfig.h"
 *  </pre>
 */

#ifndef ASC_ASCDYNALOAD_H
#define ASC_ASCDYNALOAD_H

#ifdef DYNAMIC_PACKAGES

extern int Asc_DynamicLoad(CONST char *path, CONST char *initFunc);
/**<
 *  Loads a dynamic library and calls its initialization function.
 *  This is our function wrapping dlopen/LoadLibrary.  It makes
 *  provision for dynamic unloading using Asc_DynamicUnLoad().<br><br>
 *
 *  Returns 1 if it fails to load the library named in path and find
 *  the symbol initFunc as an int function.  Otherwise, it returns
 *  the result of the call to (*initFunc).  If initFunc == NULL,
 *  nothing is called and 0 is returned after opening the library.
 *  If path == NULL, 1 is always returned.<br><br>
 *
 *  A consequence of this behavior is that initFunc had better not
 *  return 1, or you won't be able to tell whether the library was
 *  successfully loaded or not.  If it's under your control, have
 *  initFunc only return values other than 1 so you can detect the
 *  proper status.<br><br>
 *
 *  @param path     Path to the dynamic library to load (non-NULL).
 *  @param initFunc The DL initialization function to call.
 *  @return The return value from initFunc is returned if specified.
 *          Otherwise, 0 is returned if the library is successfully
 *          loaded, 1 if it is not.
 */

extern int Asc_DynamicUnLoad(CONST char *path);
/**<
 *  Attempts to unload a dynamic library.
 *  This function tries to look up the previously-loaded library
 *  in path and unload it.  Only libraries successfully loaded using
 *  Asc_DynamicLoad() may be unloaded using this function.<br><br>
 *
 *  This is our function wrapping dlclose/shl_unload/FreeLibrary
 *  which provides unloading.  Once all references to the
 *  previously-loaded library have been scheduled to be removed
 *  without further ado, it can be unloaded on most architectures.
 *  Once you call this function, you damn well better not reference
 *  functions or data that came from the path given.  Passing a NULL
 *  path will always result in an error condition (-3) being returned.
 *
 *  @param path     Path to the dynamic library to unload.
 *  @return Returns 0 if the library was successfully located and unloaded,
 *          -3 if the library was not located, or the return value of
 *          dlclose/shl_unload/FreeLibrary otherwise.  Note that the
 *          return value conventions differ between platforms, so if you
 *          get a return value that is not 0 or -3, you are in platform-
 *          specific hell.
 */

#define Asc_DynamicSymbol(a,b) Asc_DynamicVariable((a),(b))
/**< For backward compatibility to old name of Asc_DynamicVariable() */

extern void *Asc_DynamicVariable(CONST char *libraryname,
                                 CONST char *varname);
/**<
 *  Returns a pointer to a variable exported from a dynamically-linked
 *  library.  It will generally be necessary to cast the returned
 *  pointer to the correct data type before use.  If either parameter
 *  is NULL, or if the library or symbol cannot be located, then NULL
 *  will be returned.<br><br>
 *
 *  This function was previously called Asc_DynamicSymbol() and could
 *  be used to retrieve either variables or functions from a library.
 *  This necessitated casting the returned void* to a function pointer
 *  for exported functions, which is forbidden by ISO C.  Functions
 *  may now be retrieved using Asc_DynamicFunction(), thus avoiding the
 *  need for the caller to cast between data and function pointers.
 *  Never mind what the implementation does to achieve this.
 *  <pre>
 *  Example:
 *    int *value;
 *    value = (int *)Asc_DynamicVariable("lib.dll", "g_variable");
 *  </pre>
 *  @param libraryname Name of the dynamic library to query.
 *  @param varname     Name of variable to look up in the library.
 *  @return A pointer to the variable in memory, or NULL if not found.
 */

typedef void (*DynamicF)(void);
/**<  Function pointer type returned by Asc_DynamicFunction(). */

extern DynamicF Asc_DynamicFunction(CONST char *libraryname,
                                    CONST char *funcname);
/**<
 *  Returns a pointer to a function exported from a dynamically-linked
 *  library.  It will generally be necessary to cast the returned pointer
 *  to the correct function type before use.  If either parameter
 *  is NULL, or if the library or function cannot be located, then NULL
 *  will be returned.
 *  <pre>
 *  Example:
 *    typedef double (*calcfunc)(double *, double *);
 *    calcfunc calc;
 *    calc = (calcfunc))Asc_DynamicFunction("lib.dll","calc");
 *  </pre>
 *  @param libraryname Name of the dynamic library to query.
 *  @param funcname   Name of function to look up in the library.
 *  @return A pointer to the function in memory, or NULL if not found.
 */

#if defined(__GNUC__) || (defined(__HPUX__) || defined(__ALPHA_OSF__) || \
     defined(__WIN32__) || defined(__SUN_SOLARIS__) || \
     defined(__SUN_SUNOS__) || defined(__SGI_IRIX__))
#define HAVE_DL_UNLOAD 1
/**<
 *  Set if a platform has a library unload function.
 *  We don't know about aix, and others.
 */
#endif

#endif

#endif /* ASC_ASCDYNALOAD_H */

1	johnpye	466	/* ASCEND modelling environment
2			Copyright (C) 2006 Carnegie Mellon University
3	aw0a	1
4	johnpye	466	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	jds	54	/* ChangeLog
20	aw0a	1	* Added Asc_DynamicUnLoad. Ben Allan (ballan@cs.cmu.edu) Jan 1998.
21			* Your mileage may vary.
22			* UnLoad alleged for sun, hp, sgi, and alpha/osf. It probably works
23			* only as well as their dlclose and shl_unload do.
24	jds	103	*
25			* Split Asc_DynamicSymbol() into Asc_DynamicVariable() and
26			* Asc_DynamicFunction() so callers don't have to cast between
27			* data and function pointers (forbidden by ISO C). JDS Dec 2005
28	aw0a	1	*/
29	jds	54
30			/** @file
31	jds	59	* Dynamic library routines.
32			* <pre>
33			* Reaquires:
34	jds	54	* #include "utilities/ascConfig.h"
35	jds	59	* </pre>
36	jds	54	*/
37
38	johnpye	158	#ifndef ASC_ASCDYNALOAD_H
39			#define ASC_ASCDYNALOAD_H
40	aw0a	1
41	johnpye	466	#ifdef DYNAMIC_PACKAGES
42
43	jds	59	extern int Asc_DynamicLoad(CONST char path, CONST char initFunc);
44			/**<
45			* Loads a dynamic library and calls its initialization function.
46			* This is our function wrapping dlopen/LoadLibrary. It makes
47			* provision for dynamic unloading using Asc_DynamicUnLoad().<br><br>
48	aw0a	1	*
49	jds	59	* Returns 1 if it fails to load the library named in path and find
50			* the symbol initFunc as an int function. Otherwise, it returns
51			* the result of the call to (*initFunc). If initFunc == NULL,
52			* nothing is called and 0 is returned after opening the library.
53			* If path == NULL, 1 is always returned.<br><br>
54			*
55			* A consequence of this behavior is that initFunc had better not
56			* return 1, or you won't be able to tell whether the library was
57			* successfully loaded or not. If it's under your control, have
58			* initFunc only return values other than 1 so you can detect the
59			* proper status.<br><br>
60			*
61			* @param path Path to the dynamic library to load (non-NULL).
62			* @param initFunc The DL initialization function to call.
63			* @return The return value from initFunc is returned if specified.
64			* Otherwise, 0 is returned if the library is successfully
65			* loaded, 1 if it is not.
66	aw0a	1	*/
67
68	jds	59	extern int Asc_DynamicUnLoad(CONST char *path);
69			/**<
70			* Attempts to unload a dynamic library.
71			* This function tries to look up the previously-loaded library
72			* in path and unload it. Only libraries successfully loaded using
73			* Asc_DynamicLoad() may be unloaded using this function.<br><br>
74	aw0a	1	*
75	jds	59	* This is our function wrapping dlclose/shl_unload/FreeLibrary
76			* which provides unloading. Once all references to the
77			* previously-loaded library have been scheduled to be removed
78			* without further ado, it can be unloaded on most architectures.
79			* Once you call this function, you damn well better not reference
80			* functions or data that came from the path given. Passing a NULL
81			* path will always result in an error condition (-3) being returned.
82	aw0a	1	*
83	jds	59	* @param path Path to the dynamic library to unload.
84	jds	61	* @return Returns 0 if the library was successfully located and unloaded,
85	johnpye	466	* -3 if the library was not located, or the return value of
86	jds	61	* dlclose/shl_unload/FreeLibrary otherwise. Note that the
87			* return value conventions differ between platforms, so if you
88			* get a return value that is not 0 or -3, you are in platform-
89			* specific hell.
90	aw0a	1	*/
91
92	jds	103	#define Asc_DynamicSymbol(a,b) Asc_DynamicVariable((a),(b))
93			/*< For backward compatibility to old name of Asc_DynamicVariable() /
94
95			extern void Asc_DynamicVariable(CONST char libraryname,
96			CONST char *varname);
97	jds	59	/**<
98	jds	103	* Returns a pointer to a variable exported from a dynamically-linked
99	johnpye	466	* library. It will generally be necessary to cast the returned
100			* pointer to the correct data type before use. If either parameter
101			* is NULL, or if the library or symbol cannot be located, then NULL
102	jds	103	* will be returned.<br><br>
103			*
104	johnpye	466	* This function was previously called Asc_DynamicSymbol() and could
105	jds	103	* be used to retrieve either variables or functions from a library.
106			* This necessitated casting the returned void* to a function pointer
107			* for exported functions, which is forbidden by ISO C. Functions
108			* may now be retrieved using Asc_DynamicFunction(), thus avoiding the
109			* need for the caller to cast between data and function pointers.
110			* Never mind what the implementation does to achieve this.
111			* <pre>
112			* Example:
113			* int *value;
114			* value = (int *)Asc_DynamicVariable("lib.dll", "g_variable");
115			* </pre>
116			* @param libraryname Name of the dynamic library to query.
117			* @param varname Name of variable to look up in the library.
118			* @return A pointer to the variable in memory, or NULL if not found.
119			*/
120
121			typedef void (*DynamicF)(void);
122			/*< Function pointer type returned by Asc_DynamicFunction(). /
123
124			extern DynamicF Asc_DynamicFunction(CONST char *libraryname,
125			CONST char *funcname);
126			/**<
127			* Returns a pointer to a function exported from a dynamically-linked
128	jds	59	* library. It will generally be necessary to cast the returned pointer
129	jds	103	* to the correct function type before use. If either parameter
130	johnpye	466	* is NULL, or if the library or function cannot be located, then NULL
131	jds	103	* will be returned.
132	jds	59	* <pre>
133			* Example:
134			* typedef double (calcfunc)(double , double *);
135			* calcfunc calc;
136	jds	103	* calc = (calcfunc))Asc_DynamicFunction("lib.dll","calc");
137	jds	59	* </pre>
138			* @param libraryname Name of the dynamic library to query.
139	jds	103	* @param funcname Name of function to look up in the library.
140			* @return A pointer to the function in memory, or NULL if not found.
141	aw0a	1	*/
142
143	johnpye	163	#if defined(__GNUC__) \|\| (defined(__HPUX__) \|\| defined(__ALPHA_OSF__) \|\| \
144	jds	59	defined(__WIN32__) \|\| defined(__SUN_SOLARIS__) \|\| \
145			defined(__SUN_SUNOS__) \|\| defined(__SGI_IRIX__))
146			#define HAVE_DL_UNLOAD 1
147			/**<
148			* Set if a platform has a library unload function.
149	johnpye	158	* We don't know about aix, and others.
150	jds	59	*/
151			#endif
152	jds	54
153	johnpye	466	#endif
154
155	johnpye	158	#endif /* ASC_ASCDYNALOAD_H */
156	jds	59