This API documentation is for Ballerina 1.2.0. View API documentation for the latest release.

Module : cache

Module Overview

This module provides APIs for handle caching in Ballerina. It consists of a default implementation based on the map data structure. It also provides a default cache eviction policy object, which is based on the LRU eviction algorithm.

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.

public type AbstractCache abstract object {
    public function put(string key, any value, int maxAgeInSeconds) returns Error?;
    public function get(string key) returns any|Error;
    public function invalidate(string key) returns Error?;
    public function invalidateAll() returns Error?;
    public function hasKey(string key) returns boolean;
    public function keys() returns string[];
    public function size() returns int;
    public function capacity() returns int;
};

The cache:AbstractEvictionPolicy object has the common APIs for the cache eviction functionalities. Custom implementations of the eviction policy can be done by maintaining the cache:LinkedList data structure according to the eviction algorithm.

public type AbstractEvictionPolicy abstract object {
    public function get(Node node);
    public function put(Node node);
    public function remove(Node node);
    public function replace(Node newNode, Node oldNode);
    public function clear();
    public function evict() returns Node?;
};

The Ballerina Cache module provides the cache:Cache object, which is a map data structure based implementation of the cache:AbstractCache object. It is not recommended to insert () as the value of the cache since it doesn't make sense to cache a nil. Also, it provides the cache:LruEvictionPolicy object, which is based on the LRU eviction algorithm.

While initializing the cache:Cache, you need to pass the following parameters as the cache configurations.

For a better user experience, the above-mentioned configuration is initialized with the below default values:

public type CacheConfig record {|
    int capacity = 100;
    AbstractEvictionPolicy evictionPolicy = new LruEvictionPolicy();
    float evictionFactor = 0.25;
    int defaultMaxAgeInSeconds = -1;
    int cleanupIntervalInSeconds?;
|};

There are 2 mandatory scenarios and 1 optional scenario in which a cache entry gets removed from the cache and maintains the freshness of the cache entries. The 2 independent factors (i.e., eviction policy and freshness time of the cache entry) governs the 3 scenarios.

  1. When using the get API, if the returning cache entry has expired, it gets removed.
  2. When using the put API, if the cache size has reached its capacity, the number of entries get removed based on the 'eviction policy' and the 'eviction factor'.
  3. If cleanupIntervalInSeconds (optional property) is configured, the timer task will remove the expired cache entries based on the configured interval.

The main benefit of using the cleanupIntervalInSeconds (optional) property is that the developer can optimize the memory usage while adding some additional CPU costs and vice versa. The default behaviour is the CPU-optimized method.

The concept of the default cache:Cache object is based on the Ballerina map data structure and the cache:LinkedList data structure. The key of the map entry would be a string and the value of the map entry would be a node of the linked list.

public type Node record {|
    any value;
    Node? prev = ();
    Node? next = ();
|};

While using the cache, a cache:CacheEntry record will be created and added as the value of the cache:Node record. The cache:Node record will be inserted into the map data structure with the provided string key.

type CacheEntry record {|
    string key;
    any data;
    int expTime;
|};

A linked list is used for the eviction of the cache. According to the user-configured eviction policy, when inserting / updating / retrieving cache entries, the linked list will be updated. Therefore, when an eviction happens, cache entries can be removed efficiently without iterating the complete map data structure.

Example: If the eviction policy is LRU, the MRU item will always be the head of the linked list. When an eviction happens, nodes from the tail will be deleted without iterating the map.

Furthermore, you can implement custom caching implementations based on different cache storage mechanisms (file, database. etc.) and different eviction policies (MRU, FIFO, etc.). Ballerina provides a "map-based cache" as the default cache implementation.

For information on the operations, which you can perform with the cache module, see the below Functions. For examples on the usage of the operations, see Cache Example

Records

CacheConfig

Represents configurations for the cache:Cache object.

Detail

Record type to hold the details of an error.

Node

Represents a structure to keep data and references to the adjacent nodes of the linked list.

Objects

AbstractCache

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

AbstractEvictionPolicy

The cache:AbstractEvictionPolicy Ballerina object is used for custom implementations of the eviction policy for a Ballerina cache object.

Cache

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

LinkedList

The cache:LinkedList object consists operations of LinkedList data structure which are related to LRU eviction algorithm

LruEvictionPolicy

The cache:LruEvictionPolicy object consists of the LRU eviction algorithm related operations based on a linked list data structure.

Constants

CACHE_ERROR

Represents the reason for the cache:Error.

Errors

Error

Represents the Cache error type with details.