Add doc in lru.mli and improve the add function.

lyrm · lyrm · commit d73b4e102d47 · 2025-10-15T18:34:00.000+02:00
diff --git a/src/irmin/lru.ml b/src/irmin/lru.ml
@@ -92,39 +92,30 @@ module Make (H : Hashtbl.HashedType) = struct
     match tl with
     | None -> None
     | Some ({ Q.value = k, v; _ } as n) ->
-        Xt.modify ~xt t.w (fun tw -> tw - 1);
+        Xt.decr ~xt t.w;
         HT.Xt.remove ~xt t.ht k;
         Q.detach ~xt t.q n;
         Some v
 
-  let remove ~xt t k =
-    match HT.Xt.find_opt ~xt t.ht k with
-    | None -> ()
-    | Some n ->
-        Xt.modify ~xt t.w (fun tw -> tw - 1);
-        HT.Xt.remove ~xt t.ht k;
-        Q.detach ~xt t.q n
-
-  let add t k v =
-    let tx ~xt =
-      let add t k v =
-        remove ~xt t k;
-        let n = Q.node (k, v) in
-        Xt.modify ~xt t.w (fun tw -> tw + 1);
-        HT.Xt.replace ~xt t.ht k n;
-        Q.append ~xt t.q n
-      in
-      match t.cap with
-      | Capped c when c = 0 -> ()
-      | Uncapped -> add t k v
-      | Capped c ->
-          add t k v;
-          if weight ~xt t > c then
-            let _ = drop ~xt t in
-            ()
+  let add ~xt t k v =
+    let add t k v =
+      let n = Q.node (k, v) in
+      (match HT.Xt.find_opt ~xt t.ht k with
+      | Some old -> Q.detach ~xt t.q old
+      | None -> Xt.incr ~xt t.w);
+      Q.append ~xt t.q n;
+      HT.Xt.replace ~xt t.ht k n
     in
-    Xt.commit { tx }
-
+    match t.cap with
+    | Capped c when c = 0 -> ()
+    | Uncapped -> add t k v
+    | Capped c ->
+        add t k v;
+        if weight ~xt t > c then
+          let _ = drop ~xt t in
+          ()
+
+  let add t k v = Xt.commit { tx = add t k v }
   let drop t = Xt.commit { tx = drop t }
 
   let promote ~xt t n =
diff --git a/src/irmin/lru.mli b/src/irmin/lru.mli
@@ -15,14 +15,37 @@
 
 (* Extracted from https://github.com/pqwy/lru *)
 
+(** LRU cache implementation *)
 module Make (H : Hashtbl.HashedType) : sig
   type 'a t
 
   val create : int -> 'a t
+  (** [create n] returns a new LRU cache with the maximum size of [n]. If [n] is
+      non-positive, the LRU cache is unbounded and is automatically internally
+      resized. *)
+
   val add : 'a t -> H.t -> 'a -> unit
+  (** [add t k v] adds the binding [k -> v] to the cache [t]. If the cache is
+      full, the least recently used element is evicted. If [k] was already
+      bound, its previous binding is replaced by [v] and it is marked as most
+      recently used. *)
+
   val find : 'a t -> H.t -> 'a
+  (** [find t k] returns the value associated with [k] in the cache [t], and
+      marks [k] as most recently used. Raises [Not_found] if [k] is not bound in
+      [t]. *)
+
   val mem : 'a t -> H.t -> bool
+  (** [mem t k] checks if [k] is bound in the cache [t], and marks [k] as most
+      recently used if it is. *)
+
   val clear : 'a t -> unit
+  (** [clear t] removes all bindings from the cache [t]. *)
+
   val iter : 'a t -> (H.t -> 'a -> unit) -> unit
+  (** [iter t f] calls [f k v] for all bindings in the cache [t]. *)
+
   val drop : 'a t -> 'a option
+  (** [drop t] removes the least recently used binding from the cache [t] and
+      returns its value, or [None] if the cache is empty. *)
 end
