vblt.org
forked from
gazagnaire.org/irmin
Persistent store with Git semantics: lazy reads, delayed writes, content-addressing
1(** Lazy trees with delayed writes.
2
3 Trees are like Git's staging area: immutable, temporary, non-persistent
4 areas held in memory. Reads are done lazily and writes are accumulated until
5 commit - if you modify a key twice, only the last change is written. *)
6
7(** {1 Tree Functor} *)
8
9module Make (F : Codec.S) : sig
10 type t
11 (** Immutable in-memory tree with lazy reads and delayed writes. *)
12
13 type hash = F.hash
14
15 (** {2 Path Type} *)
16
17 type path = string list
18 (** A path is a list of path segments. *)
19
20 (** {2 Concrete Trees} *)
21
22 type concrete = [ `Contents of string | `Tree of (string * concrete) list ]
23 (** Fully materialized tree for import/export. *)
24
25 (** {2 Construction} *)
26
27 val empty : unit -> t
28 (** [empty ()] creates an empty tree. *)
29
30 val of_hash : backend:hash Backend.t -> hash -> t
31 (** [of_hash ~backend h] creates a tree backed by the store. Nothing is loaded
32 until accessed (lazy reads). *)
33
34 val of_concrete : concrete -> t
35 (** [of_concrete c] creates a tree from a fully materialized tree. *)
36
37 val shallow : hash -> t
38 (** [shallow h] creates a tree with only a hash reference. Accessing contents
39 raises an error. *)
40
41 val pruned : hash -> t
42 (** [pruned h] creates a pruned tree that raises on dereference. Used for GC
43 and export operations. *)
44
45 (** {2 Reads (Lazy)} *)
46
47 val find : t -> path -> string option
48 (** [find t path] looks up contents at [path]. Loads nodes lazily as needed.
49 *)
50
51 val find_tree : t -> path -> t option
52 (** [find_tree t path] looks up a subtree at [path]. *)
53
54 val list : t -> path -> (string * [ `Node | `Contents ]) list
55 (** [list t path] lists entries at [path]. *)
56
57 val mem : t -> path -> bool
58 (** [mem t path] checks if [path] exists. *)
59
60 val mem_tree : t -> path -> bool
61 (** [mem_tree t path] checks if a subtree exists at [path]. *)
62
63 (** {2 Writes (Delayed)} *)
64
65 val add : t -> path -> string -> t
66 (** [add t path contents] adds contents at [path]. The write is accumulated,
67 not performed immediately. *)
68
69 val add_tree : t -> path -> t -> t
70 (** [add_tree t path subtree] adds a subtree at [path]. *)
71
72 val remove : t -> path -> t
73 (** [remove t path] removes the entry at [path]. *)
74
75 (** {2 Materialization} *)
76
77 val to_concrete : t -> concrete
78 (** [to_concrete t] fully materializes the tree. Forces all lazy nodes to be
79 loaded. *)
80
81 val hash : ?inline_threshold:int -> t -> backend:hash Backend.t -> hash
82 (** [hash ?inline_threshold t ~backend] computes the tree hash. Writes all
83 accumulated changes to the backend. If [inline_threshold] is given,
84 contents at or below that size (in bytes) are stored directly in the
85 parent node rather than as separate blobs. Defaults to the codec's
86 [inline_threshold]. *)
87
88 (** {2 Force Control} *)
89
90 type 'a force = [ `True | `False of hash -> 'a | `Shallow of hash -> 'a ]
91 (** Control how lazy nodes are handled during traversal:
92 - [`True]: force loading of all nodes
93 - [`False f]: call [f] on unloaded hashes instead
94 - [`Shallow f]: like [`False] but for shallow trees *)
95
96 val fold :
97 ?force:'a force ->
98 t ->
99 'a ->
100 (path -> [ `Contents of string | `Tree ] -> 'a -> 'a) ->
101 'a
102 (** [fold ~force t init f] traverses the tree. The [force] parameter controls
103 lazy loading behavior. *)
104
105 (** {2 Cache Management} *)
106
107 val clear : ?depth:int -> t -> unit
108 (** [clear ?depth t] purges cached data. If [depth] is given, only clears
109 nodes at that depth or deeper. *)
110
111 (** {2 Comparison} *)
112
113 val equal : t -> t -> bool
114 (** [equal t1 t2] compares trees structurally. *)
115end
116
117(** {1 Pre-instantiated Trees} *)
118
119module Git : module type of Make (Codec.Git)
120(** Git-format trees with SHA-1 hashes. *)
121
122module Mst : module type of Make (Codec.Mst)
123(** MST-format trees with SHA-256 hashes. *)