unikernel/duniverse/ocaml-caqti/caqti/lib-platform/request_cache.mli

@@ -0,0 +1,76 @@
+(* Copyright (C) 2025  Petter A. Urkedal <paurkedal@gmail.com>
+ *
+ * This library is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or (at your
+ * option) any later version, with the LGPL-3.0 Linking Exception.
+ *
+ * This library is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
+ * License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * and the LGPL-3.0 Linking Exception along with this library.  If not, see
+ * <http://www.gnu.org/licenses/> and <https://spdx.org>, respectively.
+ *)
+
+(** Cache for associating data to requests for a fixed dialect. *)
+
+module type S = sig
+  type elt
+  type t
+
+  val create : ?dynamic_capacity: int -> Caqti_template.Dialect.t -> t
+  (** [create dialect] creates a cache of prepared queries for requests
+      specialized for [dialect].
+
+      @param dynamic_capacity
+        is the sum weight of elements of the LRU used for dynamic requests below
+        which {!trim} will not attempt to release anything. *)
+
+  val find_and_promote :
+    t -> ('a, 'b, 'm) Caqti_template.Request.t -> elt option
+  (** [find_and_promote cache request] promotes and returns the data associated
+      with [request] in [cache], if any. *)
+
+  val add : t -> ('a, 'b, 'm) Caqti_template.Request.t -> elt -> unit
+  (** Given the hard precondition that [request] is not bound in [cache], as
+      verified by {!find_and_promote}, [add cache request data] binds it to
+      [data]. *)
+
+  val remove_and_discard : t -> ('a, 'b, 'm) Caqti_template.Request.t -> unit
+  (** [remove_and_discard cache request] removes the binding for [request] from
+      [cache]. The caller is assumed to have just extracted the element with
+      {!find_and_promote} and is resposible for releasing related resources. *)
+
+  val deallocate :
+    t -> ('a, 'b, 'm) Caqti_template.Request.t -> (elt * (unit -> unit)) option
+  (** [deallocate request] returns the entry for [request], if any, along with a
+      function to remove it from the cache. *)
+
+  val iter : (elt -> unit) -> t -> unit
+  (** [iter f cache] calls [f] on each element of [cache]. *)
+
+  val elements : t -> elt list
+  (** [elements cache] is an arbitrarily ordered list of all elements, whether
+      associated with a static or dynamic request. *)
+
+  val trim : ?max_promote_count: int -> t -> elt list * (unit -> unit)
+  (** [trim ?promote_count cache] carrious out some work trimming elements from
+      the dynamic LRU cache.
+      The call promotes up to [max_promote_count] elements, which are alive
+      according to the garbage collector, and stop at the next one.
+      It is up to the caller to free any resources associated with the returned
+      elements. *)
+
+  val clear_and_discard : t -> unit
+  (** [clear cache] removes all entries form [cache].  Elements are not
+      returned, since this function may be used after a connection reset which
+      invalidates the cached resources, but can be requested by calling
+      {!elements} first. *)
+
+  val dynamic_weight : t -> int
+end
+
+module Make : functor (Elt : Lru.Weighted) -> S with type elt = Elt.t