suparnatural-cache / com.suparnatural.core.cache

Package com.suparnatural.core.cache



interface Cache

A generic Cache. A cache can be backed by persistent stores. The main different between cache and a persistent store is that the latter is considered to be slower than the former. Therefore, the APIs to access objects from a persistent store are not the same as that of a cache. For example, in InMemoryCache vs DiskStore, the InMemoryCache is the primary data structure which other parts of the application should interact with while DiskStore can be used to rehydrate the cache after a cold start.


interface Cacheable

Any object which should be cached must be Cacheable. Each cache object must have a unique identifier returned by cacheKey. If the object wishes to be persistable, then the serializeForPersistence method can return a string which represents its serialized version.


data class CacheableContainer

A Container which holds Cacheable objects which can identified by the key derived from Cacheable.cacheKey. The cached object is converted to immutable before caching. So any updates to the same object will cause an error.


object CacheManager

A thread-safe object which manages the cache based on initialization parameters.


interface CacheReplacementPolicy

A Cache Replacement policy maintains a registry of cached objects to free space when cache is full. The object removed when cache fills up depends on the implementation of CacheReplacementPolicy.evictUnsafe method.


interface CacheStore

A persistent store to back a cache. This store is considered to be slow by default. Therefore, direct interaction with it to access cached objects should be avoided. The store is useful in certain scenarios.


class CacheStoreBlockingWorker : CacheStoreWorker

A CacheStoreWorker which blocks the calling thread.


class CacheStoreNonBlockingWorker : CacheStoreWorker

A background worker for the cache store which does not block the calling thread. The calling thread cannot wait for the result. Therefore, this worker is supposed to be used in a fire and forget scenario. Otherwise, use CacheStoreBlockingWorker.


interface CacheStorePreprocessor<T : Cacheable, out R : Cacheable, in V : Cacheable>

A CacheStorePreprocessor processes Cacheable objects before persisting them in the store and after they are read from the store.


interface CacheStoreWorker

A CacheStore schedules its operations (controlled by CacheStore.blocking parameter) on a CacheStoreWorker. Workers are expected to operate in a single mode (blocking/non-blocking). Therefore, each worker can assume the mode in which it will be invoked in and should schedule all of its tasks (with exceptions) in that mode forever.


class DiskStore : CacheStore

A CacheStore which persists Cacheable objects on the disk. By default, the store blocks the calling thread for all its operations which can changed by setting blocking to false.


class FifoCacheReplacementPolicy : CacheReplacementPolicy

A cache replacement policy which evicts the oldest object from cache to make space when cache is full.


abstract class InMemoryCache : Cache

An abstract, thread-safe in-memory cache with a custom HashTable implementation backed by an array of atomic values. It guarantees consistency in both single and multi-threaded environment.


class LinearProbingCache : InMemoryCache

A thread-safe InMemoryCache with a custom HashTable implementation based on Linear Probing.


data class RawCacheable : Cacheable

A container to hold raw version for a cached object read from a persistent store. For example, in case of a disk store, key is the file name and value is the file contents. This is the first Cacheable object passed to the preprocessor chain. Therefore, your first preprocessor should expect RawCacheable as the input to CacheStorePreprocessor.unarchive method.


class RobinHoodProbingCache : InMemoryCache

A thread-safe InMemoryCache with a custom HashTable implementation using Robin Hood hashing.