llvm.org GIT mirror llvm / release_60 include / llvm / Support / DynamicLibrary.h
release_60

Tree @release_60 (Download .tar.gz)

DynamicLibrary.h @release_60

53ca1f3
63b3afa
0de02a6
 
7ed47a1
 
63b3afa
0de02a6
 
 
 
 
 
00e08fc
 
0de02a6
 
 
 
73a1ad8
 
 
0de02a6
 
 
63b3afa
0de02a6
 
f451cb8
0de02a6
8504690
 
 
0bce85f
 
 
0de02a6
77b6f2f
 
 
c68c862
77b6f2f
0bce85f
 
 
72501b4
7132e32
 
0bce85f
7132e32
0bce85f
 
 
 
 
 
 
 
 
 
dbf2bf7
0bce85f
 
 
a9b7d60
0bce85f
 
 
34bc6b6
0bce85f
3983dc2
 
 
dbf2bf7
 
3983dc2
 
 
 
 
0bce85f
 
 
a9b7d60
0bce85f
 
34bc6b6
0bce85f
 
7a93690
9d9b7c8
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
72501b4
0bce85f
72501b4
0bce85f
 
72501b4
 
 
0de02a6
72501b4
 
 
 
b0b0ea0
72501b4
 
 
 
0bce85f
dbf2bf7
 
0de02a6
 
cd52a7a
 
0de02a6
00e08fc
//===-- llvm/Support/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===//
//
//                     The LLVM Compiler Infrastructure
//
// This file is distributed under the University of Illinois Open Source
// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//
//
// This file declares the sys::DynamicLibrary class.
//
//===----------------------------------------------------------------------===//

#ifndef LLVM_SUPPORT_DYNAMICLIBRARY_H
#define LLVM_SUPPORT_DYNAMICLIBRARY_H

#include <string>

namespace llvm {

class StringRef;

namespace sys {

  /// This class provides a portable interface to dynamic libraries which also
  /// might be known as shared libraries, shared objects, dynamic shared
  /// objects, or dynamic link libraries. Regardless of the terminology or the
  /// operating system interface, this class provides a portable interface that
  /// allows dynamic libraries to be loaded and searched for externally
  /// defined symbols. This is typically used to provide "plug-in" support.
  /// It also allows for symbols to be defined which don't live in any library,
  /// but rather the main program itself, useful on Windows where the main
  /// executable cannot be searched.
  ///
  /// Note: there is currently no interface for temporarily loading a library,
  /// or for unloading libraries when the LLVM library is unloaded.
  class DynamicLibrary {
    // Placeholder whose address represents an invalid library.
    // We use this instead of NULL or a pointer-int pair because the OS library
    // might define 0 or 1 to be "special" handles, such as "search all".
    static char Invalid;

    // Opaque data used to interface with OS-specific dynamic library handling.
    void *Data;

  public:
    explicit DynamicLibrary(void *data = &Invalid) : Data(data) {}

    /// Returns true if the object refers to a valid library.
    bool isValid() const { return Data != &Invalid; }

    /// Searches through the library for the symbol \p symbolName. If it is
    /// found, the address of that symbol is returned. If not, NULL is returned.
    /// Note that NULL will also be returned if the library failed to load.
    /// Use isValid() to distinguish these cases if it is important.
    /// Note that this will \e not search symbols explicitly registered by
    /// AddSymbol().
    void *getAddressOfSymbol(const char *symbolName);

    /// This function permanently loads the dynamic library at the given path.
    /// The library will only be unloaded when llvm_shutdown() is called.
    /// This returns a valid DynamicLibrary instance on success and an invalid
    /// instance on failure (see isValid()). \p *errMsg will only be modified
    /// if the library fails to load.
    ///
    /// It is safe to call this function multiple times for the same library.
    /// @brief Open a dynamic library permanently.
    static DynamicLibrary getPermanentLibrary(const char *filename,
                                              std::string *errMsg = nullptr);

    /// Registers an externally loaded library. The library will be unloaded
    /// when the program terminates.
    ///
    /// It is safe to call this function multiple times for the same library,
    /// though ownership is only taken if there was no error.
    ///
    /// \returns An empty \p DynamicLibrary if the library was already loaded.
    static DynamicLibrary addPermanentLibrary(void *handle,
                                              std::string *errMsg = nullptr);

    /// This function permanently loads the dynamic library at the given path.
    /// Use this instead of getPermanentLibrary() when you won't need to get
    /// symbols from the library itself.
    ///
    /// It is safe to call this function multiple times for the same library.
    static bool LoadLibraryPermanently(const char *Filename,
                                       std::string *ErrMsg = nullptr) {
      return !getPermanentLibrary(Filename, ErrMsg).isValid();
    }

    enum SearchOrdering {
      /// SO_Linker - Search as a call to dlsym(dlopen(NULL)) would when
      /// DynamicLibrary::getPermanentLibrary(NULL) has been called or
      /// search the list of explcitly loaded symbols if not.
      SO_Linker,
      /// SO_LoadedFirst - Search all loaded libraries, then as SO_Linker would.
      SO_LoadedFirst,
      /// SO_LoadedLast - Search as SO_Linker would, then loaded libraries.
      /// Only useful to search if libraries with RTLD_LOCAL have been added.
      SO_LoadedLast,
      /// SO_LoadOrder - Or this in to search libraries in the ordered loaded.
      /// The default bahaviour is to search loaded libraries in reverse.
      SO_LoadOrder = 4
    };
    static SearchOrdering SearchOrder; // = SO_Linker

    /// This function will search through all previously loaded dynamic
    /// libraries for the symbol \p symbolName. If it is found, the address of
    /// that symbol is returned. If not, null is returned. Note that this will
    /// search permanently loaded libraries (getPermanentLibrary()) as well
    /// as explicitly registered symbols (AddSymbol()).
    /// @throws std::string on error.
    /// @brief Search through libraries for address of a symbol
    static void *SearchForAddressOfSymbol(const char *symbolName);

    /// @brief Convenience function for C++ophiles.
    static void *SearchForAddressOfSymbol(const std::string &symbolName) {
      return SearchForAddressOfSymbol(symbolName.c_str());
    }

    /// This functions permanently adds the symbol \p symbolName with the
    /// value \p symbolValue.  These symbols are searched before any
    /// libraries.
    /// @brief Add searchable symbol/value pair.
    static void AddSymbol(StringRef symbolName, void *symbolValue);

    class HandleSet;
  };

} // End sys namespace
} // End llvm namespace

#endif