1//===- MemoryObject.h - Abstract memory interface ---------------*- C++ -*-===//
2//
3//                     The LLVM Compiler Infrastructure
4//
5// This file is distributed under the University of Illinois Open Source
6// License. See LICENSE.TXT for details.
7//
8//===----------------------------------------------------------------------===//
9
10#ifndef LLVM_SUPPORT_MEMORYOBJECT_H
11#define LLVM_SUPPORT_MEMORYOBJECT_H
12
13#include "llvm/Support/DataTypes.h"
14
15namespace llvm {
16
17/// Interface to data which might be streamed. Streamability has 2 important
18/// implications/restrictions. First, the data might not yet exist in memory
19/// when the request is made. This just means that readByte/readBytes might have
20/// to block or do some work to get it. More significantly, the exact size of
21/// the object might not be known until it has all been fetched. This means that
22/// to return the right result, getExtent must also wait for all the data to
23/// arrive; therefore it should not be called on objects which are actually
24/// streamed (this would defeat the purpose of streaming). Instead,
25/// isValidAddress can be used to test addresses without knowing the exact size
26/// of the stream. Finally, getPointer can be used instead of readBytes to avoid
27/// extra copying.
28class MemoryObject {
29public:
30  virtual ~MemoryObject();
31
32  /// Returns the size of the region in bytes.  (The region is contiguous, so
33  /// the highest valid address of the region is getExtent() - 1).
34  ///
35  /// @result         - The size of the region.
36  virtual uint64_t getExtent() const = 0;
37
38  /// Tries to read a contiguous range of bytes from the region, up to the end
39  /// of the region.
40  ///
41  /// @param Buf      - A pointer to a buffer to be filled in.  Must be non-NULL
42  ///                   and large enough to hold size bytes.
43  /// @param Size     - The number of bytes to copy.
44  /// @param Address  - The address of the first byte, in the same space as
45  ///                   getBase().
46  /// @result         - The number of bytes read.
47  virtual uint64_t readBytes(uint8_t *Buf, uint64_t Size,
48                             uint64_t Address) const = 0;
49
50  /// Ensures that the requested data is in memory, and returns a pointer to it.
51  /// More efficient than using readBytes if the data is already in memory. May
52  /// block until (address - base + size) bytes have been read
53  /// @param address - address of the byte, in the same space as getBase()
54  /// @param size    - amount of data that must be available on return
55  /// @result        - valid pointer to the requested data
56  virtual const uint8_t *getPointer(uint64_t address, uint64_t size) const = 0;
57
58  /// Returns true if the address is within the object (i.e. between base and
59  /// base + extent - 1 inclusive). May block until (address - base) bytes have
60  /// been read
61  /// @param address - address of the byte, in the same space as getBase()
62  /// @result        - true if the address may be read with readByte()
63  virtual bool isValidAddress(uint64_t address) const = 0;
64};
65
66}
67
68#endif
69