Package ghidra.trace.database.memory

# Class DBTraceMemoryManager

java.lang.Object
ghidra.trace.database.space.AbstractDBTraceSpaceBasedManager<DBTraceMemorySpace>
ghidra.trace.database.memory.DBTraceMemoryManager

All Implemented Interfaces:
  `ErrorHandler`, `DBTraceManager`, `InternalTraceMemoryOperations`, `DBTraceDelegatingManager<DBTraceMemorySpace>`, `TraceMemoryManager`, `TraceMemoryOperations`

public class DBTraceMemoryManager extends AbstractDBTraceSpaceBasedManager<DBTraceMemorySpace> implements TraceMemoryManager, InternalTraceMemoryOperations, DBTraceDelegatingManager<DBTraceMemorySpace>

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class ghidra.trace.database.space.AbstractDBTraceSpaceBasedManager

  `AbstractDBTraceSpaceBasedManager.DBTraceSpaceEntry`

  ## Nested classes/interfaces inherited from interface ghidra.trace.database.space.DBTraceDelegatingManager

  `DBTraceDelegatingManager.ExcConsumer<T,E extends Throwable>, DBTraceDelegatingManager.ExcFunction<T,R,E extends Throwable>, DBTraceDelegatingManager.ExcPredicate<T,E extends Throwable>, DBTraceDelegatingManager.ExcSupplier<T,E extends Throwable>`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected static final String`
  `NAME`
  `protected final DBTraceOverlaySpaceAdapter`
  `overlayAdapter`

  ### Fields inherited from class ghidra.trace.database.space.AbstractDBTraceSpaceBasedManager

  `baseLanguage, dbh, lock, name, NO_ADDRESS_SPACE, regSpacesByContainer, spaces, spaceStore, spacesView, threadManager, trace`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `DBTraceMemoryManager(DBHandle dbh, OpenMode openMode, ReadWriteLock lock, TaskMonitor monitor, Language baseLanguage, DBTrace trace, DBTraceThreadManager threadManager, DBTraceOverlaySpaceAdapter overlayAdapter)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TraceMemoryRegion`
  `addRegion(String path, Lifespan lifespan, AddressRange range, Collection<TraceMemoryFlag> flags)`
  Add a new region with the given properties
  `AddressSpace`
  `createOverlayAddressSpace(String name, AddressSpace base)`
  Create a new address space with the given name based upon the given space
  `protected DBTraceMemorySpace`
  `createSpace(AddressSpace space, AbstractDBTraceSpaceBasedManager.DBTraceSpaceEntry ent)`
  `void`
  `deleteOverlayAddressSpace(String name)`
  Delete an overlay address space
  `protected Collection<Map.Entry<TraceAddressSnapRange,TraceMemoryState>>`
  `doGetStates(Lifespan span, AddressRange range)`
  `Address`
  `findBytes(long snap, AddressRange range, ByteBuffer data, ByteBuffer mask, boolean forward, TaskMonitor monitor)`
  Search the given address range at the given snap for a given byte pattern
  `AddressSetView`
  `getAddressesWithState(long snap, Predicate<TraceMemoryState> predicate)`
  Get the addresses having state satisfying the given predicate
  `AddressSetView`
  `getAddressesWithState(Lifespan snap, AddressSetView set, Predicate<TraceMemoryState> predicate)`
  Get at least the subset of addresses having state satisfying the given predicate
  `AddressSetView`
  `getAddressesWithState(Lifespan lifespan, Predicate<TraceMemoryState> predicate)`
  Get the addresses having state satisfying the given predicate at any time in the specified lifespan
  `Collection<? extends TraceMemoryRegion>`
  `getAllRegions()`
  Get all the regions in this space or manager
  `int`
  `getBlockSize()`
  Get the block size used by internal storage.
  `MemBuffer`
  `getBufferAt(long snap, Address start, ByteOrder byteOrder)`
  Get a view of a particular snap as a memory buffer
  `int`
  `getBytes(long snap, Address start, ByteBuffer buf)`
  Read the most recent bytes from the given snap and address
  `DBTraceMemorySpace`
  `getForSpace(AddressSpace space, boolean createIfAbsent)`
  `TraceMemoryRegion`
  `getLiveRegionByPath(long snap, String path)`
  Get the region with the given path at the given snap
  `DBTraceMemorySpace`
  `getMemoryRegisterSpace(TraceStackFrame frame, boolean createIfAbsent)`
  Obtain a "memory" space bound to the register address space for a stack frame
  `DBTraceMemorySpace`
  `getMemoryRegisterSpace(TraceThread thread, boolean createIfAbsent)`
  Obtain a "memory" space bound to the register address space for frame 0 of a given thread
  `DBTraceMemorySpace`
  `getMemoryRegisterSpace(TraceThread thread, int frame, boolean createIfAbsent)`
  Obtain a "memory" space bound to the register address space for a given thread and stack frame
  `DBTraceMemorySpace`
  `getMemorySpace(AddressSpace space, boolean createIfAbsent)`
  Obtain a memory space bound to a particular address space
  `Map.Entry<TraceAddressSnapRange,TraceMemoryState>`
  `getMostRecentStateEntry(long snap, Address address)`
  Get the entry recording the most recent state at the given snap and address
  `Iterable<Map.Entry<TraceAddressSnapRange,TraceMemoryState>>`
  `getMostRecentStates(TraceAddressSnapRange within)`
  Break a range of addresses into smaller ranges each mapped to its most recent state at the given time
  `AddressSpace`
  `getOrCreateOverlayAddressSpace(String name, AddressSpace base)`
  Get or create an overlay address space
  `TraceMemoryRegion`
  `getRegionContaining(long snap, Address address)`
  Get the region at the given address and snap
  `AddressSetView`
  `getRegionsAddressSet(long snap)`
  Get the addresses contained by regions at the given snap
  `AddressSetView`
  `getRegionsAddressSetWith(long snap, Predicate<TraceMemoryRegion> predicate)`
  Get the addresses contained by regions at the given snap satisfying the given predicate
  `Collection<? extends TraceMemoryRegion>`
  `getRegionsAtSnap(long snap)`
  Collect regions at the given snap
  `Collection<? extends TraceMemoryRegion>`
  `getRegionsIntersecting(Lifespan lifespan, AddressRange range)`
  Collect regions intersecting the given lifespan and range
  `Long`
  `getSnapOfMostRecentChangeToBlock(long snap, Address address)`
  Find the internal storage block that most-recently defines the value at the given snap and address, and return the block's snap.
  `AddressSpace`
  `getSpace()`
  For register mapping conventions
  `TraceMemoryState`
  `getState(long snap, Address address)`
  Get the state of memory at a given snap and address
  `Collection<Map.Entry<TraceAddressSnapRange,TraceMemoryState>>`
  `getStateChanges(long from, long to)`
  Collect all the state changes between two given snaps
  `Collection<Map.Entry<TraceAddressSnapRange,TraceMemoryState>>`
  `getStates(long snap, AddressRange range)`
  Break a range of addresses into smaller ranges each mapped to its state at the given snap
  `int`
  `getViewBytes(long snap, Address start, ByteBuffer buf)`
  Read the most recent bytes from the given snap and address, following schedule forks
  `Map.Entry<TraceAddressSnapRange,TraceMemoryState>`
  `getViewMostRecentStateEntry(long snap, Address address)`
  Get the entry recording the most recent state at the given snap and address, following schedule forks
  `Map.Entry<TraceAddressSnapRange,TraceMemoryState>`
  `getViewMostRecentStateEntry(long snap, AddressRange range, Predicate<TraceMemoryState> predicate)`
  Get the entry recording the most recent state since the given snap within the given range that satisfies a given predicate, following schedule forks
  `Map.Entry<Long,TraceMemoryState>`
  `getViewState(long snap, Address address)`
  Get the state of memory at a given snap and address, following schedule forks
  `void`
  `pack()`
  Optimize storage space
  `int`
  `putBytes(long snap, Address start, ByteBuffer buf)`
  Write bytes at the given snap and address
  `Lock`
  `readLock()`
  `void`
  `removeBytes(long snap, Address start, int len)`
  Remove bytes from the given time and location
  `void`
  `setState(long snap, AddressRange range, TraceMemoryState state)`
  Set the state of memory over a given time and address range
  `void`
  `setState(long snap, Address start, Address end, TraceMemoryState state)`
  `void`
  `setState(long snap, Address address, TraceMemoryState state)`
  `void`
  `setState(long snap, AddressSetView set, TraceMemoryState state)`
  Set the state of memory over a given time and address set
  `Lock`
  `writeLock()`

  ### Methods inherited from class ghidra.trace.database.space.AbstractDBTraceSpaceBasedManager

  `dbError, get, getActiveSpaces, getBaseLanguage, getForRegisterSpace, getForRegisterSpace, getForRegisterSpace, getLock, getSpaceByName, getTabledSpaces, getTrace, invalidateCache, loadSpaces, tableName`

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface ghidra.trace.database.space.DBTraceDelegatingManager

  `checkIsInMemory, delegateAddressSet, delegateAny, delegateCollection, delegateDeleteB, delegateDeleteV, delegateFirst, delegateHashSet, delegateRead, delegateRead, delegateReadB, delegateReadI, delegateReadI, delegateReadOr, delegateWrite, delegateWriteAll, delegateWriteI, delegateWriteV`

  ### Methods inherited from interface ghidra.trace.database.memory.InternalTraceMemoryOperations

  `getBytes, getLock, getState, getStates, getValue, getViewValue, putBytes, removeValue, setState, setValue`

  ### Methods inherited from interface ghidra.trace.model.memory.TraceMemoryManager

  `addRegion, createRegion, createRegion`

  ### Methods inherited from interface ghidra.trace.model.memory.TraceMemoryOperations

  `getAddressesWithState, getBufferAt, getBytes, getMostRecentStates, getState, getStates, getTrace, getValue, getViewValue, isKnown, putBytes, removeValue, setState, setValue`

- ## Field Details

  - ### NAME

    protected static final String NAME
    See Also:
      - Constant Field Values

  - ### overlayAdapter

    protected final DBTraceOverlaySpaceAdapter overlayAdapter

- ## Constructor Details

  - ### DBTraceMemoryManager

    public DBTraceMemoryManager(DBHandle dbh, OpenMode openMode, ReadWriteLock lock, TaskMonitor monitor, Language baseLanguage, DBTrace trace, DBTraceThreadManager threadManager, DBTraceOverlaySpaceAdapter overlayAdapter) throws IOException, VersionException
    Throws:
      `IOException`
      `VersionException`

- ## Method Details

  - ### getSpace

    public AddressSpace getSpace()
    Description copied from interface: `InternalTraceMemoryOperations`
    For register mapping conventions
    Specified by:
      `getSpace` in interface `InternalTraceMemoryOperations`
    Returns:
      the address space

  - ### createOverlayAddressSpace

    public AddressSpace createOverlayAddressSpace(String name, AddressSpace base) throws DuplicateNameException
    Description copied from interface: `TraceMemoryManager`
    Create a new address space with the given name based upon the given space

    The purpose of overlay spaces in traces is often to store bytes for things other than memory or registers. Some targets may expose other byte-based storage, or provide alternative views of memory.

    NOTE: This also provides a transitional piece for recording a model (sub)tree directly into a trace, without mapping to a Ghidra language first. As we experiment with that mode, we will likely instantiate traces with the "DATA:BE:64:default" language and generate an overlay space named after the path of each memory being recorded. Of course, the mapping still needs to occur between the trace and parts of the display and during emulation.

    NOTE: We are also moving away from (space, thread, frame) triples to uniquely identify register storage. Instead, that will be encoded into the address space itself. Register overlays will overlay register space and be named after the register container object, which subsumes thread and frame when applicable.

    Specified by:
      `createOverlayAddressSpace` in interface `TraceMemoryManager`
    Parameters:
      `name` - the name of the new address space
      `base` - the space after which this is modeled
    Returns:
      the create space
    Throws:
      `DuplicateNameException` - if an address space with the name already exists

  - ### getOrCreateOverlayAddressSpace

    public AddressSpace getOrCreateOverlayAddressSpace(String name, AddressSpace base)
    Description copied from interface: `TraceMemoryManager`
    Get or create an overlay address space

    If the space already exists, and it overlays the given base, the existing space is returned. If it overlays a different space, null is returned. If the space does not exist, it is created with the given base space.

    Specified by:
      `getOrCreateOverlayAddressSpace` in interface `TraceMemoryManager`
    Parameters:
      `name` - the name of the address space
      `base` - the expected base space
    Returns:
      the space, or null
    See Also:
      - `TraceMemoryManager.createOverlayAddressSpace(String, AddressSpace)`

  - ### deleteOverlayAddressSpace

    public void deleteOverlayAddressSpace(String name)
    Description copied from interface: `TraceMemoryManager`
    Delete an overlay address space

    TODO: At the moment, this will not destroy manager spaces created for the deleted address space. We should assess this behavior, esp. wrt. re-creating the address space later, and decide whether or not to clean up.

    Specified by:
      `deleteOverlayAddressSpace` in interface `TraceMemoryManager`
    Parameters:
      `name` - the name of the address space to delete

  - ### createSpace

    protected DBTraceMemorySpace createSpace(AddressSpace space, AbstractDBTraceSpaceBasedManager.DBTraceSpaceEntry ent) throws VersionException, IOException
    Specified by:
      `createSpace` in class `AbstractDBTraceSpaceBasedManager<DBTraceMemorySpace>`
    Throws:
      `VersionException`
      `IOException`

  - ### getForSpace

    public DBTraceMemorySpace getForSpace(AddressSpace space, boolean createIfAbsent)
    Specified by:
      `getForSpace` in interface `DBTraceDelegatingManager<DBTraceMemorySpace>`
    Overrides:
      `getForSpace` in class `AbstractDBTraceSpaceBasedManager<DBTraceMemorySpace>`

  - ### readLock

    public Lock readLock()
    Specified by:
      `readLock` in interface `DBTraceDelegatingManager<DBTraceMemorySpace>`

  - ### writeLock

    public Lock writeLock()
    Specified by:
      `writeLock` in interface `DBTraceDelegatingManager<DBTraceMemorySpace>`

  - ### getMemorySpace

    public DBTraceMemorySpace getMemorySpace(AddressSpace space, boolean createIfAbsent)
    Description copied from interface: `TraceMemoryManager`
    Obtain a memory space bound to a particular address space
    Specified by:
      `getMemorySpace` in interface `TraceMemoryManager`
    Parameters:
      `space` - the address space
      `createIfAbsent` - true to create the space if it's not already present
    Returns:
      the space, or `null` if absent and not created

  - ### getMemoryRegisterSpace

    public DBTraceMemorySpace getMemoryRegisterSpace(TraceThread thread, boolean createIfAbsent)
    Description copied from interface: `TraceMemoryManager`
    Obtain a "memory" space bound to the register address space for frame 0 of a given thread
    Specified by:
      `getMemoryRegisterSpace` in interface `TraceMemoryManager`
    Parameters:
      `thread` - the given thread
      `createIfAbsent` - true to create the space if it's not already present
    Returns:
      the space, or `null` if absent and not created
    See Also:
      - `TraceMemoryManager.getMemoryRegisterSpace(TraceThread, int, boolean)`

  - ### getMemoryRegisterSpace

    public DBTraceMemorySpace getMemoryRegisterSpace(TraceThread thread, int frame, boolean createIfAbsent)
    Description copied from interface: `TraceMemoryManager`
    Obtain a "memory" space bound to the register address space for a given thread and stack frame
    Specified by:
      `getMemoryRegisterSpace` in interface `TraceMemoryManager`
    Parameters:
      `thread` - the given thread
      `frame` - the "level" of the given stack frame. 0 is the innermost frame.
      `createIfAbsent` - true to create the space if it's not already present
    Returns:
      the space, or `null` if absent and not created

  - ### getMemoryRegisterSpace

    public DBTraceMemorySpace getMemoryRegisterSpace(TraceStackFrame frame, boolean createIfAbsent)
    Description copied from interface: `TraceMemoryManager`
    Obtain a "memory" space bound to the register address space for a stack frame

    Note this is simply a convenience, and does not in any way bind the space to the lifespan of the given frame. Nor, if the frame is moved, will this space move with it.

    Specified by:
      `getMemoryRegisterSpace` in interface `TraceMemoryManager`
    Parameters:
      `frame` - the stack frame
      `createIfAbsent` - true to create the space if it's not already present
    Returns:
      the space, or `null` if absent and not created
    See Also:
      - `TraceMemoryManager.getMemoryRegisterSpace(TraceThread, int, boolean)`

  - ### addRegion

    public TraceMemoryRegion addRegion(String path, Lifespan lifespan, AddressRange range, Collection<TraceMemoryFlag> flags) throws TraceOverlappedRegionException
    Description copied from interface: `TraceMemoryManager`
    Add a new region with the given properties

    Regions model the memory mappings of a debugging target. As such, they are never allowed to overlap. Additionally, to ensure `TraceMemoryManager.getLiveRegionByPath(long, String)` returns a unique region, duplicate paths cannot exist in the same snap.

    Regions have a "full name" (path) as well as a short name. The path is immutable and can be used to reliably retrieve the same region later. The short name should be something suitable for display on the screen. Short names are mutable and can be -- but probbaly shouldn't be -- duplicated.

    Specified by:
      `addRegion` in interface `TraceMemoryManager`
    Parameters:
      `path` - the "full name" of the region
      `lifespan` - the lifespan of the region
      `range` - the address range of the region
      `flags` - the flags, e.g., permissions, of the region
    Returns:
      the newly-added region
    Throws:
      `TraceOverlappedRegionException` - if the specified region would overlap an existing one

  - ### getAllRegions

    public Collection<? extends TraceMemoryRegion> getAllRegions()
    Description copied from interface: `TraceMemoryManager`
    Get all the regions in this space or manager
    Specified by:
      `getAllRegions` in interface `TraceMemoryManager`
    Returns:
      the collection of all regions

  - ### getLiveRegionByPath

    public TraceMemoryRegion getLiveRegionByPath(long snap, String path)
    Description copied from interface: `TraceMemoryManager`
    Get the region with the given path at the given snap
    Specified by:
      `getLiveRegionByPath` in interface `TraceMemoryManager`
    Parameters:
      `snap` - the snap which must be within the region's lifespan
      `path` - the "full name" of the region
    Returns:
      the region, or `null` if no region matches

  - ### getRegionContaining

    public TraceMemoryRegion getRegionContaining(long snap, Address address)
    Description copied from interface: `TraceMemoryManager`
    Get the region at the given address and snap
    Specified by:
      `getRegionContaining` in interface `TraceMemoryManager`
    Parameters:
      `snap` - the snap which must be within the region's lifespan
      `address` - the address which must be within the region's range
    Returns:
      the region, or `null` if no region matches

  - ### getRegionsIntersecting

    public Collection<? extends TraceMemoryRegion> getRegionsIntersecting(Lifespan lifespan, AddressRange range)
    Description copied from interface: `TraceMemoryManager`
    Collect regions intersecting the given lifespan and range
    Specified by:
      `getRegionsIntersecting` in interface `TraceMemoryManager`
    Parameters:
      `lifespan` - the lifespan
      `range` - the range
    Returns:
      the collection of matching regions

  - ### getRegionsAtSnap

    public Collection<? extends TraceMemoryRegion> getRegionsAtSnap(long snap)
    Description copied from interface: `TraceMemoryManager`
    Collect regions at the given snap
    Specified by:
      `getRegionsAtSnap` in interface `TraceMemoryManager`
    Parameters:
      `snap` - the snap which must be within the regions' lifespans
    Returns:
      the collection of matching regions

  - ### getRegionsAddressSet

    public AddressSetView getRegionsAddressSet(long snap)
    Description copied from interface: `TraceMemoryManager`
    Get the addresses contained by regions at the given snap

    The implementation may provide a view that updates with changes.

    Specified by:
      `getRegionsAddressSet` in interface `TraceMemoryManager`
    Parameters:
      `snap` - the snap which must be within the regions' lifespans
    Returns:
      the union of ranges of matching regions

  - ### getRegionsAddressSetWith

    public AddressSetView getRegionsAddressSetWith(long snap, Predicate<TraceMemoryRegion> predicate)
    Description copied from interface: `TraceMemoryManager`
    Get the addresses contained by regions at the given snap satisfying the given predicate

    The implementation may provide a view that updates with changes.

    Specified by:
      `getRegionsAddressSetWith` in interface `TraceMemoryManager`
    Parameters:
      `snap` - the snap which must be within the region's lifespans
      `predicate` - a predicate on regions to search for
    Returns:
      the address set

  - ### setState

    public void setState(long snap, Address address, TraceMemoryState state)
    Specified by:
      `setState` in interface `TraceMemoryOperations`
    See Also:
      - `TraceMemoryOperations.setState(long, AddressRange, TraceMemoryState)`

  - ### setState

    public void setState(long snap, Address start, Address end, TraceMemoryState state)
    Specified by:
      `setState` in interface `TraceMemoryOperations`
    See Also:
      - `TraceMemoryOperations.setState(long, AddressRange, TraceMemoryState)`

  - ### setState

    public void setState(long snap, AddressRange range, TraceMemoryState state)
    Description copied from interface: `TraceMemoryOperations`
    Set the state of memory over a given time and address range

    Setting state to `TraceMemoryState.KNOWN` via this method is not recommended. Setting bytes will automatically update the state accordingly.

    Specified by:
      `setState` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `range` - the range
      `state` - the state

  - ### setState

    public void setState(long snap, AddressSetView set, TraceMemoryState state)
    Description copied from interface: `TraceMemoryOperations`
    Set the state of memory over a given time and address set
    Specified by:
      `setState` in interface `TraceMemoryOperations`
    See Also:
      - `TraceMemoryOperations.setState(long, AddressRange, TraceMemoryState)`

  - ### getState

    public TraceMemoryState getState(long snap, Address address)
    Description copied from interface: `TraceMemoryOperations`
    Get the state of memory at a given snap and address

    If the location's state has not been set, the result is `null`, which implies `TraceMemoryState.UNKNOWN`.

    Specified by:
      `getState` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `address` - the location
    Returns:
      the state

  - ### getViewState

    public Map.Entry<Long,TraceMemoryState> getViewState(long snap, Address address)
    Description copied from interface: `TraceMemoryOperations`
    Get the state of memory at a given snap and address, following schedule forks
    Specified by:
      `getViewState` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `address` - the location
    Returns:
      the state, and the snap where it was found

  - ### getMostRecentStateEntry

    public Map.Entry<TraceAddressSnapRange,TraceMemoryState> getMostRecentStateEntry(long snap, Address address)
    Description copied from interface: `TraceMemoryOperations`
    Get the entry recording the most recent state at the given snap and address

    The entry includes the entire entry at that snap. Parts occluded by more recent snaps are not subtracted from the entry's address range.

    Specified by:
      `getMostRecentStateEntry` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `address` - the location
    Returns:
      the entry including the entire recorded range

  - ### getViewMostRecentStateEntry

    public Map.Entry<TraceAddressSnapRange,TraceMemoryState> getViewMostRecentStateEntry(long snap, AddressRange range, Predicate<TraceMemoryState> predicate)
    Description copied from interface: `TraceMemoryOperations`
    Get the entry recording the most recent state since the given snap within the given range that satisfies a given predicate, following schedule forks
    Specified by:
      `getViewMostRecentStateEntry` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the latest time to consider
      `range` - the range of addresses
      `predicate` - a predicate on the state
    Returns:
      the most-recent entry

  - ### getViewMostRecentStateEntry

    public Map.Entry<TraceAddressSnapRange,TraceMemoryState> getViewMostRecentStateEntry(long snap, Address address)
    Description copied from interface: `TraceMemoryOperations`
    Get the entry recording the most recent state at the given snap and address, following schedule forks
    Specified by:
      `getViewMostRecentStateEntry` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the latest time to consider
      `address` - the address
    Returns:
      the most-recent entry

  - ### getAddressesWithState

    public AddressSetView getAddressesWithState(Lifespan snap, AddressSetView set, Predicate<TraceMemoryState> predicate)
    Description copied from interface: `TraceMemoryOperations`
    Get at least the subset of addresses having state satisfying the given predicate

    The implementation may provide a larger view than requested, but within the requested set, only ranges satisfying the predicate may be present. Use `AddressSetView.intersect(AddressSetView)` with `set` if a strict subset is required.

    Because `TraceMemoryState.UNKNOWN` is not explicitly stored in the map, to compute the set of `TraceMemoryState.UNKNOWN` addresses, use the predicate `state -> state != null && state != TraceMemoryState.UNKNOWN` and subtract the result from `set`.

    Specified by:
      `getAddressesWithState` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the range of time
      `set` - the set to examine
      `predicate` - a predicate on state to search for
    Returns:
      the address set

  - ### getAddressesWithState

    public AddressSetView getAddressesWithState(long snap, Predicate<TraceMemoryState> predicate)
    Description copied from interface: `TraceMemoryOperations`
    Get the addresses having state satisfying the given predicate

    The implementation may provide a view that updates with changes. Behavior is not well defined for predicates testing for `TraceMemoryState.UNKNOWN`.

    Specified by:
      `getAddressesWithState` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `predicate` - a predicate on state to search for
    Returns:
      the address set

  - ### getAddressesWithState

    public AddressSetView getAddressesWithState(Lifespan lifespan, Predicate<TraceMemoryState> predicate)
    Description copied from interface: `TraceMemoryOperations`
    Get the addresses having state satisfying the given predicate at any time in the specified lifespan

    The implementation may provide a view that updates with changes. Behavior is not well defined for predicates testing for `TraceMemoryState.UNKNOWN` .

    Specified by:
      `getAddressesWithState` in interface `TraceMemoryOperations`
    Parameters:
      `lifespan` - the span of time
      `predicate` - a predicate on state to search for
    Returns:
      the address set

  - ### doGetStates

    protected Collection<Map.Entry<TraceAddressSnapRange,TraceMemoryState>> doGetStates(Lifespan span, AddressRange range)

  - ### getStates

    public Collection<Map.Entry<TraceAddressSnapRange,TraceMemoryState>> getStates(long snap, AddressRange range)
    Description copied from interface: `TraceMemoryOperations`
    Break a range of addresses into smaller ranges each mapped to its state at the given snap

    Note that `TraceMemoryState.UNKNOWN` entries will not appear in the result. Gaps in the returned entries are implied to be `TraceMemoryState.UNKNOWN`.

    Specified by:
      `getStates` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `range` - the range to examine
    Returns:
      the map of ranges to states

  - ### getMostRecentStates

    public Iterable<Map.Entry<TraceAddressSnapRange,TraceMemoryState>> getMostRecentStates(TraceAddressSnapRange within)
    Description copied from interface: `TraceMemoryOperations`
    Break a range of addresses into smaller ranges each mapped to its most recent state at the given time

    Typically `within` is the box whose width is the address range to break down and whose height is from "negative infinity" to the "current" snap.

    In this context, "most recent" means the latest state other than `TraceMemoryState.UNKNOWN`.

    Specified by:
      `getMostRecentStates` in interface `TraceMemoryOperations`
    Parameters:
      `within` - a box intersecting entries to consider
    Returns:
      an iterable over the snap ranges and states

  - ### putBytes

    public int putBytes(long snap, Address start, ByteBuffer buf)
    Description copied from interface: `TraceMemoryOperations`
    Write bytes at the given snap and address

    This will attempt to read `Buffer.remaining()` bytes starting at `Buffer.position()` from the source buffer `buf` and write them into memory at the specified time and location. The affected region is also updated to `TraceMemoryState.KNOWN`. The written bytes are assumed effective for all future snaps up to the next write.

    Specified by:
      `putBytes` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `start` - the location
      `buf` - the source buffer of bytes
    Returns:
      the number of bytes written

  - ### getBytes

    public int getBytes(long snap, Address start, ByteBuffer buf)
    Description copied from interface: `TraceMemoryOperations`
    Read the most recent bytes from the given snap and address

    This will attempt to read `Buffer.remaining()` of the most recent bytes from memory at the specified time and location and write them into the destination buffer `buf` starting at `Buffer.position()`. Where bytes in memory have no defined value, values in the destination buffer are unspecified. The implementation may leave those bytes in the destination buffer unmodified, or it may write zeroes.

    Specified by:
      `getBytes` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `start` - the location
      `buf` - the destination buffer of bytes
    Returns:
      the number of bytes read

  - ### getViewBytes

    public int getViewBytes(long snap, Address start, ByteBuffer buf)
    Description copied from interface: `TraceMemoryOperations`
    Read the most recent bytes from the given snap and address, following schedule forks

    This behaves similarly to `TraceMemoryOperations.getBytes(long, Address, ByteBuffer)`, except it checks for the `TraceMemoryState.KNOWN` state among each involved snap range and reads the applicable address ranges, preferring the most recent. Where memory is never known the buffer is left unmodified.

    Specified by:
      `getViewBytes` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `start` - the location
      `buf` - the destination buffer of bytes
    Returns:
      the number of bytes read

  - ### removeBytes

    public void removeBytes(long snap, Address start, int len)
    Description copied from interface: `TraceMemoryOperations`
    Remove bytes from the given time and location

    This deletes all observed bytes from the given address through length at the given snap. If there were no observations in the range at exactly the given snap, this has no effect. If there were, then those observations are removed. The next time those bytes are read, they will have a value from a previous snap, or no value at all. The affected region's state is also deleted, i.e., set to `null`, implying `TraceMemoryState.UNKNOWN`.

    Note, use of this method is discouraged. The more observations within the same range that follow the deleted observation, the more expensive this operation typically is, since all of those observations may need to be updated.

    Specified by:
      `removeBytes` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `start` - the location
      `len` - the number of bytes to remove

  - ### findBytes

    public Address findBytes(long snap, AddressRange range, ByteBuffer data, ByteBuffer mask, boolean forward, TaskMonitor monitor)
    Description copied from interface: `TraceMemoryOperations`
    Search the given address range at the given snap for a given byte pattern
    Specified by:
      `findBytes` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time to search
      `range` - the address range to search
      `data` - the values to search for
      `mask` - a mask on the bits of `data`; or null to match all bytes exactly
      `forward` - true to return the match with the lowest address in `range`, false for the highest address.
      `monitor` - a monitor for progress reporting and canceling
    Returns:
      the minimum address of the matched bytes, or `null` if not found

  - ### getBufferAt

    public MemBuffer getBufferAt(long snap, Address start, ByteOrder byteOrder)
    Description copied from interface: `TraceMemoryOperations`
    Get a view of a particular snap as a memory buffer

    The bytes read by this buffer are the most recent bytes written before the given snap

    Specified by:
      `getBufferAt` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the snap
      `start` - the starting address
      `byteOrder` - the byte ordering for this buffer
    Returns:
      the memory buffer

  - ### getSnapOfMostRecentChangeToBlock

    public Long getSnapOfMostRecentChangeToBlock(long snap, Address address)
    Description copied from interface: `TraceMemoryOperations`
    Find the internal storage block that most-recently defines the value at the given snap and address, and return the block's snap.

    This method reveals portions of the internal storage so that clients can optimize difference computations by eliminating corresponding ranges defined by the same block. If the underlying implementation cannot answer this question, this returns the given snap.

    Specified by:
      `getSnapOfMostRecentChangeToBlock` in interface `TraceMemoryOperations`
    Parameters:
      `snap` - the time
      `address` - the location
    Returns:
      the most snap for the most recent containing block

  - ### getBlockSize

    public int getBlockSize()
    Description copied from interface: `TraceMemoryOperations`
    Get the block size used by internal storage.

    This method reveals portions of the internal storage so that clients can optimize searches. If the underlying implementation cannot answer this question, this returns 0.

    Specified by:
      `getBlockSize` in interface `TraceMemoryOperations`
    Returns:
      the block size

  - ### pack

    public void pack()
    Description copied from interface: `TraceMemoryOperations`
    Optimize storage space

    This gives the implementation an opportunity to clean up garbage, apply compression, etc., in order to best use the storage space. Because memory observations can be sparse, a trace's memory is often compressible, and observations are not often modified or deleted, packing is recommended whenever the trace is saved to disk.

    Specified by:
      `pack` in interface `TraceMemoryOperations`

  - ### getStateChanges

    public Collection<Map.Entry<TraceAddressSnapRange,TraceMemoryState>> getStateChanges(long from, long to)
    Description copied from interface: `TraceMemoryManager`
    Collect all the state changes between two given snaps
    Specified by:
      `getStateChanges` in interface `TraceMemoryManager`
    Parameters:
      `from` - the earlier snap
      `to` - the later snap
    Returns:
      the collection of state changes