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	/* 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	/* ChangeLog
20	* 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	*
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	*/
29
30	/** @file
31	* Dynamic library routines.
32	* <pre>
33	* Reaquires:
34	* #include "utilities/ascConfig.h"
35	* </pre>
36	*/
37
38	#ifndef ASC_ASCDYNALOAD_H
39	#define ASC_ASCDYNALOAD_H
40
41	#ifdef DYNAMIC_PACKAGES
42
43	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	*
49	* 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	*/
67
68	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	*
75	* 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	*
83	* @param path Path to the dynamic library to unload.
84	* @return Returns 0 if the library was successfully located and unloaded,
85	* -3 if the library was not located, or the return value of
86	* 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	*/
91
92	#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	/**<
98	* Returns a pointer to a variable exported from a dynamically-linked
99	* 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	* will be returned.<br><br>
103	*
104	* This function was previously called Asc_DynamicSymbol() and could
105	* 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	* library. It will generally be necessary to cast the returned pointer
129	* to the correct function type before use. If either parameter
130	* is NULL, or if the library or function cannot be located, then NULL
131	* will be returned.
132	* <pre>
133	* Example:
134	* typedef double (calcfunc)(double , double *);
135	* calcfunc calc;
136	* calc = (calcfunc))Asc_DynamicFunction("lib.dll","calc");
137	* </pre>
138	* @param libraryname Name of the dynamic library to query.
139	* @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	*/
142
143	#if defined(__GNUC__) \|\| (defined(__HPUX__) \|\| defined(__ALPHA_OSF__) \|\| \
144	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	* We don't know about aix, and others.
150	*/
151	#endif
152
153	#endif
154
155	#endif /* ASC_ASCDYNALOAD_H */
156