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

# Interface OOCCacheScheduler

All Known Implementing Classes:
  `OOCLRUCacheScheduler`

public interface OOCCacheScheduler

## Nested Class Summary

Nested Classes
Modifier and Type
Interface
Description
`static interface`
`OOCCacheScheduler.HandoverHandle`

## Method Summary

Modifier and Type
Method
Description
`void`
`addReference(BlockKey key)`
Notifies the cache that there is another reference to the same block key.
`void`
`forget(BlockKey key)`
Forgets a block from the cache.
`long`
`getCacheSize()`
Returns the current cache size in bytes.
`long`
`getHardLimit()`
Returns the hard cache limit in bytes.
`long`
`getPinnedBytes()`
Returns the number of pinned bytes in the cache.
`OOCCacheScheduler.HandoverHandle`
`handover(BlockKey key, InMemoryQueueCallback callback)`
`boolean`
`isWithinLimits()`
Returns if the current cache size is within its defined memory limits.
`boolean`
`isWithinSoftLimits()`
Returns if the current cache size is within its soft memory limits.
`void`
`pin(BlockEntry entry)`
Pins a BlockEntry in cache to prevent eviction.
`void`
`prioritize(BlockKey key, double priority)`
Adds the given priority to any pending request accessing the key.
`BlockKey`
`put(BlockKey key, Object data, long size)`
Places a new block in the cache.
`BlockEntry`
`putAndPin(BlockKey key, Object data, long size)`
Places a new block in the cache and returns a pinned handle.
`BlockEntry`
`putAndPinSourceBacked(BlockKey key, Object data, long size, OOCIOHandler.SourceBlockDescriptor descriptor)`
Places a new source-backed block in the cache and returns a pinned handle.
`void`
`putSourceBacked(BlockKey key, Object data, long size, OOCIOHandler.SourceBlockDescriptor descriptor)`
Places a new source-backed block in the cache and registers the location with the IO handler.
`CompletableFuture<List<BlockEntry>>`
`request(List<BlockKey> keys)`
Requests a list of blocks from the cache that must be available at the same time.
`CompletableFuture<BlockEntry>`
`request(BlockKey key)`
Requests a single block from the cache.
`CompletableFuture<List<BlockEntry>>`
`requestAnyOf(List<BlockKey> keys, int n, List<BlockKey> selectionOut)`
Requests any n entries of the list of blocks, preferring an available item.
`void`
`shutdown()`
Shuts down the cache scheduler.
`Collection<BlockEntry>`
`snapshot()`
Creates a snapshot of the cache.
`List<BlockEntry>`
`tryRequest(List<BlockKey> keys)`
Tries to request a list of blocks from the cache that must be available at the same time.
`default BlockEntry`
`tryRequest(BlockKey key)`
Tries to request a single block from the cache.
`List<BlockEntry>`
`tryRequestAnyOf(List<BlockKey> keys, int n, List<BlockKey> selectionOut)`
Requests any n entries of the list of blocks, preferring an available item.
`void`
`unpin(BlockEntry entry)`
Unpins a pinned block.
`void`
`updateLimits(long evictionLimit, long hardLimit)`
Updates the cache limits.

## Method Details

### request

CompletableFuture<BlockEntry> request(BlockKey key)
Requests a single block from the cache.

Parameters:
  `key` - the requested key associated to the block
Returns:
  the available BlockEntry

### tryRequest

default BlockEntry tryRequest(BlockKey key)
Tries to request a single block from the cache. Immediately returns the entry if present, otherwise null without scheduling reads.

Parameters:
  `key` - the requested key associated to the block
Returns:
  the available BlockEntry or null

### request

CompletableFuture<List<BlockEntry>> request(List<BlockKey> keys)
Requests a list of blocks from the cache that must be available at the same time.

Parameters:
  `keys` - the requested keys associated to the block
Returns:
  the list of available BlockEntries

### tryRequest

List<BlockEntry> tryRequest(List<BlockKey> keys)
Tries to request a list of blocks from the cache that must be available at the same time. Immediately returns the list of entries if present, otherwise null without scheduling reads.

Parameters:
  `keys` - the requested keys associated to the block
Returns:
  the list of available BlockEntries

### requestAnyOf

CompletableFuture<List<BlockEntry>> requestAnyOf(List<BlockKey> keys, int n, List<BlockKey> selectionOut)
Requests any n entries of the list of blocks, preferring an available item.

### tryRequestAnyOf

List<BlockEntry> tryRequestAnyOf(List<BlockKey> keys, int n, List<BlockKey> selectionOut)
Requests any n entries of the list of blocks, preferring an available item.

### prioritize

void prioritize(BlockKey key, double priority)
Adds the given priority to any pending request accessing the key. Multi-requests are prioritized partially.

### put

BlockKey put(BlockKey key, Object data, long size)
Places a new block in the cache. Note that objects are immutable and cannot be overwritten. The object data should now only be accessed via cache, as ownership has been transferred.

Parameters:
  `key` - the associated key of the block
  `data` - the block data
  `size` - the size of the data

### putAndPin

BlockEntry putAndPin(BlockKey key, Object data, long size)
Places a new block in the cache and returns a pinned handle. Note that objects are immutable and cannot be overwritten.

Parameters:
  `key` - the associated key of the block
  `data` - the block data
  `size` - the size of the data

### handover

OOCCacheScheduler.HandoverHandle handover(BlockKey key, InMemoryQueueCallback callback)

### putSourceBacked

void putSourceBacked(BlockKey key, Object data, long size, OOCIOHandler.SourceBlockDescriptor descriptor)
Places a new source-backed block in the cache and registers the location with the IO handler. The entry is treated as backed by disk, so eviction does not schedule spill writes.

Parameters:
  `key` - the associated key of the block
  `data` - the block data
  `size` - the size of the data
  `descriptor` - the source location descriptor

### putAndPinSourceBacked

BlockEntry putAndPinSourceBacked(BlockKey key, Object data, long size, OOCIOHandler.SourceBlockDescriptor descriptor)
Places a new source-backed block in the cache and returns a pinned handle.

Parameters:
  `key` - the associated key of the block
  `data` - the block data
  `size` - the size of the data
  `descriptor` - the source location descriptor

### addReference

void addReference(BlockKey key)
Notifies the cache that there is another reference to the same block key. This will prevent forget(key) from removing the block from cache. A block will only be forgotten after all referencing instances called forget(key).

Parameters:
  `key` -

### forget

void forget(BlockKey key)
Forgets a block from the cache.

Parameters:
  `key` - the associated key of the block

### pin

void pin(BlockEntry entry)
Pins a BlockEntry in cache to prevent eviction.

Parameters:
  `entry` - the entry to be pinned

### unpin

void unpin(BlockEntry entry)
Unpins a pinned block.

Parameters:
  `entry` - the entry to be unpinned

### getCacheSize

long getCacheSize()
Returns the current cache size in bytes.

### getPinnedBytes

long getPinnedBytes()
Returns the number of pinned bytes in the cache.

### getHardLimit

long getHardLimit()
Returns the hard cache limit in bytes.

### isWithinLimits

boolean isWithinLimits()
Returns if the current cache size is within its defined memory limits.

### isWithinSoftLimits

boolean isWithinSoftLimits()
Returns if the current cache size is within its soft memory limits.

### shutdown

void shutdown()
Shuts down the cache scheduler.

### updateLimits

void updateLimits(long evictionLimit, long hardLimit)
Updates the cache limits.

### snapshot

Collection<BlockEntry> snapshot()
Creates a snapshot of the cache. Should only be used for debugging or diagnoses.