llvm/Support/MemoryBuffer.h

0001 //===--- MemoryBuffer.h - Memory Buffer Interface ---------------*- C++ -*-===//
0002 //
0003 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
0004 // See https://llvm.org/LICENSE.txt for license information.
0005 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
0006 //
0007 //===----------------------------------------------------------------------===//
0008 //
0009 //  This file defines the MemoryBuffer interface.
0010 //
0011 //===----------------------------------------------------------------------===//
0012
0013 #ifndef LLVM_SUPPORT_MEMORYBUFFER_H
0014 #define LLVM_SUPPORT_MEMORYBUFFER_H
0015
0016 #include "llvm-c/Types.h"
0017 #include "llvm/ADT/ArrayRef.h"
0018 #include "llvm/ADT/StringRef.h"
0019 #include "llvm/ADT/Twine.h"
0020 #include "llvm/Support/Alignment.h"
0021 #include "llvm/Support/CBindingWrapping.h"
0022 #include "llvm/Support/ErrorOr.h"
0023 #include "llvm/Support/MemoryBufferRef.h"
0024 #include <cstddef>
0025 #include <cstdint>
0026 #include <memory>
0027
0028 namespace llvm {
0029 namespace sys {
0030 namespace fs {
0031 // Duplicated from FileSystem.h to avoid a dependency.
0032 #if defined(_WIN32)
0033 // A Win32 HANDLE is a typedef of void*
0034 using file_t = void *;
0035 #else
0036 using file_t = int;
0037 #endif
0038 } // namespace fs
0039 } // namespace sys
0040
0041 /// This interface provides simple read-only access to a block of memory, and
0042 /// provides simple methods for reading files and standard input into a memory
0043 /// buffer.  In addition to basic access to the characters in the file, this
0044 /// interface guarantees you can read one character past the end of the file,
0045 /// and that this character will read as '\0'.
0046 ///
0047 /// The '\0' guarantee is needed to support an optimization -- it's intended to
0048 /// be more efficient for clients which are reading all the data to stop
0049 /// reading when they encounter a '\0' than to continually check the file
0050 /// position to see if it has reached the end of the file.
0051 class MemoryBuffer {
0052   const char *BufferStart; // Start of the buffer.
0053   const char *BufferEnd;   // End of the buffer.
0054
0055 protected:
0056   MemoryBuffer() = default;
0057
0058   void init(const char *BufStart, const char *BufEnd,
0059             bool RequiresNullTerminator);
0060
0061 public:
0062   MemoryBuffer(const MemoryBuffer &) = delete;
0063   MemoryBuffer &operator=(const MemoryBuffer &) = delete;
0064   virtual ~MemoryBuffer();
0065
0066   const char *getBufferStart() const { return BufferStart; }
0067   const char *getBufferEnd() const   { return BufferEnd; }
0068   size_t getBufferSize() const { return BufferEnd-BufferStart; }
0069
0070   StringRef getBuffer() const {
0071     return StringRef(BufferStart, getBufferSize());
0072   }
0073
0074   /// Return an identifier for this buffer, typically the filename it was read
0075   /// from.
0076   virtual StringRef getBufferIdentifier() const { return "Unknown buffer"; }
0077
0078   /// For read-only MemoryBuffer_MMap, mark the buffer as unused in the near
0079   /// future and the kernel can free resources associated with it. Further
0080   /// access is supported but may be expensive. This calls
0081   /// madvise(MADV_DONTNEED) on read-only file mappings on *NIX systems. This
0082   /// function should not be called on a writable buffer.
0083   virtual void dontNeedIfMmap() {}
0084
0085   /// Open the specified file as a MemoryBuffer, returning a new MemoryBuffer
0086   /// if successful, otherwise returning null.
0087   ///
0088   /// \param IsText Set to true to indicate that the file should be read in
0089   /// text mode.
0090   ///
0091   /// \param IsVolatile Set to true to indicate that the contents of the file
0092   /// can change outside the user's control, e.g. when libclang tries to parse
0093   /// while the user is editing/updating the file or if the file is on an NFS.
0094   ///
0095   /// \param Alignment Set to indicate that the buffer should be aligned to at
0096   /// least the specified alignment.
0097   static ErrorOr<std::unique_ptr<MemoryBuffer>>
0098   getFile(const Twine &Filename, bool IsText = false,
0099           bool RequiresNullTerminator = true, bool IsVolatile = false,
0100           std::optional<Align> Alignment = std::nullopt);
0101
0102   /// Read all of the specified file into a MemoryBuffer as a stream
0103   /// (i.e. until EOF reached). This is useful for special files that
0104   /// look like a regular file but have 0 size (e.g. /proc/cpuinfo on Linux).
0105   static ErrorOr<std::unique_ptr<MemoryBuffer>>
0106   getFileAsStream(const Twine &Filename);
0107
0108   /// Given an already-open file descriptor, map some slice of it into a
0109   /// MemoryBuffer. The slice is specified by an \p Offset and \p MapSize.
0110   /// Since this is in the middle of a file, the buffer is not null terminated.
0111   static ErrorOr<std::unique_ptr<MemoryBuffer>>
0112   getOpenFileSlice(sys::fs::file_t FD, const Twine &Filename, uint64_t MapSize,
0113                    int64_t Offset, bool IsVolatile = false,
0114                    std::optional<Align> Alignment = std::nullopt);
0115
0116   /// Given an already-open file descriptor, read the file and return a
0117   /// MemoryBuffer.
0118   ///
0119   /// \param IsVolatile Set to true to indicate that the contents of the file
0120   /// can change outside the user's control, e.g. when libclang tries to parse
0121   /// while the user is editing/updating the file or if the file is on an NFS.
0122   ///
0123   /// \param Alignment Set to indicate that the buffer should be aligned to at
0124   /// least the specified alignment.
0125   static ErrorOr<std::unique_ptr<MemoryBuffer>>
0126   getOpenFile(sys::fs::file_t FD, const Twine &Filename, uint64_t FileSize,
0127               bool RequiresNullTerminator = true, bool IsVolatile = false,
0128               std::optional<Align> Alignment = std::nullopt);
0129
0130   /// Open the specified memory range as a MemoryBuffer. Note that InputData
0131   /// must be null terminated if RequiresNullTerminator is true.
0132   static std::unique_ptr<MemoryBuffer>
0133   getMemBuffer(StringRef InputData, StringRef BufferName = "",
0134                bool RequiresNullTerminator = true);
0135
0136   static std::unique_ptr<MemoryBuffer>
0137   getMemBuffer(MemoryBufferRef Ref, bool RequiresNullTerminator = true);
0138
0139   /// Open the specified memory range as a MemoryBuffer, copying the contents
0140   /// and taking ownership of it. InputData does not have to be null terminated.
0141   static std::unique_ptr<MemoryBuffer>
0142   getMemBufferCopy(StringRef InputData, const Twine &BufferName = "");
0143
0144   /// Read all of stdin into a file buffer, and return it.
0145   static ErrorOr<std::unique_ptr<MemoryBuffer>> getSTDIN();
0146
0147   /// Open the specified file as a MemoryBuffer, or open stdin if the Filename
0148   /// is "-".
0149   static ErrorOr<std::unique_ptr<MemoryBuffer>>
0150   getFileOrSTDIN(const Twine &Filename, bool IsText = false,
0151                  bool RequiresNullTerminator = true,
0152                  std::optional<Align> Alignment = std::nullopt);
0153
0154   /// Map a subrange of the specified file as a MemoryBuffer.
0155   static ErrorOr<std::unique_ptr<MemoryBuffer>>
0156   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
0157                bool IsVolatile = false,
0158                std::optional<Align> Alignment = std::nullopt);
0159
0160   //===--------------------------------------------------------------------===//
0161   // Provided for performance analysis.
0162   //===--------------------------------------------------------------------===//
0163
0164   /// The kind of memory backing used to support the MemoryBuffer.
0165   enum BufferKind {
0166     MemoryBuffer_Malloc,
0167     MemoryBuffer_MMap
0168   };
0169
0170   /// Return information on the memory mechanism used to support the
0171   /// MemoryBuffer.
0172   virtual BufferKind getBufferKind() const = 0;
0173
0174   MemoryBufferRef getMemBufferRef() const;
0175 };
0176
0177 /// This class is an extension of MemoryBuffer, which allows copy-on-write
0178 /// access to the underlying contents.  It only supports creation methods that
0179 /// are guaranteed to produce a writable buffer.  For example, mapping a file
0180 /// read-only is not supported.
0181 class WritableMemoryBuffer : public MemoryBuffer {
0182 protected:
0183   WritableMemoryBuffer() = default;
0184
0185 public:
0186   using MemoryBuffer::getBuffer;
0187   using MemoryBuffer::getBufferEnd;
0188   using MemoryBuffer::getBufferStart;
0189
0190   // const_cast is well-defined here, because the underlying buffer is
0191   // guaranteed to have been initialized with a mutable buffer.
0192   char *getBufferStart() {
0193     return const_cast<char *>(MemoryBuffer::getBufferStart());
0194   }
0195   char *getBufferEnd() {
0196     return const_cast<char *>(MemoryBuffer::getBufferEnd());
0197   }
0198   MutableArrayRef<char> getBuffer() {
0199     return {getBufferStart(), getBufferEnd()};
0200   }
0201
0202   static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
0203   getFile(const Twine &Filename, bool IsVolatile = false,
0204           std::optional<Align> Alignment = std::nullopt);
0205
0206   /// Map a subrange of the specified file as a WritableMemoryBuffer.
0207   static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
0208   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
0209                bool IsVolatile = false,
0210                std::optional<Align> Alignment = std::nullopt);
0211
0212   /// Allocate a new MemoryBuffer of the specified size that is not initialized.
0213   /// Note that the caller should initialize the memory allocated by this
0214   /// method. The memory is owned by the MemoryBuffer object.
0215   ///
0216   /// \param Alignment Set to indicate that the buffer should be aligned to at
0217   /// least the specified alignment.
0218   static std::unique_ptr<WritableMemoryBuffer>
0219   getNewUninitMemBuffer(size_t Size, const Twine &BufferName = "",
0220                         std::optional<Align> Alignment = std::nullopt);
0221
0222   /// Allocate a new zero-initialized MemoryBuffer of the specified size. Note
0223   /// that the caller need not initialize the memory allocated by this method.
0224   /// The memory is owned by the MemoryBuffer object.
0225   static std::unique_ptr<WritableMemoryBuffer>
0226   getNewMemBuffer(size_t Size, const Twine &BufferName = "");
0227
0228 private:
0229   // Hide these base class factory function so one can't write
0230   //   WritableMemoryBuffer::getXXX()
0231   // and be surprised that he got a read-only Buffer.
0232   using MemoryBuffer::getFileAsStream;
0233   using MemoryBuffer::getFileOrSTDIN;
0234   using MemoryBuffer::getMemBuffer;
0235   using MemoryBuffer::getMemBufferCopy;
0236   using MemoryBuffer::getOpenFile;
0237   using MemoryBuffer::getOpenFileSlice;
0238   using MemoryBuffer::getSTDIN;
0239 };
0240
0241 /// This class is an extension of MemoryBuffer, which allows write access to
0242 /// the underlying contents and committing those changes to the original source.
0243 /// It only supports creation methods that are guaranteed to produce a writable
0244 /// buffer.  For example, mapping a file read-only is not supported.
0245 class WriteThroughMemoryBuffer : public MemoryBuffer {
0246 protected:
0247   WriteThroughMemoryBuffer() = default;
0248
0249 public:
0250   using MemoryBuffer::getBuffer;
0251   using MemoryBuffer::getBufferEnd;
0252   using MemoryBuffer::getBufferStart;
0253
0254   // const_cast is well-defined here, because the underlying buffer is
0255   // guaranteed to have been initialized with a mutable buffer.
0256   char *getBufferStart() {
0257     return const_cast<char *>(MemoryBuffer::getBufferStart());
0258   }
0259   char *getBufferEnd() {
0260     return const_cast<char *>(MemoryBuffer::getBufferEnd());
0261   }
0262   MutableArrayRef<char> getBuffer() {
0263     return {getBufferStart(), getBufferEnd()};
0264   }
0265
0266   static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
0267   getFile(const Twine &Filename, int64_t FileSize = -1);
0268
0269   /// Map a subrange of the specified file as a ReadWriteMemoryBuffer.
0270   static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
0271   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset);
0272
0273 private:
0274   // Hide these base class factory function so one can't write
0275   //   WritableMemoryBuffer::getXXX()
0276   // and be surprised that he got a read-only Buffer.
0277   using MemoryBuffer::getFileAsStream;
0278   using MemoryBuffer::getFileOrSTDIN;
0279   using MemoryBuffer::getMemBuffer;
0280   using MemoryBuffer::getMemBufferCopy;
0281   using MemoryBuffer::getOpenFile;
0282   using MemoryBuffer::getOpenFileSlice;
0283   using MemoryBuffer::getSTDIN;
0284 };
0285
0286 // Create wrappers for C Binding types (see CBindingWrapping.h).
0287 DEFINE_SIMPLE_CONVERSION_FUNCTIONS(MemoryBuffer, LLVMMemoryBufferRef)
0288
0289 } // end namespace llvm
0290
0291 #endif // LLVM_SUPPORT_MEMORYBUFFER_H