DynamicLibrary.h revision 218893 
1//===-- llvm/Support/DynamicLibrary.h - Portable Dynamic Library -*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9//
10// This file declares the sys::DynamicLibrary class.
11//
12//===----------------------------------------------------------------------===//
13
14#ifndef LLVM_SYSTEM_DYNAMIC_LIBRARY_H
15#define LLVM_SYSTEM_DYNAMIC_LIBRARY_H
16
17#include <string>
18
19namespace llvm {
20namespace sys {
21
22  /// This class provides a portable interface to dynamic libraries which also
23  /// might be known as shared libraries, shared objects, dynamic shared
24  /// objects, or dynamic link libraries. Regardless of the terminology or the
25  /// operating system interface, this class provides a portable interface that
26  /// allows dynamic libraries to be loaded and searched for externally
27  /// defined symbols. This is typically used to provide "plug-in" support.
28  /// It also allows for symbols to be defined which don't live in any library,
29  /// but rather the main program itself, useful on Windows where the main
30  /// executable cannot be searched.
31  class DynamicLibrary {
32    DynamicLibrary(); // DO NOT IMPLEMENT
33  public:
34    /// This function allows a library to be loaded without instantiating a
35    /// DynamicLibrary object. Consequently, it is marked as being permanent
36    /// and will only be unloaded when the program terminates.  This returns
37    /// false on success or returns true and fills in *ErrMsg on failure.
38    /// @brief Open a dynamic library permanently.
39    ///
40    /// NOTE: This function is not thread safe.
41    ///
42    static bool LoadLibraryPermanently(const char *filename,
43                                       std::string *ErrMsg = 0);
44
45    /// This function will search through all previously loaded dynamic
46    /// libraries for the symbol \p symbolName. If it is found, the addressof
47    /// that symbol is returned. If not, null is returned. Note that this will
48    /// search permanently loaded libraries (LoadLibraryPermanently) as well
49    /// as ephemerally loaded libraries (constructors).
50    /// @throws std::string on error.
51    /// @brief Search through libraries for address of a symbol
52    ///
53    /// NOTE: This function is not thread safe.
54    ///
55    static void *SearchForAddressOfSymbol(const char *symbolName);
56
57    /// @brief Convenience function for C++ophiles.
58    ///
59    /// NOTE: This function is not thread safe.
60    ///
61    static void *SearchForAddressOfSymbol(const std::string &symbolName) {
62      return SearchForAddressOfSymbol(symbolName.c_str());
63    }
64
65    /// This functions permanently adds the symbol \p symbolName with the
66    /// value \p symbolValue.  These symbols are searched before any
67    /// libraries.
68    /// @brief Add searchable symbol/value pair.
69    ///
70    /// NOTE: This function is not thread safe.
71    ///
72    static void AddSymbol(const char *symbolName, void *symbolValue);
73
74    /// @brief Convenience function for C++ophiles.
75    ///
76    /// NOTE: This function is not thread safe.
77    ///
78    static void AddSymbol(const std::string &symbolName, void *symbolValue) {
79      AddSymbol(symbolName.c_str(), symbolValue);
80    }
81  };
82
83} // End sys namespace
84} // End llvm namespace
85
86#endif // LLVM_SYSTEM_DYNAMIC_LIBRARY_H
87