cleanup the MappedFile API and comments. This removes and updates

tons of out of date comments (really nothing throws here!) and fixes
some other fairly glaring issues: "size" used to return the size of 
the file *and* change it, depending on how you called it.



git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@49009 91177308-0d34-0410-b5e6-96231b3b80d8

1 files changed, 40 insertions, 95 deletions

diff --git a/include/llvm/System/MappedFile.h b/include/llvm/System/MappedFile.h
index af13cbb..6f902d2 100644
--- a/include/llvm/System/MappedFile.h
+++ b/include/llvm/System/MappedFile.h
@@ -28,145 +28,90 @@ namespace sys {
   /// for mapping a file into memory for both read and write access. This class
   /// does not provide facilities for finding the file or operating on paths to
   /// files. The sys::Path class is used for that.
-  /// @since 1.4
-  /// @brief An abstraction for memory mapped files.
   class MappedFile {
-  /// @name Types
-  /// @{
+    sys::PathWithStatus Path;        ///< Path to the file.
+    unsigned Options;                ///< Options used to create the mapping
+    void *BasePtr;                   ///< Pointer to the base memory address
+    mutable MappedFileInfo *MapInfo; ///< Platform specific info for the mapping
+    
+    MappedFile& operator=(const MappedFile &that); // DO NOT IMPLEMENT
+    MappedFile(const MappedFile &that); // DO NOT IMPLEMENT
   public:
     enum MappingOptions {
-      READ_ACCESS = 0x0001,     ///< Map the file for reading
-      WRITE_ACCESS = 0x0002,    ///< Map the file for write access
-      EXEC_ACCESS = 0x0004,     ///< Map the file for execution access
+      READ_ACCESS    = 0x0001,  ///< Map the file for reading
+      WRITE_ACCESS   = 0x0002,  ///< Map the file for write access
+      EXEC_ACCESS    = 0x0004,  ///< Map the file for execution access
       SHARED_MAPPING = 0x0008   ///< Map the file shared with other processes
     };
-  /// @}
-  /// @name Constructors
-  /// @{
-  public:
-    /// Construct a MappedFile to the \p path in the operating system's file
-    /// system with the mapping \p options provided.
-    /// @throws std::string if an error occurs
-    MappedFile() : path_(), options_(READ_ACCESS), base_(0), info_(0) {}
+    
+    MappedFile() : Options(READ_ACCESS), BasePtr(0), MapInfo(0) {}
 
     /// Destruct a MappedFile and release all memory associated with it.
-    /// @throws std::string if an error occurs
-    ~MappedFile() { if (info_) terminate(); }
+    ~MappedFile() { close(); }
+
+  public:  // Accessors
 
-  /// @}
-  /// @name Accessors
-  /// @{
-  public:
     /// This function determines if the file is currently mapped or not.
-    /// @returns true iff the file is mapped into memory, false otherwise
-    /// @brief Determine if a MappedFile is currently mapped
-    /// @throws nothing
-    bool isMapped() const { return base_ != 0; }
+    bool isMapped() const { return BasePtr != 0; }
 
     /// This function returns a void* pointer to the base address of the file
     /// mapping. This is the memory address of the first byte in the file.
     /// Note that although a non-const pointer is returned, the memory might
     /// not actually be writable, depending on the MappingOptions used when
     /// the MappedFile was opened.
-    /// @returns The base pointer to the memory mapped file.
-    /// @brief Obtain the base pointer to the memory mapped file.
-    /// @throws nothing
-    void* base() const { return base_; }
+    void* base() const { return BasePtr; }
 
     /// This function returns a char* pointer to the base address of the file
     /// mapping. This is the memory address of the first byte in the file.
     /// Note that although a non-const pointer is returned, the memory might
     /// not actually be writable, depending on the MappingOptions used when
     /// the MappedFile was opened.
-    /// @returns The base pointer to the memory mapped file as a char pointer.
-    /// @brief Obtain the base pointer to the memory mapped file.
-    /// @throws nothing
-    char* charBase() const { return reinterpret_cast<char*>(base_); }
+    char* charBase() const { return reinterpret_cast<char*>(BasePtr); }
 
     /// This function returns a reference to the sys::Path object kept by the
     /// MappedFile object. This contains the path to the file that is or
     /// will be mapped.
-    /// @returns sys::Path containing the path name.
-    /// @brief Returns the mapped file's path as a sys::Path
-    /// @throws nothing
-    const sys::Path& path() const { return path_; }
+    const sys::Path& path() const { return Path; }
 
     /// This function returns the number of bytes in the file.
-    /// @throws std::string if an error occurs
     size_t size() const;
 
-  /// @}
-  /// @name Mutators
-  /// @{
-  public:
-    /// Open a file to be mapped and get its size but don't map it yet.
-    /// @returns true if an error occurred
-    bool open(
-      const sys::Path& p, ///< Path to file to be mapped
-      int options = READ_ACCESS, ///< Access mode for the mapping
-      std::string* ErrMsg = 0 ///< Optional error string pointer
-    ) {
-      path_ = p;
-      options_ = options;
+  public:  // Mutators
+    
+    /// Open a file to be mapped and get its size but don't map it yet.  Return
+    /// true on error.
+    bool open(const sys::Path &P, int options = READ_ACCESS,
+              std::string *ErrMsg = 0) {
+      Path = P;
+      Options = options;
       return initialize(ErrMsg);
     }
 
-    /// The mapped file is removed from memory. If the file was mapped for
+    /// unmap - Remove the mapped file from memory. If the file was mapped for
     /// write access, the memory contents will be automatically synchronized
     /// with the file's disk contents.
-    /// @brief Remove the file mapping from memory.
     void unmap();
 
-    /// The mapped file is put into memory.
-    /// @returns The base memory address of the mapped file or 0 if an error
-    /// occurred.
-    /// @brief Map the file into memory.
-    void* map(
-      std::string* ErrMsg = 0///< Optional error string pointer
-    );
+    /// map - Reserve space for the file, map it into memory, and return a
+    /// pointer to it.  This returns the base memory address of the mapped file
+    /// or 0 if an error occurred.
+    void *map(std::string* ErrMsg = 0);
 
-    /// This method causes the size of the file, and consequently the size
-    /// of the mapping to be set. This is logically the same as unmap(),
+    /// resize - This method causes the size of the file, and consequently the
+    /// size of the mapping to be set. This is logically the same as unmap(),
     /// adjust size of the file, map(). Consequently, when calling this
     /// function, the caller should not rely on previous results of the
     /// map(), base(), or baseChar() members as they may point to invalid
     /// areas of memory after this call.
-    /// @throws std::string if an error occurs
-    /// @brief Set the size of the file and memory mapping.
-    bool size(size_t new_size, std::string* ErrMsg = 0);
+    bool resize(size_t new_size, std::string *ErrMsg = 0);
 
-    void close() { if (info_) terminate(); }
+    void close() { if (MapInfo) terminate(); }
 
-  /// @}
-  /// @name Implementation
-  /// @{
-  private:
-    /// @brief Initialize platform-specific portion
-    bool initialize(std::string* ErrMsg); 
-
-    /// @brief Terminate platform-specific portion
-    void terminate();  
-
-  /// @}
-  /// @name Data
-  /// @{
-  private:
-    sys::PathWithStatus path_;       ///< Path to the file.
-    int options_;          ///< Options used to create the mapping
-    void* base_;           ///< Pointer to the base memory address
-    mutable MappedFileInfo* info_; ///< Platform specific info for the mapping
-
-  /// @}
-  /// @name Disabled
-  /// @{
   private:
-    ///< Disallow assignment
-    MappedFile& operator=(const MappedFile &that);
-    ///< Disallow copying
-    MappedFile(const MappedFile& that);
-  /// @}
+    bool initialize(std::string *ErrMsg); 
+    void terminate();
   };
-}
-}
+} // end namespace sys
+} // end namespace llvm
 
 #endif