Package 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.

  • Method Details

    • 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 particularentity's data will be cleared from the Storage's internal cache.
      Returns:
      a new StorageEntityCacheEvaluator instance.
      Throws:
      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:
      NumberRangeException - if any of the passed values is equal to or lower than 0.
      See Also:
      New(), New(long), StorageEntityCacheEvaluator.Defaults