HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UT_DSO.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: UT library (C++)
7  *
8  * COMMENTS: Dynamic shared object management
9  *
10  */
11 
12 #ifndef __UT_DSO_H__
13 #define __UT_DSO_H__
14 
15 #include "FS_API.h"
16 
17 #include <UT/UT_KnownPath.h>
18 #include <UT/UT_StringHolder.h>
19 #include <SYS/SYS_Hash.h>
20 #include <SYS/SYS_Types.h>
21 
22 #if defined( WIN32 )
23  #define FS_DSO_EXTENSION ".dll"
24 #elif defined( MBSD )
25  #define FS_DSO_EXTENSION ".dylib"
26 #else
27  #define FS_DSO_EXTENSION ".so"
28 #endif
29 
30 class dso_file;
31 class UT_String;
32 
33 // This abstract class is only used as a return value from UT_DSO::loadDSO()
34 // and a parameter to UT_DSO::findSymbol().
35 class UT_DSOHandle;
36 
37 class FS_API UT_DSO {
38 public:
39  // These static functions provide a much simplified and more generic
40  // interface over UT_DSO objects. They also correspond more directly to
41  // the underlying system's dlopen/LoadLibrary, dlsym/GetProcAddress, and
42  // dlclose/FreeLibrary interface than do UT_DSO objects.
43 
44  // loadDSO() will load one particular shared object, using the system's
45  // standard search path. A pointer to an opaque UT_DSOHandle object is
46  // returned on success, and you can use this handle to look up symbols.
47  // on failure, this function returns null.
48  //
49  // Unlike UT_DSO objects, it will not load all the shared objects it can
50  // find in Houdini's search paths. Also, a parameter controls whether or
51  // not the symbols are available to shared objects that are loaded later.
52  // UT_DSO objects instead look for a special function in the shared object
53  // to determine if its symbols should be made available.
54  static UT_DSOHandle *loadDSO(
55  const char *file_name, bool available_to_later_loaded_libraries,
56  UT_String *error = NULL);
57 
58  // get the filename from a DSO handle
59  static UT_StringHolder getFilePath(
60  UT_DSOHandle *handle, UT_StringHolder &error);
61 
62  // Find a symbol (function or global variable) in a loaded shared object.
63  // Unlike the findProcedure() method on UT_DSO objects, you pass in
64  // a dso object that's already been loaded, instead of a file name. This
65  // way you can quickly look up multiple symbols in the same shared library.
66  // This function also doesn't for HoudiniDSOVersion symbols like UT_DSO
67  // objects do.
68  static void *findSymbol(UT_DSOHandle &handle, const char *symbol_name);
69 
70  // Decrement the reference cound on the loaded library, unloading it if
71  // it's no longer used.
72  static int closeDSO(UT_DSOHandle &handle);
73 
74  // Return the UT_DSOHandle for the main program. This lets you look up
75  // symbols in the main program from a shared library that was loaded.
76  static UT_DSOHandle *getExecutable();
77 
78  // Return the UT_DSOHandle for a given loaded library.
79  // Return NULL if the library is not loaded.
80  // Use this function to check whether a particular library has been loaded
81  // or to look up symbols in a library.
82  static UT_DSOHandle *getLoadedLibrary(const char *lib_name);
83 
84  //------------------------------------------------------------------------
85 
86  // Given the name of a shared object, search for the file on disk using the
87  // system's library path resolution mechanism and try to load it. Returns
88  // null if the file could not be found or couldn't be loaded for some
89  // reason.
90  static UT_DSOHandle *loadLibraryInPath(
91  const char *shared_object_name,
92  bool available_to_later_loaded_libraries);
93 
94  //------------------------------------------------------------------------
95 
96  // Load a dynamic object and run the function specified.
97  bool run(const char *function_name, void *data = NULL,
98  bool validate_version = true);
99  bool run(const char *filename, const char *function_name,
100  void *data = NULL, bool validate_version = true,
102 
103  // This will go through the available DSOs in reverse order.
104  // Normally, we run them from $HOME -> $HFS. However, if the
105  // called procedure will override earlier on successive calls (rather
106  // than ignore) the correct order should be $HFS -> $HOME. This is
107  // the case with CMDextendLibrary.
108  bool runReverse(const char *function_name, void *data = NULL,
109  bool validate_version = true);
110 
111  // Rather than running the function, simply load the dynamic object and
112  // return a pointer to the function. This returns a pointer to the
113  // function (or NULL if no function was found).
114  // The actual name of the dynamic object is returned in the fullpath string.
115  void *findProcedure(const char *filename, const char *function_name,
116  UT_StringHolder &fullpath,
117  bool validate_version = true,
118  bool err_on_missing_file = true);
119 
120  // This will return the file which is currently being loaded (i.e. in the
121  // run() command. If there is no file, then it will return a null ptr.
122  static const char *getRunningFile();
123 
124 private:
125  bool dsoListRun(exint data_i,
126  const UT_StringRef& func_name,
127  void* func_data,
128  bool validate_version,
129  exint func_i);
130 
131  static bool checkDSOVersion(UT_DSOHandle *handle,
132  const char *filename);
133 
134  typedef void (*DSOCallback)(void *);
135  static DSOCallback loadDSOAndFindFunction(UT_DSOHandle *&handle,
136  const char *file_name,
137  const char *func_name,
138  bool validate_version,
139  bool err_on_missing_func);
140  static UT_DSOHandle *openLibrary(const char *filename);
141 private:
142  static const char *theRunningFile;
143 };
144 
145 #endif
GT_API const UT_StringHolder filename
UT_KnownPath
Definition: UT_KnownPath.h:14
void
Definition: png.h:1083
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
int64 exint
Definition: SYS_Types.h:125
< returns > If no error
Definition: snippets.dox:2
Definition: UT_DSO.h:37
Definition: format.h:895
#define FS_API
Definition: FS_API.h:10