ballerina/cache

Overview

This module provides APIs for in-memory caching by using a semi-persistent mapping from keys to values. Cache entries are added to the cache manually and are stored in the cache until either evicted or invalidated manually.

This is based on the Least Recently Used (LRU) eviction algorithm by using a map data structure and defining the most basic operations on a collection of cache entries, which entails basic reading, writing, and deleting individual cache items. It does not allow the () as a key or value of the cache and entries can be accessed safely by multiple concurrent threads as it is thread-safe.

The cache can be defined with optional configurations as follows:

1cache:Cache cache = new (capacity = 10, evictionFactor = 0.2, defaultMaxAge = 0.5, cleanupInterval = 1);

The Cache entries will be evicted in case of the following scenarios:

  • When using the get API, if the returning cache entry has expired, it gets removed.
  • When using the put API, if the cache size has reached its capacity, the number of entries that get removed will be based on the eviction policy and the eviction factor.
  • If cleanupInterval (optional property) is configured, the recurrence task will remove the expired cache entries based on the configured interval. The main benefit of this property is that you can optimize the memory usage while adding some additional CPU costs and vice versa. The default behaviour is the CPU-optimized method.

The cache:AbstractCache object has the common APIs for the caching functionalities. Custom implementations of the cache can be done with different data storages like file, database, etc., with the structural equivalency to the cache:AbstractCacheObject object.

1public type AbstractCache object {
2 public function put(string key, any value, int maxAgeInSeconds) returns Error?;
3 public function get(string key) returns any|Error;
4 public function invalidate(string key) returns Error?;
5 public function invalidateAll() returns Error?;
6 public function hasKey(string key) returns boolean;
7 public function keys() returns string[];
8 public function size() returns int;
9 public function capacity() returns int;
10};

The Ballerina Cache package provides the cache:Cache class, which is a map data structure based implementation of the cache:AbstractCache object.

Classes

[1]

Cache

The cache:Cache object, which is used for all the cache-related operations.

Object types

[1]

AbstractCache

The cache:AbstractCache object is used for custom implementations of the Ballerina cache.

Records

[1]

CacheConfig

Represents configurations for the cache:Cache object.

Enums

[1]

EvictionPolicy

Possible types of eviction policy that can be passed into the EvictionPolicy.

Errors

[1]

Error

Represents Cache related errors.