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