one.microstream.storage.types

Interface StorageEntityCacheEvaluator

All Known Implementing Classes:

StorageEntityCacheEvaluator.Default

Functional Interface:

This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.

@FunctionalInterface
public interface StorageEntityCacheEvaluator

Function type that evaluates if a live entity (entity with cached data) shall be unloaded (its cache cleared).

Note that any implementation of this type must be safe enough to never throw an exception as this would doom the storage thread that executes it. Catching any exception would not prevent the problem for the channel thread as the function has to work in order for the channel to work properly. It is therefore strongly suggested that implementations only use "exception free" logic (like simple arithmetic) or handle any possible exception internally.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	StorageEntityCacheEvaluator.Default
static interface	StorageEntityCacheEvaluator.Defaults
static interface	StorageEntityCacheEvaluator.Validation

Method Summary

Modifier and Type	Method and Description
boolean	clearEntityCache(long totalCacheSize, long evaluationTime, StorageEntity entity)
default boolean	initiallyCacheEntity(long totalCacheSize, long evaluationTime, StorageEntity entity)
static StorageEntityCacheEvaluator	New() Pseudo-constructor method to create a new StorageEntityCacheEvaluator instance using default values defined by StorageEntityCacheEvaluator.Defaults.
static StorageEntityCacheEvaluator	New(long timeoutMs) Pseudo-constructor method to create a new StorageEntityCacheEvaluator instance using the passed value and default values defined by StorageEntityCacheEvaluator.Defaults.
static StorageEntityCacheEvaluator	New(long timeoutMs, long threshold) Pseudo-constructor method to create a new StorageEntityCacheEvaluator instance using the passed values.

Method Detail

clearEntityCache

boolean clearEntityCache(long totalCacheSize,
                         long evaluationTime,
                         StorageEntity entity)

initiallyCacheEntity

default boolean initiallyCacheEntity(long totalCacheSize,
                                     long evaluationTime,
                                     StorageEntity entity)

New

static StorageEntityCacheEvaluator New()

Pseudo-constructor method to create a new StorageEntityCacheEvaluator instance using default values defined by StorageEntityCacheEvaluator.Defaults.

For explanations and customizing values, see New(long, long).

Returns:

a new StorageEntityCacheEvaluator instance.

See Also:

New(long), New(long, long), StorageEntityCacheEvaluator.Defaults

New

static StorageEntityCacheEvaluator New(long timeoutMs)

Pseudo-constructor method to create a new StorageEntityCacheEvaluator instance using the passed value and default values defined by StorageEntityCacheEvaluator.Defaults.

For explanations and customizing values, see New(long, long).

Parameters:

timeoutMs - the time (in milliseconds, greater than 0) of not being read (the "age"), after which a particular entity's data will be cleared from the Storage's internal cache.

Returns:

a new StorageEntityCacheEvaluator instance.

Throws:

one.microstream.exceptions.NumberRangeException - if the passed value is equal to or lower than 0.

See Also:

New(), New(long, long), StorageEntityCacheEvaluator.Defaults

New

static StorageEntityCacheEvaluator New(long timeoutMs,
                                       long threshold)

Pseudo-constructor method to create a new StorageEntityCacheEvaluator instance using the passed values.

In the default implementation, two values are combined to calculate an entity's "cache weight": its "age" (the time in milliseconds of not being read) and its size in bytes. The resulting value is in turn compared to an abstract "free space" value, calculated by subtracting the current total cache size in bytes from the abstract threshold value defined here. If this comparison deems the tested entity to be "too heavy" for the cache, its data is cleared from the cache. It is also cleared from the cache if its "age" is greater than the timeout defined here.
This is a relatively simple and extremely fast algorithm to create the following behavior:

1. Cached data that seems to not be used currently ("too old") is cleared.
2. Apart from that, as long as there is "enough space", nothing is cleared.
3. The old and bigger an entity's data is, the more likely it is to be cleared.
4. The less free space there is in the cache, the sooner cached entity data is cleared.

This combination of rules is relatively accurate on keeping cached what is needed and dropping the rest, while being easily tailorable to suit an application's needs.

Parameters:

timeoutMs - the time (in milliseconds, greater than 0) of not being read (the "age"), after which a particular entity's data will be cleared from the Storage's internal cache.

threshold - an abstract value (greater than 0) to evaluate the product of size and age of an entity in relation to the current cache size in order to determine if the entity's data shall be cleared from the cache.

Returns:

a new StorageEntityCacheEvaluator instance.

Throws:

one.microstream.exceptions.NumberRangeException - if any of the passed values is equal to or lower than 0.

See Also:

New(), New(long), StorageEntityCacheEvaluator.Defaults