include/llvm/System/MappedFile.h

   1 //===- llvm/System/MappedFile.h - MappedFile OS Concept ---------*- 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 llvm::sys::MappedFile class.
  11 //
  12 //===----------------------------------------------------------------------===//
  13
  14 #ifndef LLVM_SYSTEM_MAPPEDFILE_H
  15 #define LLVM_SYSTEM_MAPPEDFILE_H
  16
  17 #include "llvm/System/Path.h"
  18 #include "llvm/System/IncludeFile.h"
  19
  20 namespace llvm {
  21 namespace sys {
  22
  23   /// Forward declare a class used for holding platform specific information
  24   /// that needs to be
  25   struct MappedFileInfo;
  26
  27   /// This class provides an abstraction for a memory mapped file in the
  28   /// operating system's filesystem. It provides platform independent operations
  29   /// for mapping a file into memory for both read and write access. This class
  30   /// does not provide facilities for finding the file or operating on paths to
  31   /// files. The sys::Path class is used for that.
  32   /// @since 1.4
  33   /// @brief An abstraction for memory mapped files.
  34   class MappedFile {
  35   /// @name Types
  36   /// @{
  37   public:
  38     enum MappingOptions {
  39       READ_ACCESS = 0x0001,     ///< Map the file for reading
  40       WRITE_ACCESS = 0x0002,    ///< Map the file for write access
  41       EXEC_ACCESS = 0x0004,     ///< Map the file for execution access
  42       SHARED_MAPPING = 0x0008   ///< Map the file shared with other processes
  43     };
  44   /// @}
  45   /// @name Constructors
  46   /// @{
  47   public:
  48     /// Construct a MappedFile to the \p path in the operating system's file
  49     /// system with the mapping \p options provided.
  50     /// @throws std::string if an error occurs
  51     MappedFile() : path_(), options_(READ_ACCESS), base_(0), info_(0) {}
  52
  53     /// Destruct a MappedFile and release all memory associated with it.
  54     /// @throws std::string if an error occurs
  55     ~MappedFile() { if (info_) terminate(); }
  56
  57   /// @}
  58   /// @name Accessors
  59   /// @{
  60   public:
  61     /// This function determines if the file is currently mapped or not.
  62     /// @returns true iff the file is mapped into memory, false otherwise
  63     /// @brief Determine if a MappedFile is currently mapped
  64     /// @throws nothing
  65     bool isMapped() const { return base_ != 0; }
  66
  67     /// This function returns a void* pointer to the base address of the file
  68     /// mapping. This is the memory address of the first byte in the file.
  69     /// Note that although a non-const pointer is returned, the memory might
  70     /// not actually be writable, depending on the MappingOptions used when
  71     /// the MappedFile was opened.
  72     /// @returns The base pointer to the memory mapped file.
  73     /// @brief Obtain the base pointer to the memory mapped file.
  74     /// @throws nothing
  75     void* base() const { return base_; }
  76
  77     /// This function returns a char* pointer to the base address of the file
  78     /// mapping. This is the memory address of the first byte in the file.
  79     /// Note that although a non-const pointer is returned, the memory might
  80     /// not actually be writable, depending on the MappingOptions used when
  81     /// the MappedFile was opened.
  82     /// @returns The base pointer to the memory mapped file as a char pointer.
  83     /// @brief Obtain the base pointer to the memory mapped file.
  84     /// @throws nothing
  85     char* charBase() const { return reinterpret_cast<char*>(base_); }
  86
  87     /// This function returns a reference to the sys::Path object kept by the
  88     /// MappedFile object. This contains the path to the file that is or
  89     /// will be mapped.
  90     /// @returns sys::Path containing the path name.
  91     /// @brief Returns the mapped file's path as a sys::Path
  92     /// @throws nothing
  93     const sys::Path& path() const { return path_; }
  94
  95     /// This function returns the number of bytes in the file.
  96     /// @throws std::string if an error occurs
  97     size_t size() const;
  98
  99   /// @}
 100   /// @name Mutators
 101   /// @{
 102   public:
 103     /// Open a file to be mapped and get its size but don't map it yet.
 104     /// @returns true if an error occurred
 105     bool open(
 106       const sys::Path& p, ///< Path to file to be mapped
 107       int options = READ_ACCESS, ///< Access mode for the mapping
 108       std::string* ErrMsg = 0 ///< Optional error string pointer
 109     ) {
 110       path_ = p;
 111       options_ = options;
 112       return initialize(ErrMsg);
 113     }
 114
 115     /// The mapped file is removed from memory. If the file was mapped for
 116     /// write access, the memory contents will be automatically synchronized
 117     /// with the file's disk contents.
 118     /// @brief Remove the file mapping from memory.
 119     void unmap();
 120
 121     /// The mapped file is put into memory.
 122     /// @returns The base memory address of the mapped file or 0 if an error
 123     /// occurred.
 124     /// @brief Map the file into memory.
 125     void* map(
 126       std::string* ErrMsg = 0///< Optional error string pointer
 127     );
 128
 129     /// This method causes the size of the file, and consequently the size
 130     /// of the mapping to be set. This is logically the same as unmap(),
 131     /// adjust size of the file, map(). Consequently, when calling this
 132     /// function, the caller should not rely on previous results of the
 133     /// map(), base(), or baseChar() members as they may point to invalid
 134     /// areas of memory after this call.
 135     /// @throws std::string if an error occurs
 136     /// @brief Set the size of the file and memory mapping.
 137     bool size(size_t new_size, std::string* ErrMsg = 0);
 138
 139     void close() { if (info_) terminate(); }
 140
 141   /// @}
 142   /// @name Implementation
 143   /// @{
 144   private:
 145     /// @brief Initialize platform-specific portion
 146     bool initialize(std::string* ErrMsg);
 147
 148     /// @brief Terminate platform-specific portion
 149     void terminate();
 150
 151   /// @}
 152   /// @name Data
 153   /// @{
 154   private:
 155     sys::PathWithStatus path_;       ///< Path to the file.
 156     int options_;          ///< Options used to create the mapping
 157     void* base_;           ///< Pointer to the base memory address
 158     mutable MappedFileInfo* info_; ///< Platform specific info for the mapping
 159
 160   /// @}
 161   /// @name Disabled
 162   /// @{
 163   private:
 164     ///< Disallow assignment
 165     MappedFile& operator = ( const MappedFile & that );
 166     ///< Disallow copying
 167     MappedFile(const MappedFile& that);
 168   /// @}
 169   };
 170 }
 171 }
 172
 173 FORCE_DEFINING_FILE_TO_BE_LINKED(SystemMappedFile)
 174
 175 #endif