LLVM API Documentation
00001 //===- llvm/System/MappedFile.h - MappedFile OS Concept ---------*- C++ -*-===// 00002 // 00003 // The LLVM Compiler Infrastructure 00004 // 00005 // This file was developed by Reid Spencer and is distributed under the 00006 // University of Illinois Open Source License. See LICENSE.TXT for details. 00007 // 00008 //===----------------------------------------------------------------------===// 00009 // 00010 // This file declares the llvm::sys::MappedFile class. 00011 // 00012 //===----------------------------------------------------------------------===// 00013 00014 #ifndef LLVM_SYSTEM_MAPPEDFILE_H 00015 #define LLVM_SYSTEM_MAPPEDFILE_H 00016 00017 #include "llvm/System/Path.h" 00018 00019 namespace llvm { 00020 namespace sys { 00021 00022 /// Forward declare a class used for holding platform specific information 00023 /// that needs to be 00024 struct MappedFileInfo; 00025 00026 /// This class provides an abstraction for a memory mapped file in the 00027 /// operating system's filesystem. It provides platform independent operations 00028 /// for mapping a file into memory for both read and write access. This class 00029 /// does not provide facilities for finding the file or operating on paths to 00030 /// files. The sys::Path class is used for that. 00031 /// @since 1.4 00032 /// @brief An abstraction for memory mapped files. 00033 class MappedFile { 00034 /// @name Types 00035 /// @{ 00036 public: 00037 enum MappingOptions { 00038 READ_ACCESS = 0x0001, ///< Map the file for reading 00039 WRITE_ACCESS = 0x0002, ///< Map the file for write access 00040 EXEC_ACCESS = 0x0004, ///< Map the file for execution access 00041 SHARED_MAPPING = 0x0008 ///< Map the file shared with other processes 00042 }; 00043 /// @} 00044 /// @name Constructors 00045 /// @{ 00046 public: 00047 /// Construct a MappedFile to the \p path in the operating system's file 00048 /// system with the mapping \p options provided. 00049 /// @throws std::string if an error occurs 00050 MappedFile(const Path& path, int options = READ_ACCESS) 00051 : path_(path), options_(options), base_(0), info_(0) { initialize(); } 00052 00053 /// Destruct a MappedFile and release all memory associated with it. 00054 /// @throws std::string if an error occurs 00055 ~MappedFile() { if (info_) terminate(); } 00056 00057 /// @} 00058 /// @name Accessors 00059 /// @{ 00060 public: 00061 /// This function determines if the file is currently mapped or not. 00062 /// @returns true iff the file is mapped into memory, false otherwise 00063 /// @brief Determine if a MappedFile is currently mapped 00064 /// @throws nothing 00065 bool isMapped() const { return base_ != 0; } 00066 00067 /// This function returns a void* pointer to the base address of the file 00068 /// mapping. This is the memory address of the first byte in the file. 00069 /// Note that although a non-const pointer is returned, the memory might 00070 /// not actually be writable, depending on the MappingOptions used when 00071 /// the MappedFile was opened. 00072 /// @returns The base pointer to the memory mapped file. 00073 /// @brief Obtain the base pointer to the memory mapped file. 00074 /// @throws nothing 00075 void* base() const { return base_; } 00076 00077 /// This function returns a char* pointer to the base address of the file 00078 /// mapping. This is the memory address of the first byte in the file. 00079 /// Note that although a non-const pointer is returned, the memory might 00080 /// not actually be writable, depending on the MappingOptions used when 00081 /// the MappedFile was opened. 00082 /// @returns The base pointer to the memory mapped file as a char pointer. 00083 /// @brief Obtain the base pointer to the memory mapped file. 00084 /// @throws nothing 00085 char* charBase() const { return reinterpret_cast<char*>(base_); } 00086 00087 /// This function returns a reference to the sys::Path object kept by the 00088 /// MappedFile object. This contains the path to the file that is or 00089 /// will be mapped. 00090 /// @returns sys::Path containing the path name. 00091 /// @brief Returns the mapped file's path as a sys::Path 00092 /// @throws nothing 00093 const sys::Path& path() const { return path_; } 00094 00095 /// This function returns the number of bytes in the file. 00096 /// @throws std::string if an error occurs 00097 size_t size() const; 00098 00099 /// @} 00100 /// @name Mutators 00101 /// @{ 00102 public: 00103 /// The mapped file is removed from memory. If the file was mapped for 00104 /// write access, the memory contents will be automatically synchronized 00105 /// with the file's disk contents. 00106 /// @brief Remove the file mapping from memory. 00107 void unmap(); 00108 00109 /// The mapped file is put into memory. 00110 /// @returns The base memory address of the mapped file. 00111 /// @brief Map the file into memory. 00112 void* map(); 00113 00114 /// This method causes the size of the file, and consequently the size 00115 /// of the mapping to be set. This is logically the same as unmap(), 00116 /// adjust size of the file, map(). Consequently, when calling this 00117 /// function, the caller should not rely on previous results of the 00118 /// map(), base(), or baseChar() members as they may point to invalid 00119 /// areas of memory after this call. 00120 /// @throws std::string if an error occurs 00121 /// @brief Set the size of the file and memory mapping. 00122 void size(size_t new_size); 00123 00124 void close() { terminate(); } 00125 00126 /// @} 00127 /// @name Implementation 00128 /// @{ 00129 private: 00130 void initialize(); ///< Initialize platform-specific portion 00131 void terminate(); ///< Terminate platform-specific portion 00132 00133 /// @} 00134 /// @name Data 00135 /// @{ 00136 private: 00137 sys::Path path_; ///< Path to the file. 00138 int options_; ///< Options used to create the mapping 00139 void* base_; ///< Pointer to the base memory address 00140 mutable MappedFileInfo* info_; ///< Platform specific info for the mapping 00141 00142 /// @} 00143 /// @name Disabled 00144 /// @{ 00145 private: 00146 ///< Disallow assignment 00147 MappedFile& operator = ( const MappedFile & that ); 00148 ///< Disallow copying 00149 MappedFile(const MappedFile& that); 00150 /// @} 00151 }; 00152 } 00153 } 00154 00155 00156 #endif