LLVM API Documentation

Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

MappedFile.h

Go to the documentation of this file.
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() { 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();
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     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 // vim: sw=2
00156 
00157 #endif