1 files changed, 37 insertions, 33 deletions

diff --git a/include/llvm/Support/MemoryObject.h b/include/llvm/Support/MemoryObject.h
index 17aa9d2..e0c8749 100644
--- a/include/llvm/Support/MemoryObject.h
+++ b/include/llvm/Support/MemoryObject.h
@@ -14,49 +14,53 @@
 
 namespace llvm {
 
-/// MemoryObject - Abstract base class for contiguous addressable memory.
-///   Necessary for cases in which the memory is in another process, in a
-///   file, or on a remote machine.
-///   All size and offset parameters are uint64_ts, to allow 32-bit processes
-///   access to 64-bit address spaces.
+/// Interface to data which might be streamed. Streamability has 2 important
+/// implications/restrictions. First, the data might not yet exist in memory
+/// when the request is made. This just means that readByte/readBytes might have
+/// to block or do some work to get it. More significantly, the exact size of
+/// the object might not be known until it has all been fetched. This means that
+/// to return the right result, getExtent must also wait for all the data to
+/// arrive; therefore it should not be called on objects which are actually
+/// streamed (this would defeat the purpose of streaming). Instead,
+/// isValidAddress can be used to test addresses without knowing the exact size
+/// of the stream. Finally, getPointer can be used instead of readBytes to avoid
+/// extra copying.
 class MemoryObject {
 public:
-  /// Destructor      - Override as necessary.
   virtual ~MemoryObject();
 
-  /// getBase         - Returns the lowest valid address in the region.
-  ///
-  /// @result         - The lowest valid address.
-  virtual uint64_t getBase() const = 0;
-
-  /// getExtent       - Returns the size of the region in bytes.  (The region is
-  ///                   contiguous, so the highest valid address of the region
-  ///                   is getBase() + getExtent() - 1).
+  /// Returns the size of the region in bytes.  (The region is contiguous, so
+  /// the highest valid address of the region is getExtent() - 1).
   ///
   /// @result         - The size of the region.
   virtual uint64_t getExtent() const = 0;
 
-  /// readByte        - Tries to read a single byte from the region.
-  ///
-  /// @param address  - The address of the byte, in the same space as getBase().
-  /// @param ptr      - A pointer to a byte to be filled in.  Must be non-NULL.
-  /// @result         - 0 if successful; -1 if not.  Failure may be due to a
-  ///                   bounds violation or an implementation-specific error.
-  virtual int readByte(uint64_t address, uint8_t *ptr) const = 0;
-
-  /// readBytes       - Tries to read a contiguous range of bytes from the
-  ///                   region, up to the end of the region.
-  ///                   You should override this function if there is a quicker
-  ///                   way than going back and forth with individual bytes.
+  /// Tries to read a contiguous range of bytes from the region, up to the end
+  /// of the region.
   ///
-  /// @param address  - The address of the first byte, in the same space as 
-  ///                   getBase().
-  /// @param size     - The number of bytes to copy.
-  /// @param buf      - A pointer to a buffer to be filled in.  Must be non-NULL
+  /// @param Buf      - A pointer to a buffer to be filled in.  Must be non-NULL
   ///                   and large enough to hold size bytes.
-  /// @result         - 0 if successful; -1 if not.  Failure may be due to a
-  ///                   bounds violation or an implementation-specific error.
-  virtual int readBytes(uint64_t address, uint64_t size, uint8_t *buf) const;
+  /// @param Size     - The number of bytes to copy.
+  /// @param Address  - The address of the first byte, in the same space as
+  ///                   getBase().
+  /// @result         - The number of bytes read.
+  virtual uint64_t readBytes(uint8_t *Buf, uint64_t Size,
+                             uint64_t Address) const = 0;
+
+  /// Ensures that the requested data is in memory, and returns a pointer to it.
+  /// More efficient than using readBytes if the data is already in memory. May
+  /// block until (address - base + size) bytes have been read
+  /// @param address - address of the byte, in the same space as getBase()
+  /// @param size    - amount of data that must be available on return
+  /// @result        - valid pointer to the requested data
+  virtual const uint8_t *getPointer(uint64_t address, uint64_t size) const = 0;
+
+  /// Returns true if the address is within the object (i.e. between base and
+  /// base + extent - 1 inclusive). May block until (address - base) bytes have
+  /// been read
+  /// @param address - address of the byte, in the same space as getBase()
+  /// @result        - true if the address may be read with readByte()
+  virtual bool isValidAddress(uint64_t address) const = 0;
 };
 
 }