include/llvm/Bytecode/Reader.h

   1 //===-- llvm/Bytecode/Reader.h - Reader for VM bytecode files ---*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by the LLVM research group and is distributed under
   6 // the University of Illinois Open Source License. See LICENSE.TXT for details.
   7 //
   8 //===----------------------------------------------------------------------===//
   9 //
  10 // This functionality is implemented by the lib/Bytecode/Reader library.
  11 // This library is used to read VM bytecode files from an iostream.
  12 //
  13 // Note that performance of this library is _crucial_ for performance of the
  14 // JIT type applications, so we have designed the bytecode format to support
  15 // quick reading.
  16 //
  17 //===----------------------------------------------------------------------===//
  18
  19 #ifndef LLVM_BYTECODE_READER_H
  20 #define LLVM_BYTECODE_READER_H
  21
  22 #include "llvm/System/Path.h"
  23 #include "llvm/ModuleProvider.h"
  24 #include "llvm/Module.h"
  25 #include <string>
  26
  27 namespace llvm {
  28
  29 // Forward declare the handler class
  30 class BytecodeHandler;
  31
  32 /// This function returns a ModuleProvider that can be used to do lazy
  33 /// function-at-a-time loading from a bytecode file.
  34 /// @returns NULL on error
  35 /// @returns ModuleProvider* if successful
  36 /// @brief Get a ModuleProvide for a bytecode file.
  37 ModuleProvider *getBytecodeModuleProvider(
  38   const std::string &Filename,  ///< Name of file to be read
  39   std::string* ErrMsg = 0,      ///< Optional error message holder
  40   BytecodeHandler* H = 0        ///< Optional handler for reader events
  41 );
  42
  43 /// This function returns a ModuleProvider that can be used to do lazy
  44 /// function function-at-a-time loading from a bytecode buffer.
  45 /// @returns NULL on error
  46 /// @returns ModuleProvider* if successful
  47 /// @brief Get a ModuleProvider for a bytecode buffer.
  48 ModuleProvider *getBytecodeBufferModuleProvider(
  49   const unsigned char *Buffer,    ///< Start of buffer to parse
  50   unsigned BufferSize,            ///< Size of the buffer
  51   const std::string &ModuleID,    ///< Name to give the module
  52   std::string* ErrMsg = 0,        ///< Optional place to return an error message
  53   BytecodeHandler* H = 0          ///< Optional handler for reader events
  54 );
  55
  56 /// This is the main interface to bytecode parsing. It opens the file specified
  57 /// by \p Filename and parses the entire file, returing the corresponding Module
  58 /// object if successful.
  59 /// @returns NULL on error
  60 /// @returns the module corresponding to the bytecode file, if successful
  61 /// @brief Parse the given bytecode file
  62 Module* ParseBytecodeFile(
  63   const std::string &Filename,    ///< Name of file to parse
  64   std::string *ErrMsg = 0         ///< Optional place to return an error message
  65 );
  66
  67 /// Parses a bytecode buffer specified by \p Buffer and \p BufferSize.
  68 /// @returns NULL on error
  69 /// @returns the module corresponding to the bytecode buffer, if successful
  70 /// @brief Parse a given bytecode buffer
  71 Module* ParseBytecodeBuffer(
  72   const unsigned char *Buffer,    ///< Start of buffer to parse
  73   unsigned BufferSize,            ///< Size of the buffer
  74   const std::string &ModuleID="", ///< Name to give the module
  75   std::string *ErrMsg = 0         ///< Optional place to return an error message
  76 );
  77
  78 /// This function will read only the necessary parts of a bytecode file in order
  79 /// to determine the list of dependent libraries encoded within it. The \p
  80 /// deplibs parameter will contain a vector of strings of the bytecode module's
  81 /// dependent libraries.
  82 /// @returns true on error, false otherwise
  83 /// @brief Get the list of dependent libraries from a bytecode file.
  84 bool GetBytecodeDependentLibraries(
  85   const std::string &fileName,       ///< File name to read bytecode from
  86   Module::LibraryListType& deplibs,  ///< List of dependent libraries extracted
  87   std::string* ErrMsg = 0            ///< Optional error message holder
  88 );
  89
  90 /// This function will read only the necessary parts of a bytecode file in order
  91 /// to obtain a list of externally visible global symbols that the bytecode
  92 /// module defines. This is used for archiving and linking when only the list
  93 /// of symbols the module defines is needed.
  94 /// @returns true on error, false otherwise
  95 /// @brief Get a bytecode file's externally visibile defined global symbols.
  96 bool GetBytecodeSymbols(
  97   const sys::Path& fileName,       ///< Filename to read bytecode from
  98   std::vector<std::string>& syms,  ///< Vector to return symbols in
  99   std::string* ErrMsg = 0          ///< Optional error message holder
 100 );
 101
 102 /// This function will read only the necessary parts of a bytecode buffer in
 103 /// order to obtain a list of externally visible global symbols that the
 104 /// bytecode module defines. This is used for archiving and linking when only
 105 /// the list of symbols the module defines is needed and the bytecode is
 106 /// already in memory.
 107 /// @returns the ModuleProvider on success, 0 if the bytecode can't be parsed
 108 /// @brief Get a bytecode file's externally visibile defined global symbols.
 109 ModuleProvider* GetBytecodeSymbols(
 110   const unsigned char*Buffer,        ///< The buffer to be parsed
 111   unsigned Length,                   ///< The length of \p Buffer
 112   const std::string& ModuleID,       ///< An identifier for the module
 113   std::vector<std::string>& symbols, ///< The symbols defined in the module
 114   std::string* ErrMsg = 0            ///< Optional error message holder
 115 );
 116
 117 } // End llvm namespace
 118
 119 #endif