include/llvm/System/MappedFile.h

   1 //===- llvm/System/MappedFile.h - MappedFile OS Concept ---------*- C++ -*-===//
   2 //
   3 //                     The LLVM Compiler Infrastructure
   4 //
   5 // This file was developed by Reid Spencer and is distributed under the
   6 // University of Illinois Open Source 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
  19 namespace llvm {
  20 namespace sys {
  21
  22   /// Forward declare a class used for holding platform specific information
  23   /// that needs to be
  24   struct MappedFileInfo;
  25
  26   /// This class provides an abstraction for a memory mapped file in the
  27   /// operating system's filesystem. It provides platform independent operations
  28   /// for mapping a file into memory for both read and write access. This class
  29   /// does not provide facilities for finding the file or operating on paths to
  30   /// files. The sys::Path class is used for that.
  31   /// @since 1.4
  32   /// @brief An abstraction for memory mapped files.
  33   class MappedFile {
  34   /// @name Types
  35   /// @{
  36   public:
  37     enum MappingOptions {
  38       READ_ACCESS = 0x0001,     ///< Map the file for reading
  39       WRITE_ACCESS = 0x0002,    ///< Map the file for write access
  40       EXEC_ACCESS = 0x0004,     ///< Map the file for execution access
  41       SHARED_MAPPING = 0x0008   ///< Map the file shared with other processes
  42     };
  43   /// @}
  44   /// @name Constructors
  45   /// @{
  46   public:
  47     /// Construct a MappedFile to the \p path in the operating system's file
  48     /// system with the mapping \p options provided.
  49     /// @throws std::string if an error occurs
  50     MappedFile(const Path& path, int options = READ_ACCESS)
  51       : path_(path), options_(options), base_(0), info_(0) { initialize(); }
  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     /// The mapped file is removed from memory. If the file was mapped for
 104     /// write access, the memory contents will be automatically synchronized
 105     /// with the file's disk contents.
 106     /// @brief Remove the file mapping from memory.
 107     void unmap();
 108
 109     /// The mapped file is put into memory.
 110     /// @returns The base memory address of the mapped file.
 111     /// @brief Map the file into memory.
 112     void* map();
 113
 114     /// This method causes the size of the file, and consequently the size
 115     /// of the mapping to be set. This is logically the same as unmap(),
 116     /// adjust size of the file, map(). Consequently, when calling this
 117     /// function, the caller should not rely on previous results of the
 118     /// map(), base(), or baseChar() members as they may point to invalid
 119     /// areas of memory after this call.
 120     /// @throws std::string if an error occurs
 121     /// @brief Set the size of the file and memory mapping.
 122     void size(size_t new_size);
 123
 124     void close() { terminate(); }
 125
 126   /// @}
 127   /// @name Implementation
 128   /// @{
 129   private:
 130     void initialize(); ///< Initialize platform-specific portion
 131     void terminate();  ///< Terminate platform-specific portion
 132
 133   /// @}
 134   /// @name Data
 135   /// @{
 136   private:
 137     sys::Path path_;       ///< Path to the file.
 138     int options_;          ///< Options used to create the mapping
 139     void* base_;           ///< Pointer to the base memory address
 140     mutable MappedFileInfo* info_; ///< Platform specific info for the mapping
 141
 142   /// @}
 143   /// @name Disabled
 144   /// @{
 145   private:
 146     ///< Disallow assignment
 147     MappedFile& operator = ( const MappedFile & that );
 148     ///< Disallow copying
 149     MappedFile(const MappedFile& that);
 150   /// @}
 151   };
 152 }
 153 }
 154
 155
 156 #endif