1 //===- llvm/System/MappedFile.h - MappedFile OS Concept ---------*- C++ -*-===//
3 // The LLVM Compiler Infrastructure
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.
8 //===----------------------------------------------------------------------===//
10 // This file declares the llvm::sys::MappedFile class.
12 //===----------------------------------------------------------------------===//
14 #ifndef LLVM_SYSTEM_MAPPEDFILE_H
15 #define LLVM_SYSTEM_MAPPEDFILE_H
17 #include "llvm/System/Path.h"
22 /// Forward declare a class used for holding platform specific information
24 struct MappedFileInfo;
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.
32 /// @brief An abstraction for memory mapped files.
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
44 /// @name Constructors
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(); }
53 /// Destruct a MappedFile and release all memory associated with it.
54 /// @throws std::string if an error occurs
55 ~MappedFile() { if (info_) terminate(); }
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
65 bool isMapped() const { return base_ != 0; }
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.
75 void* base() const { return base_; }
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.
85 char* charBase() const { return reinterpret_cast<char*>(base_); }
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
90 /// @returns sys::Path containing the path name.
91 /// @brief Returns the mapped file's path as a sys::Path
93 const sys::Path& path() const { return path_; }
95 /// This function returns the number of bytes in the file.
96 /// @throws std::string if an error occurs
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.
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.
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);
124 void close() { terminate(); }
127 /// @name Implementation
130 void initialize(); ///< Initialize platform-specific portion
131 void terminate(); ///< Terminate platform-specific portion
137 sys::Path path_; ///< Path to the file.
138 int options_; ///< Options used to create the mapping
139 void* base_; ///< Pointer to the base memory address
140 mutable MappedFileInfo* info_; ///< Platform specific info for the mapping
146 ///< Disallow assignment
147 MappedFile& operator = ( const MappedFile & that );
148 ///< Disallow copying
149 MappedFile(const MappedFile& that);