LLVM API Documentation

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