include/llvm/Support/MemoryBuffer.h - llvm-project/llvm - Git at Google

 //===--- MemoryBuffer.h - Memory Buffer Interface ---------------*- C++ -*-===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 //
 //  This file defines the MemoryBuffer interface.
 //
 //===----------------------------------------------------------------------===//

 #ifndef LLVM_SUPPORT_MEMORYBUFFER_H
 #define LLVM_SUPPORT_MEMORYBUFFER_H

 #include "llvm-c/Types.h"
 #include "llvm/ADT/ArrayRef.h"
 #include "llvm/ADT/StringRef.h"
 #include "llvm/ADT/Twine.h"
 #include "llvm/Support/CBindingWrapping.h"
 #include "llvm/Support/ErrorOr.h"
 #include "llvm/Support/MemoryBufferRef.h"
 #include <cstddef>
 #include <cstdint>
 #include <memory>

 namespace llvm {
 namespace sys {
 namespace fs {
 // Duplicated from FileSystem.h to avoid a dependency.
 #if defined(_WIN32)
 // A Win32 HANDLE is a typedef of void*
 using file_t = void *;
 #else
 using file_t = int;
 #endif
 } // namespace fs
 } // namespace sys

 /// This interface provides simple read-only access to a block of memory, and
 /// provides simple methods for reading files and standard input into a memory
 /// buffer.  In addition to basic access to the characters in the file, this
 /// interface guarantees you can read one character past the end of the file,
 /// and that this character will read as '\0'.
 ///
 /// The '\0' guarantee is needed to support an optimization -- it's intended to
 /// be more efficient for clients which are reading all the data to stop
 /// reading when they encounter a '\0' than to continually check the file
 /// position to see if it has reached the end of the file.
 class MemoryBuffer {
   const char *BufferStart; // Start of the buffer.
   const char *BufferEnd;   // End of the buffer.

 protected:
   MemoryBuffer() = default;

   void init(const char *BufStart, const char *BufEnd,
             bool RequiresNullTerminator);

 public:
   MemoryBuffer(const MemoryBuffer &) = delete;
   MemoryBuffer &operator=(const MemoryBuffer &) = delete;
   virtual ~MemoryBuffer();

   const char *getBufferStart() const { return BufferStart; }
   const char *getBufferEnd() const   { return BufferEnd; }
   size_t getBufferSize() const { return BufferEnd-BufferStart; }

   StringRef getBuffer() const {
     return StringRef(BufferStart, getBufferSize());
   }

   /// Return an identifier for this buffer, typically the filename it was read
   /// from.
   virtual StringRef getBufferIdentifier() const { return "Unknown buffer"; }

   /// Open the specified file as a MemoryBuffer, returning a new MemoryBuffer
   /// if successful, otherwise returning null.
   ///
   /// \param IsText Set to true to indicate that the file should be read in
   /// text mode.
   ///
   /// \param IsVolatile Set to true to indicate that the contents of the file
   /// can change outside the user's control, e.g. when libclang tries to parse
   /// while the user is editing/updating the file or if the file is on an NFS.
   static ErrorOr<std::unique_ptr<MemoryBuffer>>
   getFile(const Twine &Filename, bool IsText = false,
           bool RequiresNullTerminator = true, bool IsVolatile = false);

   /// Read all of the specified file into a MemoryBuffer as a stream
   /// (i.e. until EOF reached). This is useful for special files that
   /// look like a regular file but have 0 size (e.g. /proc/cpuinfo on Linux).
   static ErrorOr<std::unique_ptr<MemoryBuffer>>
   getFileAsStream(const Twine &Filename);

   /// Given an already-open file descriptor, map some slice of it into a
   /// MemoryBuffer. The slice is specified by an \p Offset and \p MapSize.
   /// Since this is in the middle of a file, the buffer is not null terminated.
   static ErrorOr<std::unique_ptr<MemoryBuffer>>
   getOpenFileSlice(sys::fs::file_t FD, const Twine &Filename, uint64_t MapSize,
                    int64_t Offset, bool IsVolatile = false);

   /// Given an already-open file descriptor, read the file and return a
   /// MemoryBuffer.
   ///
   /// \param IsVolatile Set to true to indicate that the contents of the file
   /// can change outside the user's control, e.g. when libclang tries to parse
   /// while the user is editing/updating the file or if the file is on an NFS.
   static ErrorOr<std::unique_ptr<MemoryBuffer>>
   getOpenFile(sys::fs::file_t FD, const Twine &Filename, uint64_t FileSize,
               bool RequiresNullTerminator = true, bool IsVolatile = false);

   /// Open the specified memory range as a MemoryBuffer. Note that InputData
   /// must be null terminated if RequiresNullTerminator is true.
   static std::unique_ptr<MemoryBuffer>
   getMemBuffer(StringRef InputData, StringRef BufferName = "",
                bool RequiresNullTerminator = true);

   static std::unique_ptr<MemoryBuffer>
   getMemBuffer(MemoryBufferRef Ref, bool RequiresNullTerminator = true);

   /// Open the specified memory range as a MemoryBuffer, copying the contents
   /// and taking ownership of it. InputData does not have to be null terminated.
   static std::unique_ptr<MemoryBuffer>
   getMemBufferCopy(StringRef InputData, const Twine &BufferName = "");

   /// Read all of stdin into a file buffer, and return it.
   static ErrorOr<std::unique_ptr<MemoryBuffer>> getSTDIN();

   /// Open the specified file as a MemoryBuffer, or open stdin if the Filename
   /// is "-".
   static ErrorOr<std::unique_ptr<MemoryBuffer>>
   getFileOrSTDIN(const Twine &Filename, bool IsText = false,
                  bool RequiresNullTerminator = true);

   /// Map a subrange of the specified file as a MemoryBuffer.
   static ErrorOr<std::unique_ptr<MemoryBuffer>>
   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
                bool IsVolatile = false);

   //===--------------------------------------------------------------------===//
   // Provided for performance analysis.
   //===--------------------------------------------------------------------===//

   /// The kind of memory backing used to support the MemoryBuffer.
   enum BufferKind {
     MemoryBuffer_Malloc,
     MemoryBuffer_MMap
   };

   /// Return information on the memory mechanism used to support the
   /// MemoryBuffer.
   virtual BufferKind getBufferKind() const = 0;

   MemoryBufferRef getMemBufferRef() const;
 };

 /// This class is an extension of MemoryBuffer, which allows copy-on-write
 /// access to the underlying contents.  It only supports creation methods that
 /// are guaranteed to produce a writable buffer.  For example, mapping a file
 /// read-only is not supported.
 class WritableMemoryBuffer : public MemoryBuffer {
 protected:
   WritableMemoryBuffer() = default;

 public:
   using MemoryBuffer::getBuffer;
   using MemoryBuffer::getBufferEnd;
   using MemoryBuffer::getBufferStart;

   // const_cast is well-defined here, because the underlying buffer is
   // guaranteed to have been initialized with a mutable buffer.
   char *getBufferStart() {
     return const_cast<char *>(MemoryBuffer::getBufferStart());
   }
   char *getBufferEnd() {
     return const_cast<char *>(MemoryBuffer::getBufferEnd());
   }
   MutableArrayRef<char> getBuffer() {
     return {getBufferStart(), getBufferEnd()};
   }

   static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
   getFile(const Twine &Filename, bool IsVolatile = false);

   /// Map a subrange of the specified file as a WritableMemoryBuffer.
   static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
                bool IsVolatile = false);

   /// Allocate a new MemoryBuffer of the specified size that is not initialized.
   /// Note that the caller should initialize the memory allocated by this
   /// method. The memory is owned by the MemoryBuffer object.
   static std::unique_ptr<WritableMemoryBuffer>
   getNewUninitMemBuffer(size_t Size, const Twine &BufferName = "");

   /// Allocate a new zero-initialized MemoryBuffer of the specified size. Note
   /// that the caller need not initialize the memory allocated by this method.
   /// The memory is owned by the MemoryBuffer object.
   static std::unique_ptr<WritableMemoryBuffer>
   getNewMemBuffer(size_t Size, const Twine &BufferName = "");

 private:
   // Hide these base class factory function so one can't write
   //   WritableMemoryBuffer::getXXX()
   // and be surprised that he got a read-only Buffer.
   using MemoryBuffer::getFileAsStream;
   using MemoryBuffer::getFileOrSTDIN;
   using MemoryBuffer::getMemBuffer;
   using MemoryBuffer::getMemBufferCopy;
   using MemoryBuffer::getOpenFile;
   using MemoryBuffer::getOpenFileSlice;
   using MemoryBuffer::getSTDIN;
 };

 /// This class is an extension of MemoryBuffer, which allows write access to
 /// the underlying contents and committing those changes to the original source.
 /// It only supports creation methods that are guaranteed to produce a writable
 /// buffer.  For example, mapping a file read-only is not supported.
 class WriteThroughMemoryBuffer : public MemoryBuffer {
 protected:
   WriteThroughMemoryBuffer() = default;

 public:
   using MemoryBuffer::getBuffer;
   using MemoryBuffer::getBufferEnd;
   using MemoryBuffer::getBufferStart;

   // const_cast is well-defined here, because the underlying buffer is
   // guaranteed to have been initialized with a mutable buffer.
   char *getBufferStart() {
     return const_cast<char *>(MemoryBuffer::getBufferStart());
   }
   char *getBufferEnd() {
     return const_cast<char *>(MemoryBuffer::getBufferEnd());
   }
   MutableArrayRef<char> getBuffer() {
     return {getBufferStart(), getBufferEnd()};
   }

   static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
   getFile(const Twine &Filename, int64_t FileSize = -1);

   /// Map a subrange of the specified file as a ReadWriteMemoryBuffer.
   static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
   getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset);

 private:
   // Hide these base class factory function so one can't write
   //   WritableMemoryBuffer::getXXX()
   // and be surprised that he got a read-only Buffer.
   using MemoryBuffer::getFileAsStream;
   using MemoryBuffer::getFileOrSTDIN;
   using MemoryBuffer::getMemBuffer;
   using MemoryBuffer::getMemBufferCopy;
   using MemoryBuffer::getOpenFile;
   using MemoryBuffer::getOpenFileSlice;
   using MemoryBuffer::getSTDIN;
 };

 // Create wrappers for C Binding types (see CBindingWrapping.h).
 DEFINE_SIMPLE_CONVERSION_FUNCTIONS(MemoryBuffer, LLVMMemoryBufferRef)

 } // end namespace llvm

 #endif // LLVM_SUPPORT_MEMORYBUFFER_H
	//===--- MemoryBuffer.h - Memory Buffer Interface ---------------- C++ --===//
	//
	// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
	// See https://llvm.org/LICENSE.txt for license information.
	// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
	//
	//===----------------------------------------------------------------------===//
	//
	// This file defines the MemoryBuffer interface.
	//
	//===----------------------------------------------------------------------===//

	#ifndef LLVM_SUPPORT_MEMORYBUFFER_H
	#define LLVM_SUPPORT_MEMORYBUFFER_H

	#include "llvm-c/Types.h"
	#include "llvm/ADT/ArrayRef.h"
	#include "llvm/ADT/StringRef.h"
	#include "llvm/ADT/Twine.h"
	#include "llvm/Support/CBindingWrapping.h"
	#include "llvm/Support/ErrorOr.h"
	#include "llvm/Support/MemoryBufferRef.h"
	#include <cstddef>
	#include <cstdint>
	#include <memory>

	namespace llvm {
	namespace sys {
	namespace fs {
	// Duplicated from FileSystem.h to avoid a dependency.
	#if defined(_WIN32)
	// A Win32 HANDLE is a typedef of void*
	using file_t = void *;
	#else
	using file_t = int;
	#endif
	} // namespace fs
	} // namespace sys

	/// This interface provides simple read-only access to a block of memory, and
	/// provides simple methods for reading files and standard input into a memory
	/// buffer. In addition to basic access to the characters in the file, this
	/// interface guarantees you can read one character past the end of the file,
	/// and that this character will read as '\0'.
	///
	/// The '\0' guarantee is needed to support an optimization -- it's intended to
	/// be more efficient for clients which are reading all the data to stop
	/// reading when they encounter a '\0' than to continually check the file
	/// position to see if it has reached the end of the file.
	class MemoryBuffer {
	const char *BufferStart; // Start of the buffer.
	const char *BufferEnd; // End of the buffer.

	protected:
	MemoryBuffer() = default;

	void init(const char BufStart, const char BufEnd,
	bool RequiresNullTerminator);

	public:
	MemoryBuffer(const MemoryBuffer &) = delete;
	MemoryBuffer &operator=(const MemoryBuffer &) = delete;
	virtual ~MemoryBuffer();

	const char *getBufferStart() const { return BufferStart; }
	const char *getBufferEnd() const { return BufferEnd; }
	size_t getBufferSize() const { return BufferEnd-BufferStart; }

	StringRef getBuffer() const {
	return StringRef(BufferStart, getBufferSize());
	}

	/// Return an identifier for this buffer, typically the filename it was read
	/// from.
	virtual StringRef getBufferIdentifier() const { return "Unknown buffer"; }

	/// Open the specified file as a MemoryBuffer, returning a new MemoryBuffer
	/// if successful, otherwise returning null.
	///
	/// \param IsText Set to true to indicate that the file should be read in
	/// text mode.
	///
	/// \param IsVolatile Set to true to indicate that the contents of the file
	/// can change outside the user's control, e.g. when libclang tries to parse
	/// while the user is editing/updating the file or if the file is on an NFS.
	static ErrorOr<std::unique_ptr<MemoryBuffer>>
	getFile(const Twine &Filename, bool IsText = false,
	bool RequiresNullTerminator = true, bool IsVolatile = false);

	/// Read all of the specified file into a MemoryBuffer as a stream
	/// (i.e. until EOF reached). This is useful for special files that
	/// look like a regular file but have 0 size (e.g. /proc/cpuinfo on Linux).
	static ErrorOr<std::unique_ptr<MemoryBuffer>>
	getFileAsStream(const Twine &Filename);

	/// Given an already-open file descriptor, map some slice of it into a
	/// MemoryBuffer. The slice is specified by an \p Offset and \p MapSize.
	/// Since this is in the middle of a file, the buffer is not null terminated.
	static ErrorOr<std::unique_ptr<MemoryBuffer>>
	getOpenFileSlice(sys::fs::file_t FD, const Twine &Filename, uint64_t MapSize,
	int64_t Offset, bool IsVolatile = false);

	/// Given an already-open file descriptor, read the file and return a
	/// MemoryBuffer.
	///
	/// \param IsVolatile Set to true to indicate that the contents of the file
	/// can change outside the user's control, e.g. when libclang tries to parse
	/// while the user is editing/updating the file or if the file is on an NFS.
	static ErrorOr<std::unique_ptr<MemoryBuffer>>
	getOpenFile(sys::fs::file_t FD, const Twine &Filename, uint64_t FileSize,
	bool RequiresNullTerminator = true, bool IsVolatile = false);

	/// Open the specified memory range as a MemoryBuffer. Note that InputData
	/// must be null terminated if RequiresNullTerminator is true.
	static std::unique_ptr<MemoryBuffer>
	getMemBuffer(StringRef InputData, StringRef BufferName = "",
	bool RequiresNullTerminator = true);

	static std::unique_ptr<MemoryBuffer>
	getMemBuffer(MemoryBufferRef Ref, bool RequiresNullTerminator = true);

	/// Open the specified memory range as a MemoryBuffer, copying the contents
	/// and taking ownership of it. InputData does not have to be null terminated.
	static std::unique_ptr<MemoryBuffer>
	getMemBufferCopy(StringRef InputData, const Twine &BufferName = "");

	/// Read all of stdin into a file buffer, and return it.
	static ErrorOr<std::unique_ptr<MemoryBuffer>> getSTDIN();

	/// Open the specified file as a MemoryBuffer, or open stdin if the Filename
	/// is "-".
	static ErrorOr<std::unique_ptr<MemoryBuffer>>
	getFileOrSTDIN(const Twine &Filename, bool IsText = false,
	bool RequiresNullTerminator = true);

	/// Map a subrange of the specified file as a MemoryBuffer.
	static ErrorOr<std::unique_ptr<MemoryBuffer>>
	getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
	bool IsVolatile = false);

	//===--------------------------------------------------------------------===//
	// Provided for performance analysis.
	//===--------------------------------------------------------------------===//

	/// The kind of memory backing used to support the MemoryBuffer.
	enum BufferKind {
	MemoryBuffer_Malloc,
	MemoryBuffer_MMap
	};

	/// Return information on the memory mechanism used to support the
	/// MemoryBuffer.
	virtual BufferKind getBufferKind() const = 0;

	MemoryBufferRef getMemBufferRef() const;
	};

	/// This class is an extension of MemoryBuffer, which allows copy-on-write
	/// access to the underlying contents. It only supports creation methods that
	/// are guaranteed to produce a writable buffer. For example, mapping a file
	/// read-only is not supported.
	class WritableMemoryBuffer : public MemoryBuffer {
	protected:
	WritableMemoryBuffer() = default;

	public:
	using MemoryBuffer::getBuffer;
	using MemoryBuffer::getBufferEnd;
	using MemoryBuffer::getBufferStart;

	// const_cast is well-defined here, because the underlying buffer is
	// guaranteed to have been initialized with a mutable buffer.
	char *getBufferStart() {
	return const_cast<char *>(MemoryBuffer::getBufferStart());
	}
	char *getBufferEnd() {
	return const_cast<char *>(MemoryBuffer::getBufferEnd());
	}
	MutableArrayRef<char> getBuffer() {
	return {getBufferStart(), getBufferEnd()};
	}

	static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
	getFile(const Twine &Filename, bool IsVolatile = false);

	/// Map a subrange of the specified file as a WritableMemoryBuffer.
	static ErrorOr<std::unique_ptr<WritableMemoryBuffer>>
	getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset,
	bool IsVolatile = false);

	/// Allocate a new MemoryBuffer of the specified size that is not initialized.
	/// Note that the caller should initialize the memory allocated by this
	/// method. The memory is owned by the MemoryBuffer object.
	static std::unique_ptr<WritableMemoryBuffer>
	getNewUninitMemBuffer(size_t Size, const Twine &BufferName = "");

	/// Allocate a new zero-initialized MemoryBuffer of the specified size. Note
	/// that the caller need not initialize the memory allocated by this method.
	/// The memory is owned by the MemoryBuffer object.
	static std::unique_ptr<WritableMemoryBuffer>
	getNewMemBuffer(size_t Size, const Twine &BufferName = "");

	private:
	// Hide these base class factory function so one can't write
	// WritableMemoryBuffer::getXXX()
	// and be surprised that he got a read-only Buffer.
	using MemoryBuffer::getFileAsStream;
	using MemoryBuffer::getFileOrSTDIN;
	using MemoryBuffer::getMemBuffer;
	using MemoryBuffer::getMemBufferCopy;
	using MemoryBuffer::getOpenFile;
	using MemoryBuffer::getOpenFileSlice;
	using MemoryBuffer::getSTDIN;
	};

	/// This class is an extension of MemoryBuffer, which allows write access to
	/// the underlying contents and committing those changes to the original source.
	/// It only supports creation methods that are guaranteed to produce a writable
	/// buffer. For example, mapping a file read-only is not supported.
	class WriteThroughMemoryBuffer : public MemoryBuffer {
	protected:
	WriteThroughMemoryBuffer() = default;

	public:
	using MemoryBuffer::getBuffer;
	using MemoryBuffer::getBufferEnd;
	using MemoryBuffer::getBufferStart;

	// const_cast is well-defined here, because the underlying buffer is
	// guaranteed to have been initialized with a mutable buffer.
	char *getBufferStart() {
	return const_cast<char *>(MemoryBuffer::getBufferStart());
	}
	char *getBufferEnd() {
	return const_cast<char *>(MemoryBuffer::getBufferEnd());
	}
	MutableArrayRef<char> getBuffer() {
	return {getBufferStart(), getBufferEnd()};
	}

	static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
	getFile(const Twine &Filename, int64_t FileSize = -1);

	/// Map a subrange of the specified file as a ReadWriteMemoryBuffer.
	static ErrorOr<std::unique_ptr<WriteThroughMemoryBuffer>>
	getFileSlice(const Twine &Filename, uint64_t MapSize, uint64_t Offset);

	private:
	// Hide these base class factory function so one can't write
	// WritableMemoryBuffer::getXXX()
	// and be surprised that he got a read-only Buffer.
	using MemoryBuffer::getFileAsStream;
	using MemoryBuffer::getFileOrSTDIN;
	using MemoryBuffer::getMemBuffer;
	using MemoryBuffer::getMemBufferCopy;
	using MemoryBuffer::getOpenFile;
	using MemoryBuffer::getOpenFileSlice;
	using MemoryBuffer::getSTDIN;
	};

	// Create wrappers for C Binding types (see CBindingWrapping.h).
	DEFINE_SIMPLE_CONVERSION_FUNCTIONS(MemoryBuffer, LLVMMemoryBufferRef)

	} // end namespace llvm

	#endif // LLVM_SUPPORT_MEMORYBUFFER_H