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() { 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();
  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   /// @}
 125   /// @name Implementation
 126   /// @{
 127   private:
 128     void initialize(); ///< Initialize platform-specific portion
 129     void terminate();  ///< Terminate platform-specific portion
 130
 131   /// @}
 132   /// @name Data
 133   /// @{
 134   private:
 135     sys::Path path_;       ///< Path to the file.
 136     int options_;          ///< Options used to create the mapping
 137     void* base_;           ///< Pointer to the base memory address
 138     MappedFileInfo* info_; ///< Platform specific info for the mapping
 139
 140   /// @}
 141   /// @name Disabled
 142   /// @{
 143   private:
 144     ///< Disallow assignment
 145     MappedFile& operator = ( const MappedFile & that );
 146     ///< Disallow copying
 147     MappedFile(const MappedFile& that);
 148   /// @}
 149   };
 150 }
 151 }
 152
 153 // vim: sw=2
 154
 155 #endif