ringo 0.2 · OCaml Package

Preamble

module type UNBOXED_COLLECTION = sig ... end

A mutable structure that holds at most a fixed number of values of a same type. Values are not removed by hand, instead, once the limit is reached, adding a value replaces the oldest one in the buffer.

module Ring : UNBOXED_COLLECTION

Ring is a potentially useful module that is used internally to manage bounded, FIFO collections of items. The documentation is available in UNBOXED_COLLECTION.

module Dll : UNBOXED_COLLECTION

Dll is a potentially useful module that is used internally to manage bounded, FIFO collections of items. The documentation is available in UNBOXED_COLLECTION.

Caches

module type CACHE = sig ... end

A Mutable structure akin to a hash-table, but with a size bound. Note that, different caches have different policies towards the size bounds: some uphold the bound strictly, some treat the bound as a suggestion. In addition, some caches count their elements somewhat sloppily.

All caches of Ringo have the CACHE interface. However, their behavior can be tweaked by the parameters below.

type replacement =

| LRU
| FIFO

replacement is for defining the replacement policy of a cache. 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.

type overflow =

| Strict
| Loose

overflow is for defining the overflow policy of a cache. Strict means that the cache never holds more element than is specified when calling create (see MAKER below and CACHE). Loose means that the cache may hold more elements than specified when calling create but that supernumerary elements may be collected by the Garbage Collector.

type accounting =

| Precise
| Sloppy

accounting is for defining the accounting policy of a cache. 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.

module type MAKER =
  functor (H : Stdlib.Hashtbl.HashedType) ->
  CACHE with type key = H.t

A MAKER is a functor that instantiates CACHEs based on a given type and its associated hash function.

type maker = (module MAKER)

val maker : 
  replacement:replacement ->
  overflow:overflow ->
  accounting:accounting ->
  maker

maker ~replacement ~overflow ~accounting is a first-class MAKER that instantiates caches with the policies specified by replacement, overflow, and accounting.

package ringo