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

# Class OOCCacheImpl

java.lang.Object
org.apache.sysds.runtime.ooc.cache.OOCCacheImpl

All Implemented Interfaces:
  `OOCCache`

public class OOCCacheImpl extends Object implements OOCCache

## Nested Class Summary

## Nested classes/interfaces inherited from interface org.apache.sysds.runtime.ooc.cache.OOCCache

`OOCCache.UnpinHandle`

## Constructor Summary

Constructors
Constructor
Description
`OOCCacheImpl(OOCIOHandler ioHandler, long hardLimit, long evictionLimit)`

## 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.
`OOCFuture<BlockEntry>`
`pinAdmitted(long sId, long tId, 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.
`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)`

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

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

### Methods inherited from interface org.apache.sysds.runtime.ooc.cache.OOCCache

`pin, pinAdmitted, putPinned`

## Constructor Details

### OOCCacheImpl

public OOCCacheImpl(OOCIOHandler ioHandler, long hardLimit, long evictionLimit)

## Method Details

### putPinned

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

Specified by:
  `putPinned` in interface `OOCCache`

### pin

public OOCFuture<BlockEntry> pin(long sId, long tId, MemoryAllowance allowance)
Description copied from interface: `OOCCache`
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.

Specified by:
  `pin` in interface `OOCCache`
Returns:
  a non-null future of the pinned block entry; the future result is null if the required memory could not be reserved

### pinAdmitted

public OOCFuture<BlockEntry> pinAdmitted(long sId, long tId, MemoryAllowance allowance)
Description copied from interface: `OOCCache`
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.

Specified by:
  `pinAdmitted` in interface `OOCCache`
Returns:
  a non-null future of the pinned block entry

### pinIfLive

public BlockEntry pinIfLive(long sId, long tId, MemoryAllowance allowance)
Description copied from interface: `OOCCache`
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.

Specified by:
  `pinIfLive` in interface `OOCCache`
Returns:
  the pinned block entry if available. Null if the required memory could not be reserved or the block is not live

### unpin

public OOCCache.UnpinHandle unpin(BlockEntry entry, MemoryAllowance allowance)
Description copied from interface: `OOCCache`
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.

Specified by:
  `unpin` in interface `OOCCache`
Returns:
  a handle describing the ownership transfer from allowance-owned memory back to cache-owned memory

### reference

public int reference(BlockEntry entry)
Description copied from interface: `OOCCache`
Referencing a pinned entry guarantees that its key remains in the cache until dereferenced.

Specified by:
  `reference` in interface `OOCCache`
Returns:

### dereference

public int dereference(BlockEntry entry)
Description copied from interface: `OOCCache`
Dereferencing allows an entry to be forgotten if no further reference is held. Dereferencing may not immediately cause entry removal if still pinned.

Specified by:
  `dereference` in interface `OOCCache`
Returns:

### dereference

public int dereference(BlockKey key)
Description copied from interface: `OOCCache`
Dereferencing allows an entry to be forgotten if no further reference is held. Dereferencing may not immediately cause entry removal if still pinned.

Specified by:
  `dereference` in interface `OOCCache`

### updateLimits

public void updateLimits(long hardLimit, long evictionLimit)

Specified by:
  `updateLimits` in interface `OOCCache`

### addEvictionPolicy

public void addEvictionPolicy(long streamId, LongUnaryOperator scoreFn)
Description copied from interface: `OOCCache`
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".

Specified by:
  `addEvictionPolicy` in interface `OOCCache`

### getOwnedCacheSize

public long getOwnedCacheSize()
Description copied from interface: `OOCCache`
Returns the current cache-owned size in bytes.

Specified by:
  `getOwnedCacheSize` in interface `OOCCache`

### shutdown

public void shutdown()

Specified by:
  `shutdown` in interface `OOCCache`