package ringo-lwt

Ringo

Caches (bounded-size, key-value or simple-value stores) and other bounded-size collections.

Cache

A map-cache (Sigs.CACHE_MAP) (resp. a set-cache, Sigs.CACHE_SET) is a module that implements an imperative, key-value (resp. value) store.

A cache is bounded in size – meaning that inserting bindings (resp. elements) beyond the cache capacity removes other bindings (resp. elements).

The specific behaviour of the cache is controlled by different options. Specifically, the replacement policy (which bindings (resp. elements) are removed when supernumerary bindings (resp. elements) are inserted), the overflow policy (when are bindings (resp. elements) removed), the accounting policy (how precisely are bindings (resp. elements) counted), and the capacity (how many bindings (resp. elements) a cache can hold), are all controlled by parameters.

Cache parameters

• replacement is for defining the replacement policy of a cache and is provided when instantiating the Cache module.

  LRU is for "Least Recently Used", meaning that when a supernumerary item is inserted in the cache, the least recently used item is removed to make room. FIFO is for "First-In, First-Out" meaning that when a supernumerary item is inserted in the cache, the oldest inserted element is removed to make room.

• overflow is for defining the overflow policy of a cache and is provided when instantiating the Cache module.

  Strong means that the cache never holds more element than is specified when calling create. Weak means that the cache may hold more elements than specified when calling create but that supernumerary elements may be collected by the Garbage Collector.

• accounting is for defining the accounting policy of a cache and is provided when instantiating the Cache module.

  Precise means that the cache counts its number of elements precisely. Sloppy means that the cache may count elements that have been removed from the cache as still being held by the cache.

  Note that when requesting a Sloppy cache, the library might give you a Precise cache if there is no additional runtime cost. In general, Sloppy caches are more efficient, but (1) they are not adapted to situations where you remove many elements and (2) depending on the other parameters they might be only as-efficient-as (not more) than Precise caches.

  Use Precise only if you use remove a lot or if you need strong guarantee on the number of elements.

• capacity is for specifying the size-bound of the cache and is specified when calling Cache.create to instantiate a cache.

Lwt, Option and Result wrappers

The package ringo-lwt includes wrappers for making Ringo map-caches friendly to Lwt. Specifically, it includes a functor that, given a map-cache, will produce a new cache with the following features:

• replace now takes a promise rather than a value,

• find_or_replace is a function that either returns the promise currently bound to the given key or makes a new promise, and

• promises that are rejected are automatically removed from the cache.

Two further functors provide integration for Lwt-and-Option (wherein promises resolving to None are also removed) and Lwt-and-Result (wherein promises resolving to Error are also removed).

These additional abstractions help avoiding race conditions.

Ring, Dll

Both rings and dlls are bounded-size imperative collections. Unlike caches, their interface is much simpler: essentially providing add and remove.

They are used internally to implement some components of the caches. They are exposed because they can be useful.