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

# Interface OOCCache

All Known Implementing Classes:
  `OOCCacheImpl`, `OOCPackedCache`

public interface OOCCache

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static interface`
`OOCCache.UnpinHandle`

## Method Summary

Modifier and Type
Method
Description
`void`
`addEvictionPolicy(long streamId, LongUnaryOperator scoreFn)`
Adds an eviction scoring policy for one logical cache stream.
`int`
`dereference(BlockEntry entry)`
Dereferencing allows an entry to be forgotten if no further reference is held.
`int`
`dereference(BlockKey key)`
Dereferencing allows an entry to be forgotten if no further reference is held.
`long`
`getOwnedCacheSize()`
Returns the current cache-owned size in bytes.
`OOCFuture<BlockEntry>`
`pin(long sId, long tId, MemoryAllowance allowance)`
Pins an item backed by an allowance.
`default OOCFuture<BlockEntry>`
`pin(BlockKey key, MemoryAllowance allowance)`
Pins an item backed by an allowance.
`OOCFuture<BlockEntry>`
`pinAdmitted(long sId, long tId, MemoryAllowance allowance)`
Pins an item backed by an allowance.
`default OOCFuture<BlockEntry>`
`pinAdmitted(BlockKey key, MemoryAllowance allowance)`
Pins an item backed by an allowance.
`BlockEntry`
`pinIfLive(long sId, long tId, MemoryAllowance allowance)`
Pins an item backed by an allowance if it is already live in cache.
`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.
`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.
`int`
`reference(BlockEntry entry)`
Referencing a pinned entry guarantees that its key remains in the cache until dereferenced.
`void`
`shutdown()`
`OOCCache.UnpinHandle`
`unpin(BlockEntry entry, MemoryAllowance allowance)`
Unpins an item that is still backed by the given allowance.
`void`
`updateLimits(long hardLimit, long evictionLimit)`

## 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()