UT_DSO.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT library (C++)
 *
 * COMMENTS:    Dynamic shared object management
 *
 */

#ifndef __UT_DSO_H__
#define __UT_DSO_H__

#include "FS_API.h"

#include <UT/UT_KnownPath.h>
#include <UT/UT_StringHolder.h>
#include <SYS/SYS_Hash.h>
#include <SYS/SYS_Types.h>
#include <utility>

#if defined( WIN32 )
    #define FS_DSO_EXTENSION    ".dll"
#elif defined( MBSD )
    #define FS_DSO_EXTENSION    ".dylib"
#else
    #define FS_DSO_EXTENSION    ".so"
#endif

namespace UT_Package
{
    class Package;
}

class dso_file;
class UT_String;

// This abstract class is only used as a return value from UT_DSO::loadDSO()
// and a parameter to UT_DSO::findSymbol().
class UT_DSOHandle;

class FS_API UT_DSO
{
public:
    // These static functions provide a much simplified and more generic
    // interface over UT_DSO objects.  They also correspond more directly to
    // the underlying system's dlopen/LoadLibrary, dlsym/GetProcAddress, and
    // dlclose/FreeLibrary interface than do UT_DSO objects.

    // loadDSO() will load one particular shared object, using the system's
    // standard search path.  A pointer to an opaque UT_DSOHandle object is
    // returned on success, and you can use this handle to look up symbols.
    // on failure, this function returns null.
    //
    // Unlike UT_DSO objects, it will not load all the shared objects it can
    // find in Houdini's search paths.  Also, a parameter controls whether or
    // not the symbols are available to shared objects that are loaded later.
    // UT_DSO objects instead look for a special function in the shared object
    // to determine if its symbols should be made available.
    static UT_DSOHandle *loadDSO(
            const char *file_name, bool available_to_later_loaded_libraries,
            UT_String *error = NULL);

    // get the filename from a DSO handle
    static UT_StringHolder getFilePath(
            UT_DSOHandle *handle, UT_StringHolder &error);

    // Find a symbol (function or global variable) in a loaded shared object.
    // Unlike the findProcedure() method on UT_DSO objects, you pass in
    // a dso object that's already been loaded, instead of a file name.  This
    // way you can quickly look up multiple symbols in the same shared library.
    // This function also doesn't for HoudiniDSOVersion symbols like UT_DSO
    // objects do.
    static void *findSymbol(UT_DSOHandle &handle, const char *symbol_name);

    // Decrement the reference cound on the loaded library, unloading it if
    // it's no longer used.
    static int closeDSO(UT_DSOHandle &handle);

    // Return the UT_DSOHandle for the main program.  This lets you look up
    // symbols in the main program from a shared library that was loaded.
    static UT_DSOHandle *getExecutable();

    // Return the UT_DSOHandle for a given loaded library.
    // Return NULL if the library is not loaded.
    // Use this function to check whether a particular library has been loaded
    // or to look up symbols in a library.
    static UT_DSOHandle *getLoadedLibrary(const char *lib_name);

    //------------------------------------------------------------------------

    // Given the name of a shared object, search for the file on disk using the
    // system's library path resolution mechanism and try to load it.  Returns
    // null if the file could not be found or couldn't be loaded for some
    // reason.
    static UT_DSOHandle *loadLibraryInPath(
        const char *shared_object_name,
        bool available_to_later_loaded_libraries);

    //------------------------------------------------------------------------

    // Load all the DSOs requested by the provided UT_Package.
    static void loadPackageSharedLibraries(const UT_Package::Package &pkg);

    //------------------------------------------------------------------------

    // Load a dynamic object and run the function specified.
    bool         run(const char *function_name, void *data = NULL,
                     bool validate_version = true);
    bool         run(const char *filename, const char *function_name,
                     void *data = NULL, bool validate_version = true,
                     UT_KnownPath path = UT_HOUDINI_DSO_PATH);

    // This will go through the available DSOs in reverse order.
    // Normally, we run them from $HOME -> $HFS.  However, if the
    // called procedure will override earlier on successive calls (rather
    // than ignore) the correct order should be $HFS -> $HOME.  This is
    // the case with CMDextendLibrary.
    bool         runReverse(const char *function_name, void *data = NULL,
                            bool validate_version = true);

    // Rather than running the function, simply load the dynamic object and
    // return a pointer to the function.  This returns a pointer to the
    // function (or NULL if no function was found).
    // The actual name of the dynamic object is returned in the fullpath string.
    void        *findProcedure(const char *filename, const char *function_name,
                               UT_StringHolder &fullpath,
                               bool validate_version = true,
                               bool err_on_missing_file = true);

    // Validate that the given opened shared library has the correct versions.
    // `filename` is used for HOUDINI_DSO_ERROR messages.
    static bool  checkDSOVersion(UT_DSOHandle *handle, const char *filename);

    // This will return the file which is currently being loaded (i.e. in the
    // run() command.  If there is no file, then it will return a null ptr.
    static const char   *getRunningFile();

    // Scans a dso folder and returns a list of library path 
    // files found in the folder. The shared libs can be cached for
    // further access.
    // folder_path: folder containing the dso files
    // add_to_cache: cache the libs found in the folder
    static UT_StringArray browseDSOFiles(const char* folder_path, bool add_to_cache=false);

    // Runs func_name from a specific library. If the library 
    // isn't provided, the function runs from the DSO cache.
    //  
    // func_name: Name of the function to execute from lib_path 
    //            or from all the cached libs.
    // user_data: optional data passed to the function.
    // lib_path: Library path.
    static bool runFunction(const char* func_name, void* user_data=nullptr, const char* lib_path=nullptr);

    // Runs func_name from a specific library (similar to runFunction). 
    // If the library isn't supplied, the function runs from the 
    // DSO cache in reverse order.
    //  
    // func_name: Name of the function to execute from lib_path 
    //            or from all the cached libs.
    // user_data: optional data passed to the function.
    // lib_path: Library path.
    static bool runFunctionReverse(const char* func_name, void* user_data=nullptr, const char* lib_path=nullptr);

    // Returns the last error message recorded while calling run
    // methods.
    static UT_StringHolder lastErrorMsg();

    /// The minimum compiler version that a DSO should be compiled in
    /// NOTE: Currently only enforced on Windows
    static std::pair<unsigned, unsigned> minAllowedCompilerVersion();

    /// The maximum compiler version that a DSO should be compiled in
    /// NOTE: Currently only enforced on Windows
    static std::pair<unsigned, unsigned> maxAllowedCompilerVersion();
};

#endif