Module Rache.SingletonBorrowMapSource
SingletonBorrowMap(H) is a borrow-map module but it only supports singleton maps: maps with at most one element.
The create function ignores its size-limit parameter: the size limit is hardcoded to 1.
Note that all policies are equivalent in the case of a singleton borrow-map. This is why the singleton borrow-map does not require the user to specify any policy.
A Mutable structure akin to a hash-table, but with a size bound. When an element is added that would cause the size to overflow the bound, a different element is removed.
BORROW caches are intended to hold resources (think file-descriptors or database connections). To that end, a BORROW cleans-up resources when they are removed. When using this cache, be mindful about ownership: the cache is the owner of the resources, you can only borrow them. You can find more details the documentation of each function bellow.
In other words, a BORROW is similar to a TRANSFER except that:
- It only allows borrowing of resources. All resources are under the ownership of the cache. Always.
- It is always unsafe to clean-up resources obtained from a
BORROW. - Resources are created by the cache, on-demand. This allows the cache to have ownership of the resources from the beginning of their lifetime.
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.
In general, the caches of Rache are intended to be used in settings that do not require strict, by-the-number, extremely-predictable behaviors.
See Rache (or Functors) for more information.
Parameters
Signature
The type of keys on which resources in the cache are indexed.
The type of caches holding bindings from key to 'resource
Sourceval create : (key -> 'resource -> unit) -> int -> 'resource t create destroy n creates a cache with a size-bound of n. Remember that size-bound is not upheld strictly by all caches. Moreover, caches instantiated with a specialised size (i.e., empty and singleton caches) ignore the size parameter entirely.
Accessing (and implicitly adding elements)
Sourceval borrow_or_make :
'resource t ->
key ->
(key -> 'resource) ->
('resource -> 'a) ->
'a borrow_or_make c k mk f
If k is bound to r in c then it calls f r.
Otherwise, it generates r using mk, then inserts the binding k-to-r in c, then calls f r.
Note that inserting the binding in c may cause another binding to be removed and its associated resource to be cleaned-up.
It is unsafe to make use of c during the evaluation of f.
It is unsafe to clean-up r.
Note that the in caches with a non-FIFO replacement policy, this may have a side effect on the k-to-r binding. Specifically, in those caches, it might make it less likely to be removed when supernumerary bindings are inserted.
Sourceval borrow : 'resource t -> key -> ('resource -> 'b) -> 'b option borrow c k f calls f with r if k is bound to r in c. This does not remove the resource from the cache: the cache is still responsible for cleaning-up the resource.
It is unsafe to use the cache from within the function f.
It is unsafe to clean-up r.
Note that the in caches with a non-FIFO replacement policy, this may have a side effect on the k-to-v binding. Specifically, in those caches, it might make it less likely to be removed when supernumerary bindings are inserted.
Sourceval fold : (key -> 'resource -> 'b -> 'b) -> 'resource t -> 'b -> 'b fold f c init folds the function f and value init over the bindings of c from newest to oldest.
At each called to f, the resource of the traversed binding is borrowed by f. Consequently, the same limitations apply for fold as for borrow.
It is unsafe to clean-up any of the borrowed resources.
It is unsafe to use the cache from within f.
Sourceval fold_oldest_first :
(key -> 'resource -> 'b -> 'b) ->
'resource t ->
'b ->
'b fold_oldest_first is like fold but in reversed order: the elements that would be the first to be removed are traversed first. In a FIFO cache, it is oldest-first traversal.
The same limitations and warning applies as for fold.
Removing elements from the cache
The removal functions (remove, clear, and filter) remove the specified elements from the cache. In all cases, the resources are cleaned-up by the cache.
remove c k removes and cleans-up the binding from k in c. If k is not bound in c, it does nothing.
Sourceval clear : 'resource t -> unit clear c removes and cleans-up all bindings from c.
Sourceval filter : 'resource t -> (key -> 'resource -> bool) -> unit filter c f removes and cleans-up all the bindings (k, v) such that f k v = false.
Introspecting the cache's state
Sourceval length : 'resource t -> int length c is the number of bindings held by c.
Sourceval capacity : 'resource t -> int capacity c is the number of bindings c can hold: capacity (create n) = n