A Mutable structure akin to a Ringo.CACHE_MAP but with Lwt-aware functions. E.g., consider the following use of a Ringo.CACHE_MAP:
let c = Ringo_map.create 1024 in
let resolve k =
match Ringo_map.find_opt k with
| Some v -> Lwt.return v
| None ->
do_resolve k >>= fun v ->
Ringo_map.replace c k v;
Lwt.return v
In this example, there is a race condition: if do_resolve takes time to complete, another call to resolve may be made concurrently to the first one.
The function find_or_replace in Ringo_lwt.CACHE_MAP works around this issue.
module C : Ringo.CACHE_MAPtype key = C.keyThe type of keys on which values in the cache are indexed.
The type of Lwt-friendly caches holding bindings from key to 'a.
Instead of adding values directly to this cache, you can add promises (using replace) or, more interestingly, atomically (a) querying for an already bound promises or (b) generating a new one if needed. This helps avoid race conditions.
A promise is removed from the cache if:
Ringo.CACHE_MAP for details).cleared (in which case the promise is canceled).replaced by another one (in which case it is canceled).removed (in which case it is canceled).If a promise is not held by the cache, then it cannot be removed from the cache and it will not be canceled by the cache.
val create : int -> 'a tcreate n creates a cache with a size-bound of n. Remember that the size-bound is not upheld strictly by all caches.
replace c k p binds the key k to p in the cache c.
Note that when a promise is rejected, it is automatically removed from the cache.
Note that, for the purpose of determining if an inserted binding is supernumerary, and thus if it pushes another binding out of the cache, an unresolved binding counts fully.
fold f c init folds the function f and value init over the bindings of c. More specifically, it takes the bindings that are in c at the moment of the call (inserting a binding whilst the fold promise is pending has no effect on the fold promise) and traverses them sequentially: it waits for one step of the folding to resolve before starting the next one. Promises that are rejected are not visible by this fold operation: they are simply ignored.
E.g., you can run fold (fun _ _ () -> Lwt.return_unit) () to wait for all currently-held bindings to resolve.
Note that for some caches, this function may fold over a subset of the bindings of c. Specifically, on caches with a Weak overflow policy, only the strongly-held elements are folded over.
fold_promises f c init folds the function f and value init over the promises of bindings of c. More specifically, it takes the bindings that are in c at the moment of the call (inserting a binding whilst the fold promise is pending has no effect on the fold promise) and traverses them all immediately. The function that folds over the bindings is given the promises (rather than the values these promises resolve to).
E.g., You can count the number of resolved/pending like so: fold_promises
(fun _ p (sleeping, not_sleeping) ->
match Lwt.state p with
| Sleep -> (sleeping + 1, not_sleeping)
| Return _ -> (sleeping, not_sleeping + 1)
| Fail _ -> assert false (* these are removed from the cache *)
)
c
(0, 0)
Note that for some caches, this function may fold over a subset of the bindings of c. Specifically, on caches with a Weak overflow policy, only the strongly-held elements are folded over.
find_opt c k is None if k is not bound in c. Otherwise it is Some p where p is bound to k in c.
Note that the in some caches, this may have a side effect on the k-to-v binding. Specifically, in some caches, it might make it less likely to be removed when supernumerary bindings are inserted.
find_or_replace c k f behaves likes find_opt c k if k is bound in c, and it behaves like replace c k f otherwise. Either way, it returns the promise that resolves to the value associated to k whichever behavior find_or_replace resembled.
remove c k removes the binding from k in c. If k is not bound in c, it does nothing. If the binding is not resolved yet, it also cancels the promise.
Note that in some caches, removed bindings can still count towards the size bound for some time.
val length : 'a t -> intlength c is the number of bindings held by c.
val capacity : 'a t -> intcapacity c is the number of bindings c can hold: capacity (create n) = n
val clear : 'a t -> unitclear c removes all bindings from c. It also cancels unresolved bindings.