Package org.apache.sysds.runtime.ooc.cache

Interface OOCCache

All Known Implementing Classes:
OOCCacheImpl, OOCPackedCache
public interface OOCCache

  • Method Details

    • pin

      default OOCFuture<BlockEntry> pin(BlockKey key, MemoryAllowance allowance)
      Pins an item backed by an allowance. A successful pin transfers memory ownership from the cache to the owner of the allowance and guarantees data availability. While pinned, the bytes of the entry are not counted as cache-owned memory.
      Parameters:
      key -
      allowance -
      Returns:
      a non-null future of the pinned block entry; the future result is null if the required memory could not be reserved

    • pinAdmitted

      default OOCFuture<BlockEntry> pinAdmitted(BlockKey key, MemoryAllowance allowance)
      Pins an item backed by an allowance. If the allowance cannot reserve enough memory, this method will wait until memory is available. A successful pin transfers memory ownership from the cache to the owner of the allowance and guarantees data availability. While pinned, the bytes of the entry are not counted as cache-owned memory.
      Parameters:
      key -
      allowance -
      Returns:
      a non-null future of the pinned block entry

    • putPinned

      default BlockEntry putPinned(BlockKey key, Object data, long size, MemoryAllowance allowance)
      Adds a new pinned entry whose bytes are already owned by the given allowance. Ownership can later move only via pin/unpin.

    • putPinned

      BlockEntry putPinned(long sId, long tId, Object data, long size, MemoryAllowance allowance)
      Adds a new pinned entry whose bytes are already owned by the given allowance. Ownership can later move only via pin/unpin.

    • pin

      OOCFuture<BlockEntry> pin(long sId, long tId, MemoryAllowance allowance)
      Pins an item backed by an allowance. A successful pin transfers memory ownership from the cache to the owner of the allowance and guarantees data availability. While pinned, the bytes of the entry are not counted as cache-owned memory.
      Parameters:
      sId -
      tId -
      allowance -
      Returns:
      a non-null future of the pinned block entry; the future result is null if the required memory could not be reserved

    • pinAdmitted

      OOCFuture<BlockEntry> pinAdmitted(long sId, long tId, MemoryAllowance allowance)
      Pins an item backed by an allowance. If the allowance cannot reserve enough memory, this method will wait until memory is available. A successful pin transfers memory ownership from the cache to the owner of the allowance and guarantees data availability. While pinned, the bytes of the entry are not counted as cache-owned memory.
      Parameters:
      sId -
      tId -
      allowance -
      Returns:
      a non-null future of the pinned block entry

    • pinIfLive

      BlockEntry pinIfLive(long sId, long tId, MemoryAllowance allowance)
      Pins an item backed by an allowance if it is already live in cache. A successful pin transfers memory ownership from the cache to the owner of the allowance and guarantees data availability. While pinned, the bytes of the entry are not counted as cache-owned memory. Implementations must reserve the required bytes from the allowance before making data available.
      Parameters:
      sId -
      tId -
      allowance -
      Returns:
      the pinned block entry if available. Null if the required memory could not be reserved or the block is not live

    • unpin

      OOCCache.UnpinHandle unpin(BlockEntry entry, MemoryAllowance allowance)
      Unpins an item that is still backed by the given allowance. Unpinning tries to transfer memory ownership back to the cache. An ownership transfer may commit immediately only if this does not cause the cache to exceed its hard limit. Otherwise, the transfer is deferred and the allowance remains charged until the returned handle commits, is reclaimed, or is superseded by a later pin that transfers ownership to another allowance. Unpin can be viewed as an eventually resolving operation.
      Parameters:
      entry -
      allowance -
      Returns:
      a handle describing the ownership transfer from allowance-owned memory back to cache-owned memory

    • reference

      int reference(BlockEntry entry)
      Referencing a pinned entry guarantees that its key remains in the cache until dereferenced.
      Parameters:
      entry -
      Returns:

    • dereference

      int dereference(BlockEntry entry)
      Dereferencing allows an entry to be forgotten if no further reference is held. Dereferencing may not immediately cause entry removal if still pinned.
      Parameters:
      entry -
      Returns:

    • dereference

      int dereference(BlockKey key)
      Dereferencing allows an entry to be forgotten if no further reference is held. Dereferencing may not immediately cause entry removal if still pinned.

    • updateLimits

      void updateLimits(long hardLimit, long evictionLimit)

    • addEvictionPolicy

      void addEvictionPolicy(long streamId, LongUnaryOperator scoreFn)
      Adds an eviction scoring policy for one logical cache stream. Larger scores are selected for eviction first. Long.MAX_VALUE remains reserved as "no policy score".

    • getOwnedCacheSize

      long getOwnedCacheSize()
      Returns the current cache-owned size in bytes.

    • shutdown

      void shutdown()