1 | //===--- MemoryBuffer.h - Memory Buffer Interface ---------------*- C++ -*-===// |
2 | // |
3 | // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions. |
4 | // See https://llvm.org/LICENSE.txt for license information. |
5 | // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception |
6 | // |
7 | //===----------------------------------------------------------------------===// |
8 | // |
9 | // This file defines the MemoryBuffer interface. |
10 | // |
11 | //===----------------------------------------------------------------------===// |
12 | |
13 | #ifndef LLVM_SUPPORT_MEMORYBUFFER_H |
14 | #define LLVM_SUPPORT_MEMORYBUFFER_H |
15 | |
16 | #include "llvm-c/Types.h" |
17 | #include "llvm/ADT/ArrayRef.h" |
18 | #include "llvm/ADT/StringRef.h" |
19 | #include "llvm/ADT/Twine.h" |
20 | #include "llvm/Support/CBindingWrapping.h" |
21 | #include "llvm/Support/ErrorOr.h" |
22 | #include "llvm/Support/MemoryBufferRef.h" |
23 | #include <cstddef> |
24 | #include <cstdint> |
25 | #include <memory> |
26 | |
27 | namespace llvm { |
28 | namespace sys { |
29 | namespace fs { |
30 | // Duplicated from FileSystem.h to avoid a dependency. |
31 | #if defined(_WIN32) |
32 | // A Win32 HANDLE is a typedef of void* |
33 | using file_t = void *; |
34 | #else |
35 | using file_t = int; |
36 | #endif |
37 | } // namespace fs |
38 | } // namespace sys |
39 | |
40 | /// This interface provides simple read-only access to a block of memory, and |
41 | /// provides simple methods for reading files and standard input into a memory |
42 | /// buffer. In addition to basic access to the characters in the file, this |
43 | /// interface guarantees you can read one character past the end of the file, |
44 | /// and that this character will read as '\0'. |
45 | /// |
46 | /// The '\0' guarantee is needed to support an optimization -- it's intended to |
47 | /// be more efficient for clients which are reading all the data to stop |
48 | /// reading when they encounter a '\0' than to continually check the file |
49 | /// position to see if it has reached the end of the file. |
50 | class MemoryBuffer { |
51 | const char *BufferStart; // Start of the buffer. |
52 | const char *BufferEnd; // End of the buffer. |
53 | |
54 | protected: |
55 | MemoryBuffer() = default; |
56 | |
57 | void init(const char *BufStart, const char *BufEnd, |
58 | bool RequiresNullTerminator); |
59 | |
60 | public: |
61 | MemoryBuffer(const MemoryBuffer &) = delete; |
62 | MemoryBuffer &operator=(const MemoryBuffer &) = delete; |
63 | virtual ~MemoryBuffer(); |
64 | |
65 | const char *getBufferStart() const { return BufferStart; } |
66 | const char *getBufferEnd() const { return BufferEnd; } |
67 | size_t getBufferSize() const { return BufferEnd-BufferStart; } |
68 | |
69 | StringRef getBuffer() const { |
70 | return StringRef(BufferStart, getBufferSize()); |
71 | } |
72 | |
73 | /// Return an identifier for this buffer, typically the filename it was read |
74 | /// from. |
75 | virtual StringRef getBufferIdentifier() const { return "Unknown buffer" ; } |
76 | |
77 | /// For read-only MemoryBuffer_MMap, mark the buffer as unused in the near |
78 | /// future and the kernel can free resources associated with it. Further |
79 | /// access is supported but may be expensive. This calls |
80 | /// madvise(MADV_DONTNEED) on read-only file mappings on *NIX systems. This |
81 | /// function should not be called on a writable buffer. |
82 | virtual void dontNeedIfMmap() {} |
83 | |
84 | /// Open the specified file as a MemoryBuffer, returning a new MemoryBuffer |
85 | /// if successful, otherwise returning null. |
86 | /// |
87 | /// \param IsText Set to true to indicate that the file should be read in |
88 | /// text mode. |
89 | /// |
90 | /// \param IsVolatile Set to true to indicate that the contents of the file |
91 | /// can change outside the user's control, e.g. when libclang tries to parse |
92 | /// while the user is editing/updating the file or if the file is on an NFS. |
93 | static ErrorOr<std::unique_ptr<MemoryBuffer>> |
94 | getFile(const Twine &Filename, bool IsText = false, |
95 | bool RequiresNullTerminator = true, bool IsVolatile = false); |
96 | |
97 | /// Read all of the specified file into a MemoryBuffer as a stream |
98 | /// (i.e. until EOF reached). This is useful for special files that |
99 | /// look like a regular file but have 0 size (e.g. /proc/cpuinfo on Linux). |
100 | static ErrorOr<std::unique_ptr<MemoryBuffer>> |
101 | getFileAsStream(const Twine &Filename); |
102 | |
103 | /// Given an already-open file descriptor, map some slice of it into a |
104 | /// MemoryBuffer. The slice is specified by an \p Offset and \p MapSize. |
105 | /// Since this is in the middle of a file, the buffer is not null terminated. |
106 | static ErrorOr<std::unique_ptr<MemoryBuffer>> |
107 | getOpenFileSlice(sys::fs::file_t FD, const Twine &Filename, uint64_t MapSize, |
108 | int64_t Offset, bool IsVolatile = false); |
109 | |
110 | /// Given an already-open file descriptor, read the file and return a |
111 | /// MemoryBuffer. |
112 | /// |
113 | /// \param IsVolatile Set to true to indicate that the contents of the file |
114 | /// can change outside the user's control, e.g. when libclang tries to parse |
115 | /// while the user is editing/updating the file or if the file is on an NFS. |
116 | static ErrorOr<std::unique_ptr<MemoryBuffer>> |
117 | getOpenFile(sys::fs::file_t FD, const Twine &Filename, uint64_t FileSize, |
118 | bool RequiresNullTerminator = true, bool IsVolatile = false); |
119 | |
120 | /// Open the specified memory range as a MemoryBuffer. Note that InputData |
121 | /// must be null terminated if RequiresNullTerminator is true. |
122 | static std::unique_ptr<MemoryBuffer> |
123 | getMemBuffer(StringRef InputData, StringRef BufferName = "" , |
124 | bool RequiresNullTerminator = true); |
125 | |
126 | static std::unique_ptr<MemoryBuffer> |
127 | getMemBuffer(MemoryBufferRef Ref, bool RequiresNullTerminator = true); |
128 | |
129 | /// Open the specified memory range as a MemoryBuffer, copying the contents |
130 | /// and taking ownership of it. InputData does not have to be null terminated. |
131 | static std::unique_ptr<MemoryBuffer> |
132 | getMemBufferCopy(StringRef InputData, const Twine &BufferName = "" ); |
133 | |
134 | /// Read all of stdin into a file buffer, and return it. |
135 | static ErrorOr<std::unique_ptr<MemoryBuffer>> getSTDIN(); |
136 | |
137 | /// Open the specified file as a MemoryBuffer, or open stdin if the Filename |
138 | /// is "-". |
139 | static ErrorOr<std::unique_ptr<MemoryBuffer>> |
140 | getFileOrSTDIN(const Twine &Filename, bool IsText = false, |
141 | bool RequiresNullTerminator = true); |
142 | |
143 | /// Map a subrange of the specified file as a MemoryBuffer. |
144 | static ErrorOr<std::unique_ptr<MemoryBuffer>> |
145 | getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset, |
146 | bool IsVolatile = false); |
147 | |
148 | //===--------------------------------------------------------------------===// |
149 | // Provided for performance analysis. |
150 | //===--------------------------------------------------------------------===// |
151 | |
152 | /// The kind of memory backing used to support the MemoryBuffer. |
153 | enum BufferKind { |
154 | MemoryBuffer_Malloc, |
155 | MemoryBuffer_MMap |
156 | }; |
157 | |
158 | /// Return information on the memory mechanism used to support the |
159 | /// MemoryBuffer. |
160 | virtual BufferKind getBufferKind() const = 0; |
161 | |
162 | MemoryBufferRef getMemBufferRef() const; |
163 | }; |
164 | |
165 | /// This class is an extension of MemoryBuffer, which allows copy-on-write |
166 | /// access to the underlying contents. It only supports creation methods that |
167 | /// are guaranteed to produce a writable buffer. For example, mapping a file |
168 | /// read-only is not supported. |
169 | class WritableMemoryBuffer : public MemoryBuffer { |
170 | protected: |
171 | WritableMemoryBuffer() = default; |
172 | |
173 | public: |
174 | using MemoryBuffer::getBuffer; |
175 | using MemoryBuffer::getBufferEnd; |
176 | using MemoryBuffer::getBufferStart; |
177 | |
178 | // const_cast is well-defined here, because the underlying buffer is |
179 | // guaranteed to have been initialized with a mutable buffer. |
180 | char *getBufferStart() { |
181 | return const_cast<char *>(MemoryBuffer::getBufferStart()); |
182 | } |
183 | char *getBufferEnd() { |
184 | return const_cast<char *>(MemoryBuffer::getBufferEnd()); |
185 | } |
186 | MutableArrayRef<char> getBuffer() { |
187 | return {getBufferStart(), getBufferEnd()}; |
188 | } |
189 | |
190 | static ErrorOr<std::unique_ptr<WritableMemoryBuffer>> |
191 | getFile(const Twine &Filename, bool IsVolatile = false); |
192 | |
193 | /// Map a subrange of the specified file as a WritableMemoryBuffer. |
194 | static ErrorOr<std::unique_ptr<WritableMemoryBuffer>> |
195 | getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset, |
196 | bool IsVolatile = false); |
197 | |
198 | /// Allocate a new MemoryBuffer of the specified size that is not initialized. |
199 | /// Note that the caller should initialize the memory allocated by this |
200 | /// method. The memory is owned by the MemoryBuffer object. |
201 | static std::unique_ptr<WritableMemoryBuffer> |
202 | getNewUninitMemBuffer(size_t Size, const Twine &BufferName = "" ); |
203 | |
204 | /// Allocate a new zero-initialized MemoryBuffer of the specified size. Note |
205 | /// that the caller need not initialize the memory allocated by this method. |
206 | /// The memory is owned by the MemoryBuffer object. |
207 | static std::unique_ptr<WritableMemoryBuffer> |
208 | getNewMemBuffer(size_t Size, const Twine &BufferName = "" ); |
209 | |
210 | private: |
211 | // Hide these base class factory function so one can't write |
212 | // WritableMemoryBuffer::getXXX() |
213 | // and be surprised that he got a read-only Buffer. |
214 | using MemoryBuffer::getFileAsStream; |
215 | using MemoryBuffer::getFileOrSTDIN; |
216 | using MemoryBuffer::getMemBuffer; |
217 | using MemoryBuffer::getMemBufferCopy; |
218 | using MemoryBuffer::getOpenFile; |
219 | using MemoryBuffer::getOpenFileSlice; |
220 | using MemoryBuffer::getSTDIN; |
221 | }; |
222 | |
223 | /// This class is an extension of MemoryBuffer, which allows write access to |
224 | /// the underlying contents and committing those changes to the original source. |
225 | /// It only supports creation methods that are guaranteed to produce a writable |
226 | /// buffer. For example, mapping a file read-only is not supported. |
227 | class WriteThroughMemoryBuffer : public MemoryBuffer { |
228 | protected: |
229 | WriteThroughMemoryBuffer() = default; |
230 | |
231 | public: |
232 | using MemoryBuffer::getBuffer; |
233 | using MemoryBuffer::getBufferEnd; |
234 | using MemoryBuffer::getBufferStart; |
235 | |
236 | // const_cast is well-defined here, because the underlying buffer is |
237 | // guaranteed to have been initialized with a mutable buffer. |
238 | char *getBufferStart() { |
239 | return const_cast<char *>(MemoryBuffer::getBufferStart()); |
240 | } |
241 | char *getBufferEnd() { |
242 | return const_cast<char *>(MemoryBuffer::getBufferEnd()); |
243 | } |
244 | MutableArrayRef<char> getBuffer() { |
245 | return {getBufferStart(), getBufferEnd()}; |
246 | } |
247 | |
248 | static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>> |
249 | getFile(const Twine &Filename, int64_t FileSize = -1); |
250 | |
251 | /// Map a subrange of the specified file as a ReadWriteMemoryBuffer. |
252 | static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>> |
253 | getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset); |
254 | |
255 | private: |
256 | // Hide these base class factory function so one can't write |
257 | // WritableMemoryBuffer::getXXX() |
258 | // and be surprised that he got a read-only Buffer. |
259 | using MemoryBuffer::getFileAsStream; |
260 | using MemoryBuffer::getFileOrSTDIN; |
261 | using MemoryBuffer::getMemBuffer; |
262 | using MemoryBuffer::getMemBufferCopy; |
263 | using MemoryBuffer::getOpenFile; |
264 | using MemoryBuffer::getOpenFileSlice; |
265 | using MemoryBuffer::getSTDIN; |
266 | }; |
267 | |
268 | // Create wrappers for C Binding types (see CBindingWrapping.h). |
269 | DEFINE_SIMPLE_CONVERSION_FUNCTIONS(MemoryBuffer, LLVMMemoryBufferRef) |
270 | |
271 | } // end namespace llvm |
272 | |
273 | #endif // LLVM_SUPPORT_MEMORYBUFFER_H |
274 | |