From a2e885da7d2e0c0395bc9b5800206382d565204e Mon Sep 17 00:00:00 2001 From: ArthurW Date: Fri, 24 May 2024 17:32:35 +0200 Subject: [PATCH 01/22] Fix RO sync: clear LRU for all log updates --- CHANGES.md | 1 + src/index.ml | 7 +++++-- test/issues/dune | 4 ++++ test/issues/issue398.ml | 23 +++++++++++++++++++++++ 4 files changed, 33 insertions(+), 2 deletions(-) create mode 100644 test/issues/dune create mode 100644 test/issues/issue398.ml diff --git a/CHANGES.md b/CHANGES.md index 48e0507b..5ce73c7b 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -6,6 +6,7 @@ - Lock files are now opened with O_CLOEXEC flag (#394, @vect0r-vicall) - Update to cmdliner.1.1.0 (#382, @MisterDA) - Mirage support: optional dependency to unix (#396, @art-w) +- Fix RO sync: clear LRU for all log updates (#399, @art-w) # 1.6.2 (2023-06-06) diff --git a/src/index.ml b/src/index.ml index 6dde17a4..37a5f7d0 100644 --- a/src/index.ml +++ b/src/index.ml @@ -310,12 +310,14 @@ struct Log_file.close log; (* check that file is on disk, reopen and reload everything. *) hook `Reload_log_async; + Lru.clear t.lru; t.log_async <- try_load_log t (Layout.log_async ~root:t.root) (* else if the disk offset is greater, reload the newest data. *)) - else if old_offset < h.offset then + else if old_offset < h.offset then ( + Lru.clear t.lru; Log_file.sync_entries ~min:old_offset log (* else if the offset is lesser, that means the [log_async] was - cleared, and the generation should have changed. *) + cleared, and the generation should have changed. *)) else if old_offset > h.offset then ( (* Should never occur, but we can recover by reloading the log from scratch rather than just hard failing. *) @@ -397,6 +399,7 @@ struct Log.debug (fun l -> l "[%s] new entries detected, reading log from disk" (Filename.basename t.root)); + Lru.clear t.lru; Log_file.sync_entries ~min:log_offset log) else (* Here the disk offset should be equal to the known one. A smaller diff --git a/test/issues/dune b/test/issues/dune new file mode 100644 index 00000000..aa34288d --- /dev/null +++ b/test/issues/dune @@ -0,0 +1,4 @@ +(test + (name issue398) + (modules issue398) + (libraries index index.unix)) diff --git a/test/issues/issue398.ml b/test/issues/issue398.ml new file mode 100644 index 00000000..4e5b2d6e --- /dev/null +++ b/test/issues/issue398.ml @@ -0,0 +1,23 @@ +(* See https://github.com/mirage/index/issues/398 *) + +module L = struct + let length = 4 +end + +module I = + Index_unix.Make + (Index.Key.String_fixed (L)) (Index.Value.String_fixed (L)) + (Index.Cache.Noop) + +let () = + let path = "issue398.index" in + let t = I.v path ~log_size:16384 in + let ro = I.v path ~readonly:true ~log_size:16384 in + I.replace t "1234" "aaaa"; + I.flush t; + I.sync ro; + assert (I.find ro "1234" = "aaaa"); + I.replace t "1234" "aaab"; + I.flush t; + I.sync ro; + assert (I.find ro "1234" = "aaab") From 73e78dd774d77f79a5f264393918df16aa5abcf9 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Fri, 9 Oct 2026 16:39:02 +0200 Subject: [PATCH 02/22] opam: add x-maintenance-intent Only the latest release is maintained. Fixes #405. --- index-bench.opam | 1 + index.opam | 1 + 2 files changed, 2 insertions(+) diff --git a/index-bench.opam b/index-bench.opam index f59f83f7..49364607 100644 --- a/index-bench.opam +++ b/index-bench.opam @@ -36,3 +36,4 @@ build: [ ["dune" "runtest" "-p" name "-j" jobs] {with-test} ] dev-repo: "git+https://github.com/mirage/index.git" +x-maintenance-intent: [ "(latest)" ] diff --git a/index.opam b/index.opam index 63716c03..e2d5c74f 100644 --- a/index.opam +++ b/index.opam @@ -11,6 +11,7 @@ homepage: "https://github.com/mirage/index" bug-reports: "https://github.com/mirage/index/issues" dev-repo: "git+https://github.com/mirage/index.git" doc: "https://mirage.github.io/index/" +x-maintenance-intent: [ "(latest)" ] build: [ ["dune" "subst"] {dev} From 7a5bef74bb3e32b53d47487a480f5d946f1e577f Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Fri, 6 Nov 2026 17:32:29 +0100 Subject: [PATCH 03/22] bench.Dockerfile: update apt lists before installing depexts The apt lists of the base image can be stale, and depexts then fail with 404 errors. --- bench.Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/bench.Dockerfile b/bench.Dockerfile index 40e5b8b3..5d99807f 100644 --- a/bench.Dockerfile +++ b/bench.Dockerfile @@ -6,6 +6,6 @@ RUN sudo chown opam . COPY *.opam ./ RUN opam remote add origin https://github.com/ocaml/opam-repository.git && opam update RUN opam pin -yn --with-version=dev . -RUN opam install -y --deps-only --with-test . +RUN sudo apt-get update && opam install -y --deps-only --with-test . COPY . ./ ENTRYPOINT opam exec -- make bench \ No newline at end of file From f12eedc01b999b27e31106a0c1aaa6d5d3324fd6 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Fri, 6 Nov 2026 17:53:16 +0100 Subject: [PATCH 04/22] Move the #398 regression test to the readonly suite Enable the LRU in it: the suite disables it by default. --- test/issues/dune | 4 ---- test/issues/issue398.ml | 23 ----------------------- test/unix/main.ml | 16 ++++++++++++++++ 3 files changed, 16 insertions(+), 27 deletions(-) delete mode 100644 test/issues/dune delete mode 100644 test/issues/issue398.ml diff --git a/test/issues/dune b/test/issues/dune deleted file mode 100644 index aa34288d..00000000 --- a/test/issues/dune +++ /dev/null @@ -1,4 +0,0 @@ -(test - (name issue398) - (modules issue398) - (libraries index index.unix)) diff --git a/test/issues/issue398.ml b/test/issues/issue398.ml deleted file mode 100644 index 4e5b2d6e..00000000 --- a/test/issues/issue398.ml +++ /dev/null @@ -1,23 +0,0 @@ -(* See https://github.com/mirage/index/issues/398 *) - -module L = struct - let length = 4 -end - -module I = - Index_unix.Make - (Index.Key.String_fixed (L)) (Index.Value.String_fixed (L)) - (Index.Cache.Noop) - -let () = - let path = "issue398.index" in - let t = I.v path ~log_size:16384 in - let ro = I.v path ~readonly:true ~log_size:16384 in - I.replace t "1234" "aaaa"; - I.flush t; - I.sync ro; - assert (I.find ro "1234" = "aaaa"); - I.replace t "1234" "aaab"; - I.flush t; - I.sync ro; - assert (I.find ro "1234" = "aaab") diff --git a/test/unix/main.ml b/test/unix/main.ml index 9393d90f..6119a6b3 100644 --- a/test/unix/main.ml +++ b/test/unix/main.ml @@ -596,6 +596,21 @@ module Readonly = struct Alcotest.(check int) "reloadings of log async per merge" 1 !reload_log_async; Index.await t |> check_completed + (** Readonly finds the new value of a key cached in its LRU, after a sync that + reads the update from the log (#398). *) + let sync_after_log_update () = + let* Context.{ rw; clone; _ } = Context.with_empty_index ~lru_size:10 () in + let ro = clone ~readonly:true () in + let k, v1, v2 = (Key.v (), Value.v (), Value.v ()) in + Index.replace rw k v1; + Index.flush rw; + Index.sync ro; + Index.check_binding ro k v1; + Index.replace rw k v2; + Index.flush rw; + Index.sync ro; + Index.check_binding ro k v2 + let tests = [ ("add", `Quick, readonly); @@ -622,6 +637,7 @@ module Readonly = struct `Quick, readonly_sync_and_merge_clear ); ("reload log and log async", `Quick, reload_log_async); + ("sync after log update", `Quick, sync_after_log_update); ] end From 02dc2bfe112cc4de33ecb1e0ef768426b73cba6d Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Fri, 6 Nov 2026 17:55:41 +0100 Subject: [PATCH 05/22] Fix RO sync: also clear the LRU when loading a new log_async During a merge, writes go to log_async. A read-only instance that loads it on sync could still return the old values cached in its LRU. --- src/index.ml | 8 +++++++- test/unix/main.ml | 29 +++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+), 1 deletion(-) diff --git a/src/index.ml b/src/index.ml index 37a5f7d0..806b8483 100644 --- a/src/index.ml +++ b/src/index.ml @@ -295,7 +295,12 @@ struct match t.log_async with | None -> hook `Reload_log_async; - t.log_async <- try_load_log t (Layout.log_async ~root:t.root) + let log_async = try_load_log t (Layout.log_async ~root:t.root) in + (* The entries of a new [log_async] may update keys cached in the LRU. *) + (match log_async with + | Some log when Log_file.cardinal log > 0 -> Lru.clear t.lru + | Some _ | None -> ()); + t.log_async <- log_async | Some log -> let old_generation = t.generation in let old_offset = IO.offset (Log_file.io log) in @@ -329,6 +334,7 @@ struct Reloading the log to compensate." (Filename.basename t.root) Int63.pp old_offset Int63.pp h.offset Int63.pp old_generation Int63.pp h.generation); + Lru.clear t.lru; Log_file.reload log) (** Syncs the [index] of the instance by checking on-disk changes. *) diff --git a/test/unix/main.ml b/test/unix/main.ml index 6119a6b3..35b6ecb9 100644 --- a/test/unix/main.ml +++ b/test/unix/main.ml @@ -611,6 +611,34 @@ module Readonly = struct Index.sync ro; Index.check_binding ro k v2 + (** Readonly finds the new value of a key cached in its LRU, after a sync that + loads the update from a new log_async. *) + let sync_after_log_async_update () = + let* Context.{ rw; clone; _ } = Context.with_empty_index ~lru_size:10 () in + let ro = clone ~readonly:true () in + let merge = Semaphore.make false and merge_started = Semaphore.make false in + let merge_hook = + I.Private.Hook.v @@ function + | `Before -> + Semaphore.release merge_started; + Semaphore.acquire merge + | _ -> () + in + let k, v1, v2 = (Key.v (), Value.v (), Value.v ()) in + Index.replace rw k v1; + Index.flush rw; + Index.sync ro; + Index.check_binding ro k v1; + let t = Index.try_merge_aux ~force:true ~hook:merge_hook rw in + Semaphore.acquire merge_started; + Index.replace rw k v2; + Index.flush rw; + Index.sync ro; + let found = Index.find ro k in + Semaphore.release merge; + Index.await t |> check_completed; + Alcotest.(check string) "value found during the merge" v2 found + let tests = [ ("add", `Quick, readonly); @@ -638,6 +666,7 @@ module Readonly = struct readonly_sync_and_merge_clear ); ("reload log and log async", `Quick, reload_log_async); ("sync after log update", `Quick, sync_after_log_update); + ("sync after log_async update", `Quick, sync_after_log_async_update); ] end From 6a08952826531f9fe418c0f3c6eed05bf53b2114 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Fri, 6 Nov 2026 17:56:31 +0100 Subject: [PATCH 06/22] Document the per-domain Stats functions and Platform.FMT_TTY --- src/platform.ml | 4 ++++ src/stats.mli | 11 +++++++++++ 2 files changed, 15 insertions(+) diff --git a/src/platform.ml b/src/platform.ml index 99a49395..d72ad793 100644 --- a/src/platform.ml +++ b/src/platform.ml @@ -59,8 +59,12 @@ module type THREAD = sig end module type FMT_TTY = sig + (** Terminal setup of the standard formatters, as done by [Fmt_tty]. *) + val setup_std_outputs : ?style_renderer:Fmt.style_renderer -> ?utf_8:bool -> unit -> unit + (** [setup_std_outputs ?style_renderer ?utf_8 ()] sets up the standard + formatters, as [Fmt_tty.setup_std_outputs] does. *) end module type S = sig diff --git a/src/stats.mli b/src/stats.mli index 0e8d18cf..4fd8d8ca 100644 --- a/src/stats.mli +++ b/src/stats.mli @@ -30,7 +30,11 @@ type t = { - [time_sync] is the duration of the latest call to sync. *) val get : unit -> t +(** [get ()] is the stats recorded by the calling domain. *) + val reset_stats : unit -> unit +(** [reset_stats ()] resets the stats of the calling domain. *) + val add_read : int -> unit val add_write : int -> unit val incr_nb_merge : unit -> unit @@ -38,8 +42,15 @@ val incr_nb_replace : unit -> unit val incr_nb_sync : unit -> unit val incr_nb_lru_hits : unit -> unit val incr_nb_lru_misses : unit -> unit + val merge : t -> t -> t +(** [merge s1 s2] is the sum of [s1] and [s2], for instance to combine the stats + of several domains. The duration lists are concatenated, so + [merge_durations] may hold more than 10 elements, and [time_sync] is the sum + of the two latest sync durations. *) + val merge_in : t -> unit +(** [merge_in s] adds [s] to the stats of the calling domain, as {!merge} does. *) module Make (_ : Platform.CLOCK) : sig val start_replace : unit -> unit From e5546a8d364c57a77e3da83f577030747ca37cd7 Mon Sep 17 00:00:00 2001 From: ngoguey42 Date: Fri, 15 Apr 2022 16:03:34 +0200 Subject: [PATCH 07/22] Quickfix for situations where Value hash length 0 --- src/log_file.ml | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/log_file.ml b/src/log_file.ml index 214209d7..4fc231a7 100644 --- a/src/log_file.ml +++ b/src/log_file.ml @@ -77,7 +77,17 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) = struct let len = Entry.encoded_size in let r = IO.read t.io ~off ~len scratch.buffer in assert (r = Entry.encoded_size); - Entry.decode (Bytes.unsafe_to_string scratch.buffer) 0 + let s = + if Value.encoded_size = 0 then + (* Quickfix for a situation where [Key.decode] kept a pointer to [s] + when [Value.encoded_size = 0]. This led to a bug where some entries + dissapeared post-merge. + + A proper solution will be implemented in the future. *) + Bytes.to_string scratch.buffer + else Bytes.unsafe_to_string scratch.buffer + in + Entry.decode s 0 let elt_index t key = (* NOTE: we use the _uppermost_ bits of the key hash to index the bucket From 90fb66694f638d7ac4b2b9aebd93c49d98fe8215 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 13:14:38 +0100 Subject: [PATCH 08/22] Add regression tests for zero-size values With zero-size values, the log scratch buffer holds exactly one key, and a decoder like Repr.decode_bin returns it without copying. The merge then wrote the same key several times and lost the others, and iter gave wrong keys. --- test/unix/main.ml | 1 + test/unix/zero_size_value.ml | 77 +++++++++++++++++++++++++++++++++++ test/unix/zero_size_value.mli | 1 + 3 files changed, 79 insertions(+) create mode 100644 test/unix/zero_size_value.ml create mode 100644 test/unix/zero_size_value.mli diff --git a/test/unix/main.ml b/test/unix/main.ml index 35b6ecb9..18f5019c 100644 --- a/test/unix/main.ml +++ b/test/unix/main.ml @@ -1109,4 +1109,5 @@ let () = ("filter", Filter.tests); ("flush_callback", Flush_callback.tests); ("throttle", Throttle.tests); + ("zero-size values", Zero_size_value.tests); ] diff --git a/test/unix/zero_size_value.ml b/test/unix/zero_size_value.ml new file mode 100644 index 00000000..73a3ed34 --- /dev/null +++ b/test/unix/zero_size_value.ml @@ -0,0 +1,77 @@ +(* Regression test for indexes whose values are encoded on zero bytes, as in + the snapshot export of irmin-pack. + + The log decodes its entries from a reused scratch buffer. With empty values, + this buffer holds exactly one key, and [Repr.decode_bin] returns such a + string as is, without copying it. The decoded keys then share the scratch + buffer, and are overwritten by the next read. *) + +let root = Filename.concat "_tests" "unix.zero_size_value" +let key_size = 20 + +module Key = struct + type t = string + + let t = Repr.string_of (`Fixed key_size) + let equal = String.equal + let hash = Hashtbl.hash + let hash_size = 30 + let encode s = s + let encoded_size = key_size + + (* Like [Repr.decode_bin], return [s] itself when it holds exactly one key. *) + let decode s off = + if off = 0 && String.length s = key_size then s + else String.sub s off key_size +end + +module Value = struct + type t = unit + + let t = Repr.unit + let encode () = "" + let encoded_size = 0 + let decode _ _ = () +end + +module Index = Index_unix.Private.Make (Key) (Value) (Index.Cache.Unbounded) + +let random_key () = + String.init key_size (fun _ -> Char.chr (33 + Random.int 94)) + +let check_present t key = + match Index.find t key with + | () -> () + | exception Not_found -> Alcotest.failf "Key %S is missing" key + +(* The LRU is disabled so that [find] reads the merged data file. *) +let with_index f = + let t = Index.v ~fresh:true ~lru_size:0 ~log_size:1_000 root in + Fun.protect ~finally:(fun () -> Index.close t) (fun () -> f t) + +let add_random_keys t = + let keys = List.init 500 (fun _ -> random_key ()) in + List.iter (fun key -> Index.replace t key ()) keys; + keys + +(* The merge reads the log through [Log_file.to_sorted_seq], which decodes all + the entries of a bucket before sorting them. *) +let merge_keeps_all_keys () = + with_index @@ fun t -> + let keys = add_random_keys t in + Index.try_merge_aux ~force:true t |> Index.await |> Common.check_completed; + List.iter (check_present t) keys + +(* [iter] must give keys that survive the next read of the log. *) +let iter_gives_all_keys () = + with_index @@ fun t -> + let keys = add_random_keys t in + let seen = ref [] in + Index.iter (fun key () -> seen := key :: !seen) t; + Alcotest.(check (slist string String.compare)) "keys given by iter" keys !seen + +let tests = + [ + ("merge keeps all keys", `Quick, merge_keeps_all_keys); + ("iter gives all keys", `Quick, iter_gives_all_keys); + ] diff --git a/test/unix/zero_size_value.mli b/test/unix/zero_size_value.mli new file mode 100644 index 00000000..d38ba9a9 --- /dev/null +++ b/test/unix/zero_size_value.mli @@ -0,0 +1 @@ +val tests : unit Alcotest.test_case list From ba46e5642d4400038369b078934e3018435c3fa5 Mon Sep 17 00:00:00 2001 From: Tom Ridge Date: Tue, 8 Feb 2022 18:32:17 +0000 Subject: [PATCH 09/22] Add docs for src/unix/raw.mli --- src/unix/raw.ml | 2 ++ src/unix/raw.mli | 67 ++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 61 insertions(+), 8 deletions(-) diff --git a/src/unix/raw.ml b/src/unix/raw.ml index f3f52643..d5e0970e 100644 --- a/src/unix/raw.ml +++ b/src/unix/raw.ml @@ -18,6 +18,8 @@ let really_write fd fd_offset buffer buffer_offset length = in aux fd_offset buffer_offset length +(* NOTE the return value is the number of bytes read; this is not completely obvious from + the code *) let really_read fd fd_offset length buffer = let rec aux fd_offset buffer_offset length = let r = Syscalls.pread ~fd ~fd_offset ~buffer ~buffer_offset ~length in diff --git a/src/unix/raw.mli b/src/unix/raw.mli index d4b806c9..54aa2fd5 100644 --- a/src/unix/raw.mli +++ b/src/unix/raw.mli @@ -1,32 +1,83 @@ -(** [Raw] wraps a file-descriptor with an file-format used internally by Index. - The format contains the following header fields: +(** [Raw] wraps a file-descriptor with an file-format used internally by Index; + now it is is also used by irmin-pack's pack store (and maybe others) + + The implementation uses a file descriptor, but uses space at the beginning + of the file for 4 fields: - {b offset}: a 64-bit integer, denoting the length of the file containing - valid data; - - {b version}: an 8-byte version string; - - {b generation}: a 64-bit integer denoting the generation number; + valid data; typically data is written to the end of a file, but not + considered "valid" until a later fsync completes; in this module, there is + no relation between the {!fsync} function, and the offset field - the + offset field is uninterpreted and it is up to users of this module to set + the offset appropriately + + - {b version}: an 8-byte version string; in this module we don't impose any + restrictions on this field, but elsewhere it is typically used to + distinguish different formats of the file data (see irmin-pack's [Version] + module - were the way to encode objects was changed from [`V1] to [`V2]; + [Version.set t s] will use exactly the first 8 bytes of the version + string; if the string is smaller there will be an error + + - {b generation}: a 64-bit integer denoting the generation number; like + [version], this is not interpreted any further in this module, but + elsewhere it may be used, for example, as a counter to indicate that other + RO processes need to reload data + - {b fan}: a 64-bit length field, followed by a string containing that many - bytes. *) + bytes; again, this is uninterpreted in this module, but is used by the + Index's fan; note that this field means that the header does not have a + fixed size + + How does the user know where the header ends and the file data begins? One + option is to call {!fstat} after initializing the header info. In fact, in + {!Index_unix} there is a separate computation of the header size: + [let header = eight ++ eight ++ eight ++ eight ++ +fan_size]; presumably + other users of this module do the same. *) open! Import type t -(** The type of [raw] file handles. *) +(** The type of [raw] file handles. The implementation is just a plain + {!Unix.file_descr}. *) val v : Unix.file_descr -> t -(** Construct a [raw] value from a file descriptor. *) +(** Construct a [raw] value from a file descriptor; this just wraps the file + descriptor; it does not read or write headers etc; for example, when called + on an empty file the [v] constructor will not read or write any data to the + file; it is up to the user to correctly initialize the headers. *) val unsafe_write : t -> off:int63 -> string -> int -> int -> unit +(** [unsafe_write t ~off s soff len] writes data from [s] at position [soff] to + the underlying file at position [off]; No account is made for the existence + of the header + - the user must make sure they write at offsets beyond the end of the header + data. *) + val unsafe_read : t -> off:int63 -> len:int -> bytes -> int +(** [unsafe_read t ~off ~len buf] reads upto [len] bytes of data into [buf] and + returns the number of bytes actually read. Again, no account is made for the + existence of the header - the user must make sure they read at offsets + beyond the end of the header data. *) + val fsync : t -> unit val close : t -> unit val fstat : t -> Unix.stats +(* FIXME rename this exception? *) exception Not_written +(** An exception that can be raised when {b reading} (not writing!) header + fields, in case the amount of bytes requested for a field is not the amount + of bytes actually read from file. This presumably happens only for files + that are not initialized correctly, i.e., they do not contain a full header. *) module Version : sig val get : t -> string + (** Return the version as a string of length 8 *) + val set : t -> string -> unit + (** [set t s] sets the version to [s]; uses first 8 bytes of [s]; error if + [s]'s length is less than 8 *) end module Offset : sig From ccdadc82a1de20ea1fda5ac89d048c64e5da8d32 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 13:25:47 +0100 Subject: [PATCH 10/22] Fix and complete the Raw documentation Describe the header layout with byte ranges and encoding, and the unchecked bounds of the unsafe functions. Correct a few points: the offset does not depend on fsync, Not_written is raised only when the file ends at or before the first byte read, Version.set does not check its argument, and files using Header_prefix have a different layout. --- src/unix/raw.ml | 5 +- src/unix/raw.mli | 164 ++++++++++++++++++++++++++++------------------- 2 files changed, 101 insertions(+), 68 deletions(-) diff --git a/src/unix/raw.ml b/src/unix/raw.ml index d5e0970e..6d31d097 100644 --- a/src/unix/raw.ml +++ b/src/unix/raw.ml @@ -18,8 +18,9 @@ let really_write fd fd_offset buffer buffer_offset length = in aux fd_offset buffer_offset length -(* NOTE the return value is the number of bytes read; this is not completely obvious from - the code *) +(* [really_read fd off len buf] reads [len] bytes at [off] into [buf], from + index 0, retrying after short reads. It returns the number of bytes read, + which is less than [len] only at the end of the file. *) let really_read fd fd_offset length buffer = let rec aux fd_offset buffer_offset length = let r = Syscalls.pread ~fd ~fd_offset ~buffer ~buffer_offset ~length in diff --git a/src/unix/raw.mli b/src/unix/raw.mli index 54aa2fd5..a0703079 100644 --- a/src/unix/raw.mli +++ b/src/unix/raw.mli @@ -1,127 +1,159 @@ -(** [Raw] wraps a file-descriptor with an file-format used internally by Index; - now it is is also used by irmin-pack's pack store (and maybe others) - - The implementation uses a file descriptor, but uses space at the beginning - of the file for 4 fields: - - - {b offset}: a 64-bit integer, denoting the length of the file containing - valid data; typically data is written to the end of a file, but not - considered "valid" until a later fsync completes; in this module, there is - no relation between the {!fsync} function, and the offset field - the - offset field is uninterpreted and it is up to users of this module to set - the offset appropriately - - - {b version}: an 8-byte version string; in this module we don't impose any - restrictions on this field, but elsewhere it is typically used to - distinguish different formats of the file data (see irmin-pack's [Version] - module - were the way to encode objects was changed from [`V1] to [`V2]; - [Version.set t s] will use exactly the first 8 bytes of the version - string; if the string is smaller there will be an error - - - {b generation}: a 64-bit integer denoting the generation number; like - [version], this is not interpreted any further in this module, but - elsewhere it may be used, for example, as a counter to indicate that other - RO processes need to reload data - - - {b fan}: a 64-bit length field, followed by a string containing that many - bytes; again, this is uninterpreted in this module, but is used by the - Index's fan; note that this field means that the header does not have a - fixed size - - How does the user know where the header ends and the file data begins? One - option is to call {!fstat} after initializing the header info. In fact, in - {!Index_unix} there is a separate computation of the header size: - [let header = eight ++ eight ++ eight ++ eight ++ -fan_size]; presumably - other users of this module do the same. *) +(** [Raw] wraps a file descriptor with the file format used by Index. + + The file starts with a header made of four fields, followed by the data: + + - {b offset} (bytes 0 to 7): the length of the valid data that follows the + header. This module does not interpret it: callers update it after writing + data, and {!fsync} does not write it; + - {b version} (bytes 8 to 15): an 8-byte string, not interpreted by this + module. Index writes ["00000001"] and refuses to open a file with another + version; + - {b generation} (bytes 16 to 23): not interpreted by this module. Index + increments it on every [clear] and [merge], and writes it in the headers + of the files it rewrites. Read-only instances compare the generation of + the log file with the one they know to decide whether to reload their + files; + - {b fan} (from byte 24): the length of the fan on bytes 24 to 31, followed + by the fan itself. Index stores the fan-out of its data file there, and an + empty fan in its log files. + + Offset, generation and the length of the fan are [int63] values encoded on 8 + bytes, in big-endian order. + + Because of the fan, the header has no fixed size: it is 32 bytes plus the + length of the fan. This module does not compute it: callers do, as + [Index_unix] does. + + Files written with {!Header_prefix} have a different layout: their header is + made of the offset and the version only, and their data starts at byte 16. + + The functions below that read the header raise {!Not_written} when the file + ends at or before the first byte they read. *) open! Import type t -(** The type of [raw] file handles. The implementation is just a plain - {!Unix.file_descr}. *) +(** The type of [raw] file handles. *) val v : Unix.file_descr -> t -(** Construct a [raw] value from a file descriptor; this just wraps the file - descriptor; it does not read or write headers etc; for example, when called - on an empty file the [v] constructor will not read or write any data to the - file; it is up to the user to correctly initialize the headers. *) +(** [v fd] is a [raw] file handle for [fd]. It does not read or write anything: + the caller must initialise the header of a new file. *) val unsafe_write : t -> off:int63 -> string -> int -> int -> unit -(** [unsafe_write t ~off s soff len] writes data from [s] at position [soff] to - the underlying file at position [off]; No account is made for the existence - of the header - - the user must make sure they write at offsets beyond the end of the header - data. *) +(** [unsafe_write t ~off s soff len] writes the [len] bytes of [s] starting at + [soff] to the file, at offset [off]. Offsets are absolute: the caller must + write past the header. + + The bounds are not checked: [soff] and [len] must designate a valid + substring of [s]. + + @raise Unix.Unix_error if a system call fails. *) val unsafe_read : t -> off:int63 -> len:int -> bytes -> int -(** [unsafe_read t ~off ~len buf] reads upto [len] bytes of data into [buf] and - returns the number of bytes actually read. Again, no account is made for the - existence of the header - the user must make sure they read at offsets - beyond the end of the header data. *) +(** [unsafe_read t ~off ~len buf] reads at most [len] bytes from the file, at + offset [off], into [buf] starting at index [0]. It returns the number of + bytes read, which is less than [len] only at the end of the file. Offsets + are absolute: the caller must read past the header. + + The bounds are not checked: [len] must be between [0] and the length of + [buf]. + + @raise Unix.Unix_error if a system call fails. *) val fsync : t -> unit +(** [fsync t] flushes the file to disk with [Unix.fsync]. *) + val close : t -> unit +(** [close t] closes the underlying file descriptor. *) + val fstat : t -> Unix.stats +(** [fstat t] is the result of [Unix.fstat] on the underlying file descriptor. + Its [st_size] includes the header. *) -(* FIXME rename this exception? *) exception Not_written -(** An exception that can be raised when {b reading} (not writing!) header - fields, in case the amount of bytes requested for a field is not the amount - of bytes actually read from file. This presumably happens only for files - that are not initialized correctly, i.e., they do not contain a full header. *) +(** The exception raised when reading the header of a file that ends at or + before the first byte to read, for instance an empty file. A file that ends + after this byte but before the end of what is read raises [Assert_failure] + instead. *) module Version : sig val get : t -> string - (** Return the version as a string of length 8 *) + (** [get t] is the version, a string of 8 bytes. *) val set : t -> string -> unit - (** [set t s] sets the version to [s]; uses first 8 bytes of [s]; error if - [s]'s length is less than 8 *) + (** [set t s] writes the first 8 bytes of [s] as the version. [s] must be at + least 8 bytes long: this is not checked, and the bytes written after the + end of a shorter string are unspecified. *) end +(** The offset, in bytes 0 to 7. *) module Offset : sig val get : t -> int63 val set : t -> int63 -> unit end +(** The generation, in bytes 16 to 23. *) module Generation : sig val get : t -> int63 val set : t -> int63 -> unit end +(** The fan, from byte 24. *) module Fan : sig val get : t -> string + (** [get t] reads the length of the fan, then the fan itself. *) + val set : t -> string -> unit + (** [set t s] writes the length of [s], then [s]. The data follows the fan, so + [s] must have the length reserved with {!set_size}. *) + val get_size : t -> int63 + (** [get_size t] is the length of the fan. *) + val set_size : t -> int63 -> unit + (** [set_size t n] writes the length of the fan only. It reserves [n] bytes + for a fan written later with {!set}. *) end +(** The first three fields of the header, read or written with a single system + call. The fan is not read nor written. *) module Header : sig type raw type t = { - offset : int63; (** The length of the file containing valid data *) - version : string; (** Format version *) - generation : int63; (** Generation number *) + offset : int63; (** The length of the valid data after the header. *) + version : string; (** The version, a string of 8 bytes. *) + generation : int63; (** The generation. *) } val get : raw -> t + (** [get t] reads bytes 0 to 23. *) + val set : raw -> t -> unit + (** [set t h] writes bytes 0 to 23. + + @raise Assert_failure if [h.version] is not 8 bytes long. *) end with type raw := t -(** Functions for interacting with the header format {i without} the generation - number, provided for use in [irmin-pack]. *) +(** The header of the files that only have an offset and a version, and whose + data starts at byte 16, as in the legacy stores of irmin-pack up to 3.8. + {!Generation}, {!Fan} and {!Header} must not be used on such files: the + fields they access overlap the data. *) module Header_prefix : sig type raw type t = { - offset : int63; (** The length of the file containing valid data *) - version : string; (** Format version *) + offset : int63; (** The length of the valid data after the header. *) + version : string; (** The version, a string of 8 bytes. *) } val get : raw -> t + (** [get t] reads bytes 0 to 15. *) + val set : raw -> t -> unit + (** [set t h] writes bytes 0 to 15. + + @raise Assert_failure if [h.version] is not 8 bytes long. *) end with type raw := t From 7b63b4a5c2a60725080a9c6fea7643d6d0053fea Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 13:48:25 +0100 Subject: [PATCH 11/22] Give each instance its own prefetch buffer Io_array used one prefetch buffer for all the instances of an Index.Make application. Finds on two instances are guarded by distinct locks, so, from two threads or domains, they could overwrite each other's prefetched entries and miss bindings. --- src/index.ml | 18 +++++++--- src/io_array.ml | 62 ++++++++++++++++++++++------------- src/io_array.mli | 11 ++++++- test/unix/concurrent_find.ml | 58 ++++++++++++++++++++++++++++++++ test/unix/concurrent_find.mli | 1 + test/unix/io_array.ml | 2 +- test/unix/main.ml | 1 + 7 files changed, 123 insertions(+), 30 deletions(-) create mode 100644 test/unix/concurrent_find.ml create mode 100644 test/unix/concurrent_find.mli diff --git a/src/index.ml b/src/index.ml index 806b8483..a8a12408 100644 --- a/src/index.ml +++ b/src/index.ml @@ -149,6 +149,8 @@ struct header of [io]. *) } + module IOArray = Io_array.Make (IO) (Entry) + type instance = { config : config; root : string; (** The root location of the index *) @@ -169,6 +171,9 @@ struct mutable open_instances : int; (** The number of open instances that are shared through the [Cache.t]. *) mutable lru : Lru.t; + prefetch_buffer : IOArray.prefetch_buffer; + (** The buffer in which [find] prefetches entries of [index], guarded by + [rename_lock]. *) writer_lock : IO.Lock.t option; (** A lock that prevents multiple RW instances to be open at the same time. *) @@ -417,8 +422,6 @@ struct (** {1 Find and Mem}*) - module IOArray = Io_array.Make (IO) (Entry) - module Search = Search.Make (Entry) (IOArray) (struct @@ -445,14 +448,16 @@ struct Int63.of_float rounded end) - let interpolation_search index key = + let interpolation_search prefetch_buffer index key = let hashed_key = K.hash key in let low_bytes, high_bytes = Fan.search index.fan_out hashed_key in let low, high = Int63. (div low_bytes Entry.encoded_sizeL, div high_bytes Entry.encoded_sizeL) in - Search.interpolation_search (IOArray.v index.io) key ~low ~high + Search.interpolation_search + (IOArray.v prefetch_buffer index.io) + key ~low ~high (** Finds the value associated to [key] in [t]. In order, checks in [log_async] (in memory), then [log] (in memory), then [index] (on disk). *) @@ -471,7 +476,9 @@ struct in let find_log () = find_if_exists ~name:"log" ~find:Log_file.find t.log in let find_index () = - find_if_exists ~name:"index" ~find:interpolation_search t.index + find_if_exists ~name:"index" + ~find:(interpolation_search t.prefetch_buffer) + t.index in Semaphore.with_acquire "find_instance" t.rename_lock @@ fun () -> match Lru.find t.lru key with @@ -617,6 +624,7 @@ struct root; index; lru = Lru.create lru_size; + prefetch_buffer = IOArray.prefetch_buffer (); open_instances = 1; merge_lock = Semaphore.make true; rename_lock = Semaphore.make true; diff --git a/src/io_array.ml b/src/io_array.ml index 1794fd5f..3b75e608 100644 --- a/src/io_array.ml +++ b/src/io_array.ml @@ -29,7 +29,16 @@ module type S = sig type io - val v : io -> t + type prefetch_buffer + (** The buffer in which an array prefetches its entries. *) + + val prefetch_buffer : unit -> prefetch_buffer + (** [prefetch_buffer ()] is a fresh prefetch buffer, of 32 KiB. *) + + val v : prefetch_buffer -> io -> t + (** [v buf io] is the array of the entries of [io]. It prefetches entries in + [buf], which can be reused by successive arrays, but not by arrays used + concurrently. *) end module Make (IO : Io.S) (Elt : ELT) : @@ -42,10 +51,26 @@ module Make (IO : Io.S) (Elt : ELT) : type io = IO.t type elt = Elt.t - type buffer = { buf : bytes; low_off : int63; high_off : int63 } - type t = { io : IO.t; mutable buffer : buffer option } + type prefetch_buffer = bytes + + type window = { low_off : int63; high_off : int63 } + (** The region of the file held in the prefetch buffer. *) - let v io = { io; buffer = None } + type t = { + io : IO.t; + prefetch_buffer : prefetch_buffer; + mutable window : window option; + } + + let max_buffer_size = + (* The prefetched area should not exceed 4096 in most cases, thanks to the + fan out. However, if the hash function is not well distributed, some + exceptions might happen where the prefetched area actually exceeds 4096. + As long as this excess is reasonable (x8), we still want to prefetch. *) + 8 * 4096 + + let prefetch_buffer () = Bytes.create max_buffer_size + let v prefetch_buffer io = { io; prefetch_buffer; window = None } let get_entry_from_io io off = let buf = Bytes.create Elt.encoded_size in @@ -53,42 +78,33 @@ module Make (IO : Io.S) (Elt : ELT) : assert (n = Elt.encoded_size); Elt.decode (Bytes.unsafe_to_string buf) 0 - let get_entry_from_buffer buf off = - let buf_off = Int63.(to_int_exn (off - buf.low_off)) in - assert (buf_off <= Bytes.length buf.buf); - Elt.decode (Bytes.unsafe_to_string buf.buf) buf_off + let get_entry_from_buffer t window off = + let buf_off = Int63.(to_int_exn (off - window.low_off)) in + assert (buf_off <= Bytes.length t.prefetch_buffer); + Elt.decode (Bytes.unsafe_to_string t.prefetch_buffer) buf_off let is_in_buffer t off = - match t.buffer with + match t.window with | None -> false | Some b -> Int63.compare off b.low_off >= 0 && Int63.compare off b.high_off <= 0 let get t i = let off = Int63.(i * Elt.encoded_sizeL) in - match t.buffer with + match t.window with | Some b when is_in_buffer t off -> ( - try get_entry_from_buffer b off with _ -> assert false) + try get_entry_from_buffer t b off with _ -> assert false) | _ -> get_entry_from_io t.io off let length t = Int63.div (IO.offset t.io) Elt.encoded_sizeL - let max_buffer_size = - (* The prefetched area should not exceed 4096 in most cases, thanks to the - fan out. However, if the hash function is not well distributed, some - exceptions might happen where the prefetched area actually exceeds 4096. - As long as this excess is reasonable (x8), we still want to prefetch. *) - 8 * 4096 - - let buf = Bytes.create max_buffer_size - let set_buffer t ~low ~high = let range = Elt.encoded_size * (1 + Int63.(to_int_exn (high - low))) in let low_off = Int63.mul low Elt.encoded_sizeL in let high_off = Int63.mul high Elt.encoded_sizeL in - let n = IO.read t.io ~off:low_off ~len:range buf in + let n = IO.read t.io ~off:low_off ~len:range t.prefetch_buffer in assert (n = range); - t.buffer <- Some { buf; low_off; high_off } + t.window <- Some { low_off; high_off } let pre_fetch t ~low ~high = let range = Elt.encoded_size * (1 + Int63.(to_int_exn (high - low))) in @@ -101,7 +117,7 @@ module Make (IO : Io.S) (Elt : ELT) : m "Requested pre-fetch [%a, %a] is larger than %d" Int63.pp low Int63.pp high max_buffer_size) else - match t.buffer with + match t.window with | Some b -> let low_buf, high_buf = Int63. diff --git a/src/io_array.mli b/src/io_array.mli index 3ccc74b9..16738875 100644 --- a/src/io_array.mli +++ b/src/io_array.mli @@ -29,7 +29,16 @@ module type S = sig type io - val v : io -> t + type prefetch_buffer + (** The buffer in which an array prefetches its entries. *) + + val prefetch_buffer : unit -> prefetch_buffer + (** [prefetch_buffer ()] is a fresh prefetch buffer, of 32 KiB. *) + + val v : prefetch_buffer -> io -> t + (** [v buf io] is the array of the entries of [io]. It prefetches entries in + [buf], which can be reused by successive arrays, but not by arrays used + concurrently. *) end (** Takes an IO instance and wraps it in an Array interface with support for diff --git a/test/unix/concurrent_find.ml b/test/unix/concurrent_find.ml new file mode 100644 index 00000000..96f1bd07 --- /dev/null +++ b/test/unix/concurrent_find.ml @@ -0,0 +1,58 @@ +(* Regression test for concurrent finds on distinct instances of the same + [Index.Make] application. Each find prefetches a region of the data file in + a buffer; this buffer must not be shared between instances, which are + protected by distinct locks. *) + +open Common + +let root = Filename.concat "_tests" "unix.concurrent_find" +let nb_bindings = 2_000 +let nb_rounds = 2 + +(* A merged instance holding [bindings], so that [find] reads the data file. + The LRU is disabled so that every [find] reaches it. *) +let with_merged_instance name bindings f = + let t = + Index.v ~fresh:true ~lru_size:0 ~log_size:(2 * nb_bindings) + (Filename.concat root name) + in + Fun.protect + ~finally:(fun () -> Index.close t) + (fun () -> + List.iter (fun (k, v) -> Index.replace t k v) bindings; + Index.try_merge_aux ~force:true t |> Index.await |> check_completed; + f t) + +(* The number of [bindings] that [find] misses or gets wrong in [t]. *) +let find_errors t bindings = + let errors = ref 0 in + for _ = 1 to nb_rounds do + List.iter + (fun (k, v) -> + match Index.find t k with + | v' when String.equal v v' -> () + | _ | (exception Not_found) -> incr errors) + bindings + done; + !errors + +(* Both instances hold the same keys with different values, so that reading + the entries of the other instance gives wrong values, not only misses. *) +let two_instances_two_domains () = + let keys = List.init nb_bindings (fun _ -> Key.v ()) in + let bindings1 = List.map (fun k -> (k, Value.v ())) keys in + let bindings2 = List.map (fun k -> (k, Value.v ())) keys in + with_merged_instance "a" bindings1 @@ fun t1 -> + with_merged_instance "b" bindings2 @@ fun t2 -> + let d = Domain.spawn (fun () -> find_errors t2 bindings2) in + let errors2 = ref 0 in + let errors1 = + Fun.protect + ~finally:(fun () -> errors2 := Domain.join d) + (fun () -> find_errors t1 bindings1) + in + Alcotest.(check int) "errors on the first instance" 0 errors1; + Alcotest.(check int) "errors on the second instance" 0 !errors2 + +let tests = + [ ("two instances, two domains", `Quick, two_instances_two_domains) ] diff --git a/test/unix/concurrent_find.mli b/test/unix/concurrent_find.mli new file mode 100644 index 00000000..d38ba9a9 --- /dev/null +++ b/test/unix/concurrent_find.mli @@ -0,0 +1 @@ +val tests : unit Alcotest.test_case list diff --git a/test/unix/io_array.ml b/test/unix/io_array.ml index e79e670f..86d54c1e 100644 --- a/test/unix/io_array.ml +++ b/test/unix/io_array.ml @@ -42,7 +42,7 @@ let populate_random ~size io = loop (e :: acc) (n - 1) in let mem_arr = Array.of_list (List.rev (loop [] size)) in - let io_arr = IOArray.v io in + let io_arr = IOArray.v (IOArray.prefetch_buffer ()) io in IO.flush io; (mem_arr, io_arr) diff --git a/test/unix/main.ml b/test/unix/main.ml index 18f5019c..758755fe 100644 --- a/test/unix/main.ml +++ b/test/unix/main.ml @@ -1110,4 +1110,5 @@ let () = ("flush_callback", Flush_callback.tests); ("throttle", Throttle.tests); ("zero-size values", Zero_size_value.tests); + ("concurrent find", Concurrent_find.tests); ] From b4202348290bb71e5bd82a0148ce64e49c7a9176 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 13:48:25 +0100 Subject: [PATCH 12/22] Document that decoders must not keep a reference to their input --- src/data.ml | 10 +++++++++- src/log_file.ml | 8 +++----- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/src/data.ml b/src/data.ml index b35f9909..b2056203 100644 --- a/src/data.ml +++ b/src/data.ml @@ -31,7 +31,11 @@ module type Key = sig val decode : string -> int -> t (** [decode s off] is the decoded form of the encoded value at the offset - [off] of string [s]. Must satisfy [decode (encode t) 0 = t]. *) + [off] of string [s]. Must satisfy [decode (encode t) 0 = t]. + + [s] may be a buffer that is overwritten later, so the result must not keep + a reference to [s], except when [off = 0] and [s] holds exactly one key: + [Repr.decode_bin] returns [s] itself in that case. *) end module type Value = sig @@ -39,7 +43,11 @@ module type Value = sig val encode : t -> string val encoded_size : int + val decode : string -> int -> t + (** [decode s off] is the decoded form of the encoded value at the offset + [off] of string [s]. [s] may be a buffer that is overwritten later, so the + result must not keep a reference to [s]. *) end module Entry = struct diff --git a/src/log_file.ml b/src/log_file.ml index 4fc231a7..cf46e5ac 100644 --- a/src/log_file.ml +++ b/src/log_file.ml @@ -79,11 +79,9 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) = struct assert (r = Entry.encoded_size); let s = if Value.encoded_size = 0 then - (* Quickfix for a situation where [Key.decode] kept a pointer to [s] - when [Value.encoded_size = 0]. This led to a bug where some entries - dissapeared post-merge. - - A proper solution will be implemented in the future. *) + (* The scratch buffer then holds exactly one key, which [Key.decode] + may return without copying it (see [Data.Key.decode]). The entries + are kept, for instance by [to_sorted_seq], so copy the buffer. *) Bytes.to_string scratch.buffer else Bytes.unsafe_to_string scratch.buffer in From af702d7fdd6cbdb42c9f9f6b6118dfdbdcc29aec Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 17:00:21 +0100 Subject: [PATCH 13/22] Raw: raise Not_written on a truncated header A header field that ended in the middle failed an assertion, or was silently decoded from uninitialised bytes with -noassert. A read-only instance now handles it like a missing header. --- src/unix/raw.ml | 26 ++++++++----------- src/unix/raw.mli | 9 +++---- test/unix/main.ml | 1 + test/unix/raw_header.ml | 54 ++++++++++++++++++++++++++++++++++++++++ test/unix/raw_header.mli | 1 + 5 files changed, 70 insertions(+), 21 deletions(-) create mode 100644 test/unix/raw_header.ml create mode 100644 test/unix/raw_header.mli diff --git a/src/unix/raw.ml b/src/unix/raw.ml index 6d31d097..beb80446 100644 --- a/src/unix/raw.ml +++ b/src/unix/raw.ml @@ -56,15 +56,9 @@ let decode_int63 buf = Int63.decode ~off:0 buf exception Not_written -let assert_read ~len n = - if n = 0 && n <> len then raise Not_written; - assert ( - if Int.equal n len then true - else ( - Printf.eprintf "Attempted to read %d bytes, but got %d bytes instead!\n%!" - len n; - false)) -[@@inline always] +(* A short read means that the file ends before the end of the field: the + header is missing or was only partly written. *) +let check_read ~len n = if n < len then raise Not_written [@@inline always] module Offset = struct let off = Int63.zero @@ -74,7 +68,7 @@ module Offset = struct let len = 8 in let buf = Bytes.create len in let n = unsafe_read t ~off ~len buf in - assert_read ~len n; + check_read ~len n; decode_int63 (Bytes.unsafe_to_string buf) end @@ -85,7 +79,7 @@ module Version = struct let len = 8 in let buf = Bytes.create len in let n = unsafe_read t ~off ~len buf in - assert_read ~len n; + check_read ~len n; Bytes.unsafe_to_string buf let set t v = unsafe_write t ~off v 0 8 @@ -98,7 +92,7 @@ module Generation = struct let len = 8 in let buf = Bytes.create len in let n = unsafe_read t ~off ~len buf in - assert_read ~len n; + check_read ~len n; decode_int63 (Bytes.unsafe_to_string buf) let set t gen = unsafe_write t ~off (encode_int63 gen) 0 8 @@ -117,7 +111,7 @@ module Fan = struct let len = 8 in let size_buf = Bytes.create len in let n = unsafe_read t ~off ~len size_buf in - assert_read ~len n; + check_read ~len n; decode_int63 (Bytes.unsafe_to_string size_buf) let set_size t size = @@ -128,7 +122,7 @@ module Fan = struct let size = Int63.to_int (get_size t) in let buf = Bytes.create size in let n = unsafe_read t ~off:(off ++ Int63.of_int 8) ~len:size buf in - assert_read ~len:size n; + check_read ~len:size n; Bytes.unsafe_to_string buf end @@ -148,7 +142,7 @@ module Header = struct let get t = let header = Bytes.create total_header_length in let n = unsafe_read t ~off:Int63.zero ~len:total_header_length header in - assert_read ~len:total_header_length n; + check_read ~len:total_header_length n; let offset = read_word header 0 |> decode_int63 in let version = read_word header 8 in let generation = read_word header 16 |> decode_int63 in @@ -180,7 +174,7 @@ module Header_prefix = struct let get t = let header = Bytes.create total_header_length in let n = unsafe_read t ~off:Int63.zero ~len:total_header_length header in - assert_read ~len:total_header_length n; + check_read ~len:total_header_length n; let offset = read_word header 0 |> decode_int63 in let version = read_word header 8 in { offset; version } diff --git a/src/unix/raw.mli b/src/unix/raw.mli index a0703079..3615f5af 100644 --- a/src/unix/raw.mli +++ b/src/unix/raw.mli @@ -28,7 +28,7 @@ made of the offset and the version only, and their data starts at byte 16. The functions below that read the header raise {!Not_written} when the file - ends at or before the first byte they read. *) + ends before the last byte they read. *) open! Import @@ -71,10 +71,9 @@ val fstat : t -> Unix.stats Its [st_size] includes the header. *) exception Not_written -(** The exception raised when reading the header of a file that ends at or - before the first byte to read, for instance an empty file. A file that ends - after this byte but before the end of what is read raises [Assert_failure] - instead. *) +(** The exception raised when reading the header of a file that ends before the + last byte to read: the header is missing, as in an empty file, or was only + partly written. *) module Version : sig val get : t -> string diff --git a/test/unix/main.ml b/test/unix/main.ml index 758755fe..89792006 100644 --- a/test/unix/main.ml +++ b/test/unix/main.ml @@ -1111,4 +1111,5 @@ let () = ("throttle", Throttle.tests); ("zero-size values", Zero_size_value.tests); ("concurrent find", Concurrent_find.tests); + ("raw header", Raw_header.tests); ] diff --git a/test/unix/raw_header.ml b/test/unix/raw_header.ml new file mode 100644 index 00000000..ce6c24f8 --- /dev/null +++ b/test/unix/raw_header.ml @@ -0,0 +1,54 @@ +module Int63 = Optint.Int63 +module Raw = Index_unix.Private.Raw + +(* [with_file contents f] calls [f] on a [Raw.t] for a fresh file that holds + [contents]. *) +let with_file contents f = + let path = Filename.temp_file "index-raw" "" in + let fd = Unix.openfile path Unix.[ O_RDWR; O_CLOEXEC ] 0o600 in + Fun.protect + ~finally:(fun () -> + Unix.close fd; + Sys.remove path) + (fun () -> + let raw = Raw.v fd in + if contents <> "" then + Raw.unsafe_write raw ~off:Int63.zero contents 0 (String.length contents); + f raw) + +let check_not_written name f = + Alcotest.check_raises name Raw.Not_written (fun () -> ignore (f ())) + +(** Reading the header of a file that is empty, or that ends in the middle of + the field to read, raises [Not_written]. *) +let truncated_header () = + with_file "" (fun raw -> + check_not_written "empty file, Header.get" (fun () -> Raw.Header.get raw); + check_not_written "empty file, Offset.get" (fun () -> Raw.Offset.get raw)); + with_file (String.make 10 '\000') (fun raw -> + check_not_written "10-byte file, Header.get" (fun () -> + Raw.Header.get raw); + check_not_written "10-byte file, Version.get" (fun () -> + Raw.Version.get raw); + check_not_written "10-byte file, Header_prefix.get" (fun () -> + Raw.Header_prefix.get raw); + Alcotest.(check int) + "10-byte file, the offset is complete" 0 + (Int63.to_int (Raw.Offset.get raw))); + with_file (String.make 28 '\000') (fun raw -> + check_not_written "28-byte file, Fan.get_size" (fun () -> + Raw.Fan.get_size raw)) + +(** The fan is checked against its recorded length, and an empty fan reads fine. *) +let fan () = + with_file (String.make 32 '\000') (fun raw -> + Alcotest.(check string) "empty fan" "" (Raw.Fan.get raw); + Raw.Fan.set_size raw (Int63.of_int 16); + check_not_written "fan shorter than its length" (fun () -> + Raw.Fan.get raw); + Raw.Fan.set raw (String.make 16 'f'); + Alcotest.(check string) + "complete fan" (String.make 16 'f') (Raw.Fan.get raw)) + +let tests = + [ ("truncated header", `Quick, truncated_header); ("fan", `Quick, fan) ] diff --git a/test/unix/raw_header.mli b/test/unix/raw_header.mli new file mode 100644 index 00000000..d38ba9a9 --- /dev/null +++ b/test/unix/raw_header.mli @@ -0,0 +1 @@ +val tests : unit Alcotest.test_case list From f70c86c56912658b8100933f87eabd904e0e041b Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 17:00:49 +0100 Subject: [PATCH 14/22] Raw: reject versions that are not 8 bytes long Version.set read past the end of a shorter string, as pwrite does not check bounds. Header.set and Header_prefix.set only checked it with an assertion. All three now raise Invalid_argument. --- src/unix/raw.ml | 12 +++++++++--- src/unix/raw.mli | 10 +++++----- test/unix/raw_header.ml | 24 +++++++++++++++++++++++- 3 files changed, 37 insertions(+), 9 deletions(-) diff --git a/src/unix/raw.ml b/src/unix/raw.ml index beb80446..e6292391 100644 --- a/src/unix/raw.ml +++ b/src/unix/raw.ml @@ -60,6 +60,10 @@ exception Not_written header is missing or was only partly written. *) let check_read ~len n = if n < len then raise Not_written [@@inline always] +let check_version_length ~fn v = + if String.length v <> 8 then + Fmt.invalid_arg "Raw.%s: the version %S is not 8 bytes long" fn v + module Offset = struct let off = Int63.zero let set t n = unsafe_write t ~off (encode_int63 n) 0 8 @@ -82,7 +86,9 @@ module Version = struct check_read ~len n; Bytes.unsafe_to_string buf - let set t v = unsafe_write t ~off v 0 8 + let set t v = + check_version_length ~fn:"Version.set" v; + unsafe_write t ~off v 0 8 end module Generation = struct @@ -149,7 +155,7 @@ module Header = struct { offset; version; generation } let set t { offset; version; generation } = - assert (String.length version = 8); + check_version_length ~fn:"Header.set" version; let b = Bytes.create total_header_length in Bytes.blit_string (encode_int63 offset) 0 b 0 8; Bytes.blit_string version 0 b 8 8; @@ -180,7 +186,7 @@ module Header_prefix = struct { offset; version } let set t { offset; version } = - assert (String.length version = 8); + check_version_length ~fn:"Header_prefix.set" version; let b = Bytes.create total_header_length in Bytes.blit_string (encode_int63 offset) 0 b 0 8; Bytes.blit_string version 0 b 8 8; diff --git a/src/unix/raw.mli b/src/unix/raw.mli index 3615f5af..16a54441 100644 --- a/src/unix/raw.mli +++ b/src/unix/raw.mli @@ -80,9 +80,9 @@ module Version : sig (** [get t] is the version, a string of 8 bytes. *) val set : t -> string -> unit - (** [set t s] writes the first 8 bytes of [s] as the version. [s] must be at - least 8 bytes long: this is not checked, and the bytes written after the - end of a shorter string are unspecified. *) + (** [set t s] writes [s] as the version. + + @raise Invalid_argument if [s] is not 8 bytes long. *) end (** The offset, in bytes 0 to 7. *) @@ -131,7 +131,7 @@ module Header : sig val set : raw -> t -> unit (** [set t h] writes bytes 0 to 23. - @raise Assert_failure if [h.version] is not 8 bytes long. *) + @raise Invalid_argument if [h.version] is not 8 bytes long. *) end with type raw := t @@ -153,6 +153,6 @@ module Header_prefix : sig val set : raw -> t -> unit (** [set t h] writes bytes 0 to 15. - @raise Assert_failure if [h.version] is not 8 bytes long. *) + @raise Invalid_argument if [h.version] is not 8 bytes long. *) end with type raw := t diff --git a/test/unix/raw_header.ml b/test/unix/raw_header.ml index ce6c24f8..0638af31 100644 --- a/test/unix/raw_header.ml +++ b/test/unix/raw_header.ml @@ -50,5 +50,27 @@ let fan () = Alcotest.(check string) "complete fan" (String.make 16 'f') (Raw.Fan.get raw)) +(** Writing a version that is not 8 bytes long raises [Invalid_argument]. *) +let version_length () = + with_file (String.make 32 '\000') (fun raw -> + let invalid name f = + match f () with + | () -> Alcotest.failf "%s: Invalid_argument expected" name + | exception Invalid_argument _ -> () + in + invalid "Version.set" (fun () -> Raw.Version.set raw "v1"); + invalid "Header.set" (fun () -> + Raw.Header.set raw + { offset = Int63.zero; version = "v1"; generation = Int63.zero }); + invalid "Header_prefix.set" (fun () -> + Raw.Header_prefix.set raw + { offset = Int63.zero; version = "000000001" }); + Raw.Version.set raw "00000001"; + Alcotest.(check string) "version" "00000001" (Raw.Version.get raw)) + let tests = - [ ("truncated header", `Quick, truncated_header); ("fan", `Quick, fan) ] + [ + ("truncated header", `Quick, truncated_header); + ("fan", `Quick, fan); + ("version length", `Quick, version_length); + ] From 98c811e0e219458162eb8eb267263fe83fae5e44 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 17:01:03 +0100 Subject: [PATCH 15/22] Raw: fail when pwrite writes nothing really_write stopped silently, leaving the rest of the buffer unwritten, while the caller then updated the offset as if it was. --- src/unix/raw.ml | 5 ++++- src/unix/raw.mli | 3 ++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/src/unix/raw.ml b/src/unix/raw.ml index e6292391..18547ca6 100644 --- a/src/unix/raw.ml +++ b/src/unix/raw.ml @@ -10,7 +10,10 @@ let v fd = { fd } let really_write fd fd_offset buffer buffer_offset length = let rec aux fd_offset buffer_offset length = let w = Syscalls.pwrite ~fd ~fd_offset ~buffer ~buffer_offset ~length in - if w = 0 || w = length then () + if w = length then () + else if w = 0 then + Fmt.failwith + "Raw.unsafe_write: %d bytes left to write, but pwrite wrote none" length else (aux [@tailcall]) (fd_offset ++ Int63.of_int w) diff --git a/src/unix/raw.mli b/src/unix/raw.mli index 16a54441..8748afb1 100644 --- a/src/unix/raw.mli +++ b/src/unix/raw.mli @@ -47,7 +47,8 @@ val unsafe_write : t -> off:int63 -> string -> int -> int -> unit The bounds are not checked: [soff] and [len] must designate a valid substring of [s]. - @raise Unix.Unix_error if a system call fails. *) + @raise Unix.Unix_error if a system call fails. + @raise Failure if a system call writes nothing while bytes remain. *) val unsafe_read : t -> off:int63 -> len:int -> bytes -> int (** [unsafe_read t ~off ~len buf] reads at most [len] bytes from the file, at From 7d732bb41415fd07e24dc4090a6b5ef12493cbb5 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 17:01:11 +0100 Subject: [PATCH 16/22] Io_array: let decoding errors propagate They were turned into an Assert_failure that hid the original exception. --- src/io_array.ml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/io_array.ml b/src/io_array.ml index 3b75e608..6b5c4a7b 100644 --- a/src/io_array.ml +++ b/src/io_array.ml @@ -92,8 +92,7 @@ module Make (IO : Io.S) (Elt : ELT) : let get t i = let off = Int63.(i * Elt.encoded_sizeL) in match t.window with - | Some b when is_in_buffer t off -> ( - try get_entry_from_buffer t b off with _ -> assert false) + | Some b when is_in_buffer t off -> get_entry_from_buffer t b off | _ -> get_entry_from_io t.io off let length t = Int63.div (IO.offset t.io) Elt.encoded_sizeL From d52923c8a532dda50a3c149328f914999852fd66 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 17:01:37 +0100 Subject: [PATCH 17/22] Log_file: copy zero-size entries only when they are kept find only compares the key, so it does not need the copy. --- src/log_file.ml | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/src/log_file.ml b/src/log_file.ml index cf46e5ac..75e358b6 100644 --- a/src/log_file.ml +++ b/src/log_file.ml @@ -73,15 +73,17 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) = struct assert (r = len); fst (Entry.decode_key (Bytes.unsafe_to_string scratch.buffer) 0) - let entry_of_offset t (scratch : Scratch.t) off = + (* [entry_of_offset ~kept t scratch off] is the entry at [off]. [kept] tells + whether the caller may keep its key after [scratch] is reused. *) + let entry_of_offset ~kept t (scratch : Scratch.t) off = let len = Entry.encoded_size in let r = IO.read t.io ~off ~len scratch.buffer in assert (r = Entry.encoded_size); let s = - if Value.encoded_size = 0 then + if kept && Value.encoded_size = 0 then (* The scratch buffer then holds exactly one key, which [Key.decode] - may return without copying it (see [Data.Key.decode]). The entries - are kept, for instance by [to_sorted_seq], so copy the buffer. *) + may return without copying it (see [Data.Key.decode]): copy the + buffer so that the key outlives it. *) Bytes.to_string scratch.buffer else Bytes.unsafe_to_string scratch.buffer in @@ -191,8 +193,8 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) = struct let scratch = Scratch.create () in Small_list.find_map bucket ~f:(fun offset -> (* We expect the keys to match most of the time, so we decode the - value at the same time. *) - let entry = entry_of_offset t scratch offset in + value at the same time. Only the value is kept. *) + let entry = entry_of_offset ~kept:false t scratch offset in match Key.equal key entry.key with | false -> None | true -> Some entry.value) @@ -204,14 +206,14 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) = struct let scratch = Scratch.create () in ArrayLabels.fold_left t.hashtbl ~init ~f:(fun acc bucket -> Small_list.fold_left bucket ~init:acc ~f:(fun acc offset -> - let entry = entry_of_offset t scratch offset in + let entry = entry_of_offset ~kept:true t scratch offset in f acc entry)) let iter t ~f = let scratch = Scratch.create () in ArrayLabels.iter t.hashtbl ~f:(fun bucket -> Small_list.iter bucket ~f:(fun offset -> - f (entry_of_offset t scratch offset))) + f (entry_of_offset ~kept:true t scratch offset))) let to_sorted_seq t = let scratch = Scratch.create () in @@ -219,7 +221,7 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) = struct |> Seq.flat_map (fun bucket -> let arr = Small_list.to_array bucket - |> Array.map (fun off -> entry_of_offset t scratch off) + |> Array.map (fun off -> entry_of_offset ~kept:true t scratch off) in Array.sort Entry.compare arr; Array.to_seq arr) From 563abd0fbe331612bcc9de10b1169da24906fe12 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 17:02:08 +0100 Subject: [PATCH 18/22] Test: release the merge if the log_async sync fails Otherwise the merge thread stays blocked in its hook. --- test/unix/main.ml | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/test/unix/main.ml b/test/unix/main.ml index 89792006..acab7250 100644 --- a/test/unix/main.ml +++ b/test/unix/main.ml @@ -631,11 +631,15 @@ module Readonly = struct Index.check_binding ro k v1; let t = Index.try_merge_aux ~force:true ~hook:merge_hook rw in Semaphore.acquire merge_started; - Index.replace rw k v2; - Index.flush rw; - Index.sync ro; - let found = Index.find ro k in - Semaphore.release merge; + let found = + Fun.protect + ~finally:(fun () -> Semaphore.release merge) + (fun () -> + Index.replace rw k v2; + Index.flush rw; + Index.sync ro; + Index.find ro k) + in Index.await t |> check_completed; Alcotest.(check string) "value found during the merge" v2 found From f698bdd75717fefbf567e85758c9a39549b702cd Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 17:09:39 +0100 Subject: [PATCH 19/22] Fix RO sync: hold rename_lock, like find Sync cleared the LRU before loading the new bindings, and only held sync_lock. A find on the same instance, from another thread or domain, could then cache the old value right after the clear. Sync now holds rename_lock instead, which find also takes. --- src/index.ml | 11 ++--- src/index_intf.ml | 5 ++- test/unix/concurrent_sync.ml | 78 +++++++++++++++++++++++++++++++++++ test/unix/concurrent_sync.mli | 1 + test/unix/main.ml | 1 + 5 files changed, 90 insertions(+), 6 deletions(-) create mode 100644 test/unix/concurrent_sync.ml create mode 100644 test/unix/concurrent_sync.mli diff --git a/src/index.ml b/src/index.ml index a8a12408..d60ee6f1 100644 --- a/src/index.ml +++ b/src/index.ml @@ -177,8 +177,6 @@ struct writer_lock : IO.Lock.t option; (** A lock that prevents multiple RW instances to be open at the same time. *) - sync_lock : Semaphore.t; - (** A lock that prevents multiple [sync] to happen at the same time. *) merge_lock : Semaphore.t; (** A lock that prevents multiple [merges] to happen at the same time. *) rename_lock : Semaphore.t; @@ -357,9 +355,13 @@ struct else t.index <- Some { fan_out; io } (** Syncs an instance entirely, by checking on-disk changes for [log], [sync], - and [log_async]. *) + and [log_async]. + + It holds [rename_lock], like [find]: a [find] running between the + invalidation of the LRU and the loading of the new bindings would put an + outdated value back in the LRU. This also serializes the syncs. *) let sync_instance ?(hook = fun _ -> ()) t = - Semaphore.with_acquire "sync" t.sync_lock @@ fun () -> + Semaphore.with_acquire "sync" t.rename_lock @@ fun () -> Log.debug (fun l -> l "[%s] checking for changes on disk (generation=%a)" (Filename.basename t.root) Int63.pp t.generation); @@ -628,7 +630,6 @@ struct open_instances = 1; merge_lock = Semaphore.make true; rename_lock = Semaphore.make true; - sync_lock = Semaphore.make true; writer_lock; pending_cancel = false; } diff --git a/src/index_intf.ml b/src/index_intf.ml index 0ed8d11e..d62a4714 100644 --- a/src/index_intf.ml +++ b/src/index_intf.ml @@ -223,7 +223,10 @@ module type Private = sig - [`Before_offset_read]: before reading the generation number and the offset. - - [`After_offset_read]: after reading the generation number and offset. *) + - [`After_offset_read]: after reading the generation number and offset. + + The hooks run while [sync] holds the lock of the instance, so they must + not call [find], [mem] or [sync] on it. *) val log : t -> (key * value) list option val log_async : t -> (key * value) list option diff --git a/test/unix/concurrent_sync.ml b/test/unix/concurrent_sync.ml new file mode 100644 index 00000000..b29e570b --- /dev/null +++ b/test/unix/concurrent_sync.ml @@ -0,0 +1,78 @@ +(* Regression test for a read-only instance that syncs in one domain while + another domain calls [find] on it. A [find] running in the middle of the sync + must not put an outdated value in the LRU. *) + +open Common + +let root = Filename.concat "_tests" "unix.concurrent_sync" +let nb_keys = 500 +let nb_rounds = 20 + +(* Busy-waits until [cond ()] or [stop] holds. *) +let wait_until stop cond = + while not (cond () || Atomic.get stop) do + Domain.cpu_relax () + done + +(* The number of [bindings] whose value is not the one [find] gives. *) +let outdated t bindings = + List.fold_left + (fun n (k, v) -> if String.equal v (Index.find t k) then n else n + 1) + 0 bindings + +(* Each round updates all the keys, then syncs the read-only instance while + another domain calls [find] on all the keys. Right after the sync, the + read-only instance must give the new values. *) +let sync_and_find_two_domains () = + let path = Filename.concat root "a" in + (* The log is large enough to hold all the rounds: no merge happens. *) + let log_size = 2 * nb_keys * (nb_rounds + 1) in + let rw = Index.v ~fresh:true ~lru_size:0 ~log_size path in + let ro = Index.v ~readonly:true ~lru_size:(2 * nb_keys) ~log_size path in + Fun.protect ~finally:(fun () -> + Index.close ro; + Index.close rw) + @@ fun () -> + let keys = List.init nb_keys (fun _ -> Key.v ()) in + let update () = + let bindings = List.map (fun k -> (k, Value.v ())) keys in + List.iter (fun (k, v) -> Index.replace rw k v) bindings; + Index.flush rw; + bindings + in + ignore (update () : (Key.t * Value.t) list); + Index.sync ro; + (* The rounds started by the main domain, and the ones in which the other + domain is done with its finds. *) + let started = Atomic.make 0 and found = Atomic.make 0 in + let stop = Atomic.make false in + let d = + Domain.spawn (fun () -> + (* If a [find] fails, stop the main domain too. *) + Fun.protect ~finally:(fun () -> Atomic.set stop true) @@ fun () -> + for round = 1 to nb_rounds do + wait_until stop (fun () -> Atomic.get started >= round); + List.iter (fun k -> ignore_value (Index.find ro k)) keys; + Atomic.set found round + done) + in + let errors = + Fun.protect + ~finally:(fun () -> + Atomic.set stop true; + Domain.join d) + (fun () -> + List.init nb_rounds succ + |> List.fold_left + (fun n round -> + let bindings = update () in + Atomic.set started round; + Index.sync ro; + wait_until stop (fun () -> Atomic.get found >= round); + n + outdated ro bindings) + 0) + in + Alcotest.(check int) "outdated values after a sync" 0 errors + +let tests = + [ ("sync and find, two domains", `Quick, sync_and_find_two_domains) ] diff --git a/test/unix/concurrent_sync.mli b/test/unix/concurrent_sync.mli new file mode 100644 index 00000000..d38ba9a9 --- /dev/null +++ b/test/unix/concurrent_sync.mli @@ -0,0 +1 @@ +val tests : unit Alcotest.test_case list diff --git a/test/unix/main.ml b/test/unix/main.ml index acab7250..c6ea1cae 100644 --- a/test/unix/main.ml +++ b/test/unix/main.ml @@ -1115,5 +1115,6 @@ let () = ("throttle", Throttle.tests); ("zero-size values", Zero_size_value.tests); ("concurrent find", Concurrent_find.tests); + ("concurrent sync", Concurrent_sync.tests); ("raw header", Raw_header.tests); ] From ccd6e12ffb60803da3bcb503ecc5e5f49baa4175 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 17:12:16 +0100 Subject: [PATCH 20/22] RO sync: only remove the updated keys from the LRU Clearing the whole LRU on every sync that reads new bindings dropped all the cached values of a read-only instance that syncs often. The LRU is still cleared when the generation changes. --- src/index.ml | 44 ++++++++++++++++++++---------------- src/log_file.ml | 11 +++++---- src/log_file.mli | 10 ++++---- test/unix/concurrent_sync.ml | 7 +++++- test/unix/test_lru.ml | 25 ++++++++++++++++++++ 5 files changed, 68 insertions(+), 29 deletions(-) diff --git a/src/index.ml b/src/index.ml index d60ee6f1..254f3bb0 100644 --- a/src/index.ml +++ b/src/index.ml @@ -65,6 +65,7 @@ struct val create : int -> t val add : t -> key -> value -> unit val find : t -> key -> value option + val remove : t -> key -> unit val clear : t -> unit end = struct module Lru = @@ -98,6 +99,7 @@ struct Lru.add k v t; Lru.trim t + let remove t k = Lru.remove k !t let clear t = t := Lru.create (Lru.capacity !t) end @@ -280,14 +282,15 @@ struct (** {1 RO instances syncing} *) - (** Loads the log file at [path], if it exists. Used by RO instances to load - the temporary [log_async], or to fill the [log] field when they have been - created before their RW counterpart. *) - let try_load_log t path = + (** Loads the log file at [path], if it exists, calling [on_key] on the key of + each of its entries. Used by RO instances to load the temporary + [log_async], or to fill the [log] field when they have been created before + their RW counterpart. *) + let try_load_log ?on_key t path = match IO.v_readonly path with | Error `No_file_on_disk -> None | Ok io -> - let log = Log_file.create io in + let log = Log_file.create ?on_key io in Log.debug (fun l -> l "[%s] loaded %d entries from %s" (Filename.basename t.root) (Log_file.cardinal log) (Filename.basename path)); @@ -298,12 +301,10 @@ struct match t.log_async with | None -> hook `Reload_log_async; - let log_async = try_load_log t (Layout.log_async ~root:t.root) in (* The entries of a new [log_async] may update keys cached in the LRU. *) - (match log_async with - | Some log when Log_file.cardinal log > 0 -> Lru.clear t.lru - | Some _ | None -> ()); - t.log_async <- log_async + t.log_async <- + try_load_log ~on_key:(Lru.remove t.lru) t + (Layout.log_async ~root:t.root) | Some log -> let old_generation = t.generation in let old_offset = IO.offset (Log_file.io log) in @@ -318,14 +319,17 @@ struct Log_file.close log; (* check that file is on disk, reopen and reload everything. *) hook `Reload_log_async; - Lru.clear t.lru; - t.log_async <- try_load_log t (Layout.log_async ~root:t.root) + (* Only the keys of the new [log_async] must leave the LRU: the + bindings of the previous one were copied into [log], and a merge + changes the generation of [log], which clears the LRU. *) + t.log_async <- + try_load_log ~on_key:(Lru.remove t.lru) t + (Layout.log_async ~root:t.root) (* else if the disk offset is greater, reload the newest data. *)) - else if old_offset < h.offset then ( - Lru.clear t.lru; - Log_file.sync_entries ~min:old_offset log + else if old_offset < h.offset then + Log_file.sync_entries ~on_key:(Lru.remove t.lru) ~min:old_offset log (* else if the offset is lesser, that means the [log_async] was - cleared, and the generation should have changed. *)) + cleared, and the generation should have changed. *) else if old_offset > h.offset then ( (* Should never occur, but we can recover by reloading the log from scratch rather than just hard failing. *) @@ -359,7 +363,10 @@ struct It holds [rename_lock], like [find]: a [find] running between the invalidation of the LRU and the loading of the new bindings would put an - outdated value back in the LRU. This also serializes the syncs. *) + outdated value back in the LRU. This also serializes the syncs. + + New bindings only remove their keys from the LRU. A new generation of + [log] clears it, as a merge or a clear may have changed any binding. *) let sync_instance ?(hook = fun _ -> ()) t = Semaphore.with_acquire "sync" t.rename_lock @@ fun () -> Log.debug (fun l -> @@ -412,8 +419,7 @@ struct Log.debug (fun l -> l "[%s] new entries detected, reading log from disk" (Filename.basename t.root)); - Lru.clear t.lru; - Log_file.sync_entries ~min:log_offset log) + Log_file.sync_entries ~on_key:(Lru.remove t.lru) ~min:log_offset log) else (* Here the disk offset should be equal to the known one. A smaller offset should not be possible, because that would mean a [clear] or diff --git a/src/log_file.ml b/src/log_file.ml index 75e358b6..d78d8aca 100644 --- a/src/log_file.ml +++ b/src/log_file.ml @@ -159,17 +159,19 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) = struct Entry.encode' key value t.append_io; replace_memory t (Scratch.create ()) key offset - let sync_entries ~min t = + let sync_entries ?(on_key = ignore) ~min t = let scratch = Scratch.create () in IO.iter_keys ~min - (fun offset key -> replace_memory t scratch key offset) + (fun offset key -> + replace_memory t scratch key offset; + on_key key) t.io let reload t = clear_memory t; sync_entries ~min:Int63.zero t - let create io = + let create ?on_key io = let cardinal = Int63.(to_int_exn (IO.offset io / Entry.encoded_sizeL)) in let bucket_count_log2, bucket_count = let rec aux n_log2 n = @@ -183,8 +185,7 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) = struct let t = { io; append_io = IO.append io; hashtbl; bucket_count_log2; cardinal } in - let scratch = Scratch.create () in - IO.iter_keys (fun offset key -> replace_memory t scratch key offset) io; + sync_entries ?on_key ~min:Int63.zero t; t let find t key = diff --git a/src/log_file.mli b/src/log_file.mli index cb425207..c26a3d19 100644 --- a/src/log_file.mli +++ b/src/log_file.mli @@ -23,11 +23,13 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) : sig type key := Key.t type value := Value.t - val create : IO.t -> t + val create : ?on_key:(key -> unit) -> IO.t -> t (** [create io] constructs a write-ahead log from an IO handle referencing an unordered sequence of (binary encoded) [key * value] bindings. The bindings are read into memory, and any subsequent {!replace} operations - are reflected on disk. *) + are reflected on disk. [on_key], which does nothing by default, is called + on the key of each binding read. It must not keep the key, which may be + reused for the next binding. *) val close : t -> unit @@ -50,9 +52,9 @@ module Make (IO : Io.S) (Key : Data.Key) (Value : Data.Value) : sig (** [io t] is [t]'s underlying IO handle. Any updates to the file will not be reflected in the in-memory mirror of its state. *) - val sync_entries : min:int63 -> t -> unit + val sync_entries : ?on_key:(key -> unit) -> min:int63 -> t -> unit (** [sync_entries ~min t] loads the entries from [log]'s IO into memory, - starting from offset [min]. *) + starting from offset [min]. [on_key] is called as in {!create}. *) val flush : ?no_callback:unit -> with_fsync:bool -> t -> unit (** [flush t] is [IO.flush (io t)]. *) diff --git a/test/unix/concurrent_sync.ml b/test/unix/concurrent_sync.ml index b29e570b..9323061a 100644 --- a/test/unix/concurrent_sync.ml +++ b/test/unix/concurrent_sync.ml @@ -1,6 +1,11 @@ (* Regression test for a read-only instance that syncs in one domain while another domain calls [find] on it. A [find] running in the middle of the sync - must not put an outdated value in the LRU. *) + must not put an outdated value in the LRU. + + This test reliably detects a sync that clears the LRU before loading the new + bindings without holding the lock of [find]. With the per-key invalidation + of the LRU, the race window is much narrower, and a missing lock is only + detected now and then. *) open Common diff --git a/test/unix/test_lru.ml b/test/unix/test_lru.ml index 3e902759..9b23cce7 100644 --- a/test/unix/test_lru.ml +++ b/test/unix/test_lru.ml @@ -116,10 +116,35 @@ let test_filter () = (fun () -> ignore (Index.find idx k)); check_lru_stats __POS__ ~hits:0 ~misses:1 +(* Check that a read-only [sync] only removes the updated keys from the LRU: *) +let test_ro_sync () = + let lru_size = 2 in + let* { rw; clone; _ } = Context.with_empty_index ~lru_size () in + let ro = clone ~readonly:true () in + let k1, v1 = (Key.v (), Value.v ()) in + let k2, v2, v2' = (Key.v (), Value.v (), Value.v ()) in + Index.replace rw k1 v1; + Index.replace rw k2 v2; + Index.flush rw; + Index.sync ro; + check_value __POS__ ~expected:v1 (Index.find ro k1); + check_value __POS__ ~expected:v2 (Index.find ro k2); + + (* Update [k2] only: [k1] stays in the LRU. *) + Index.replace rw k2 v2'; + Index.flush rw; + Index.sync ro; + Stats.reset_stats (); + check_value __POS__ ~expected:v1 (Index.find ro k1); + check_lru_stats __POS__ ~hits:1 ~misses:0; + check_value __POS__ ~expected:v2' (Index.find ro k2); + check_lru_stats __POS__ ~hits:1 ~misses:1 + let tests = [ ("replace_and_find", `Quick, test_replace_and_find); ("mem", `Quick, test_mem); ("clear", `Quick, test_clear); ("filter", `Quick, test_filter); + ("readonly sync", `Quick, test_ro_sync); ] From caf8032ab89a70689c989e994223b7c8fc0e2111 Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Mon, 9 Nov 2026 17:13:37 +0100 Subject: [PATCH 21/22] Test RO syncs that update a loaded log_async Cover a sync that appends to the log_async already loaded, and one that reloads the log_async of a second merge. --- test/unix/main.ml | 94 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 77 insertions(+), 17 deletions(-) diff --git a/test/unix/main.ml b/test/unix/main.ml index c6ea1cae..5f01b02c 100644 --- a/test/unix/main.ml +++ b/test/unix/main.ml @@ -611,11 +611,10 @@ module Readonly = struct Index.sync ro; Index.check_binding ro k v2 - (** Readonly finds the new value of a key cached in its LRU, after a sync that - loads the update from a new log_async. *) - let sync_after_log_async_update () = - let* Context.{ rw; clone; _ } = Context.with_empty_index ~lru_size:10 () in - let ro = clone ~readonly:true () in + (** [with_blocked_merge rw f] starts a merge of [rw] and calls [f] while the + merge waits to start, so that the bindings added by [f] go to log_async. + It then completes the merge, and returns the result of [f]. *) + let with_blocked_merge rw f = let merge = Semaphore.make false and merge_started = Semaphore.make false in let merge_hook = I.Private.Hook.v @@ function @@ -624,25 +623,84 @@ module Readonly = struct Semaphore.acquire merge | _ -> () in - let k, v1, v2 = (Key.v (), Value.v (), Value.v ()) in - Index.replace rw k v1; - Index.flush rw; - Index.sync ro; - Index.check_binding ro k v1; let t = Index.try_merge_aux ~force:true ~hook:merge_hook rw in Semaphore.acquire merge_started; + let complete_merge () = + Semaphore.release merge; + Index.await t + in + match f () with + | result -> + complete_merge () |> check_completed; + result + | exception e -> + (* Wait for the merge before closing the instances, and report the + failure of [f] rather than the outcome of the merge. *) + let bt = Printexc.get_raw_backtrace () in + let (_ : (_, _) result) = complete_merge () in + Printexc.raise_with_backtrace e bt + + (** [update ?hook rw ro k v] binds [k] to [v] in [rw], then syncs [ro]. *) + let update ?hook rw ro k v = + Index.replace rw k v; + Index.flush rw; + Index.sync' ?hook ro + + (** Readonly finds the new value of a key cached in its LRU, after a sync that + loads the update from a new log_async. *) + let sync_after_log_async_update () = + let* Context.{ rw; clone; _ } = Context.with_empty_index ~lru_size:10 () in + let ro = clone ~readonly:true () in + let k, v1, v2 = (Key.v (), Value.v (), Value.v ()) in + update rw ro k v1; + Index.check_binding ro k v1; let found = - Fun.protect - ~finally:(fun () -> Semaphore.release merge) - (fun () -> - Index.replace rw k v2; - Index.flush rw; - Index.sync ro; + with_blocked_merge rw (fun () -> + update rw ro k v2; Index.find ro k) in - Index.await t |> check_completed; Alcotest.(check string) "value found during the merge" v2 found + (** Readonly finds the new value of a key cached in its LRU, after a sync that + reads the update from the log_async it has already loaded. *) + let sync_after_log_async_append () = + let* Context.{ rw; clone; _ } = Context.with_empty_index ~lru_size:10 () in + let ro = clone ~readonly:true () in + let k, v1, v2, v3 = (Key.v (), Value.v (), Value.v (), Value.v ()) in + update rw ro k v1; + let found = + with_blocked_merge rw (fun () -> + update rw ro k v2; + Index.check_binding ro k v2; + update rw ro k v3; + Index.find ro k) + in + Alcotest.(check string) "value found during the merge" v3 found + + (** Readonly finds the new value of a key cached in its LRU, after a sync that + reloads the log_async of a second merge. *) + let sync_after_second_merge () = + let* Context.{ rw; clone; _ } = Context.with_empty_index ~lru_size:10 () in + let ro = clone ~readonly:true () in + let k, v1, v2, v3 = (Key.v (), Value.v (), Value.v (), Value.v ()) in + update rw ro k v1; + with_blocked_merge rw (fun () -> + update rw ro k v2; + Index.check_binding ro k v2); + let reload_log_async = ref 0 in + let hook = + I.Private.Hook.v @@ function + | `Reload_log_async -> incr reload_log_async + | _ -> () + in + let found = + with_blocked_merge rw (fun () -> + update ~hook rw ro k v3; + Index.find ro k) + in + Alcotest.(check int) "reloadings of log_async" 1 !reload_log_async; + Alcotest.(check string) "value found during the merge" v3 found + let tests = [ ("add", `Quick, readonly); @@ -671,6 +729,8 @@ module Readonly = struct ("reload log and log async", `Quick, reload_log_async); ("sync after log update", `Quick, sync_after_log_update); ("sync after log_async update", `Quick, sync_after_log_async_update); + ("sync after log_async append", `Quick, sync_after_log_async_append); + ("sync after a second merge", `Quick, sync_after_second_merge); ] end From 6e3897fee12a2d28ed4c6cbebcaf687d6a997fbb Mon Sep 17 00:00:00 2001 From: Vincent Balat Date: Fri, 9 Oct 2026 16:44:52 +0200 Subject: [PATCH 22/22] Release 1.7.0 Complete the changelog with the changes merged since 1.6.2. --- CHANGES.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 6 deletions(-) diff --git a/CHANGES.md b/CHANGES.md index 5ce73c7b..ae14b30b 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,12 +1,53 @@ -# Unreleased +# 1.7.0 (2026-11-13) + +## Added + +- Add `Stats.merge` and `Stats.merge_in`, to combine the statistics recorded + by several domains (#404, @lyrm) +- Expose the Unix platform as `Index_unix.Private.Platform`, so that + `Index.Make` can be applied to it directly (#396, @art-w) +- Document the file format of `Index_unix.Private.Raw` (#380, @tomjridge, + @balat) ## Changed -- Replace global value of Stats by a DLS.key (#404, @lyrm) -- Lock files are now opened with O_CLOEXEC flag (#394, @vect0r-vicall) -- Update to cmdliner.1.1.0 (#382, @MisterDA) -- Mirage support: optional dependency to unix (#396, @art-w) -- Fix RO sync: clear LRU for all log updates (#399, @art-w) +- Breaking: OCaml 5.0 or later is now required (#404, @lyrm) +- Breaking: statistics are now recorded per domain, in a `Domain.DLS` key, + instead of in a global value. `Stats.get` and `Stats.reset_stats` only see + the calling domain (#404, @lyrm) +- Mirage support: `index` no longer depends on `unix`, and `index.unix` is + now an optional library (#396, @art-w) +- Breaking: `Platform.S` and `Checks.Platform_args` now require a `Progress` + and a `Fmt_tty` module, and `Private.Logs.setup` and + `Private.Logs.setup_term` take an extra `(module Platform.FMT_TTY)` + argument (#396, @art-w) +- Support cmdliner 2.0.0. Cmdliner 1.1.0 or later is now required (#382, + @MisterDA, #402, @art-w) + +## Fixed + +- Lock files are now opened with the `O_CLOEXEC` flag (#394, @vect0r-vicall) +- Read-only instances could return stale values after `sync`. `sync` now + removes from their LRU the keys of the entries it loads, from the log or + from the log used during merges. It also holds the lock that `find` takes, + so that a concurrent `find` cannot cache an outdated value in the middle of + a `sync` (#398, #399, @art-w, #406, @balat) +- Merges could lose entries, and `iter` could give wrong keys, when values + are encoded on zero bytes and the key decoder returns its input string + without copying it, as `Repr.decode_bin` does (#387, @Ngoguey42) +- Concurrent `find`s on distinct instances of the same `Index.Make` + application, from several threads or domains, could miss bindings: they + shared the buffer in which they prefetch entries of the data file. Each + instance now has its own buffer, created with + `Private.Io_array.prefetch_buffer` and passed to `Private.Io_array.v` + (#406, @balat) +- `Index_unix.Private.Raw`: reading a truncated header now raises + `Not_written`, as for a missing header, instead of failing an assertion. + Writing a version that is not 8 bytes long raises `Invalid_argument`, and a + write that makes no progress raises `Failure` instead of being dropped + (#406, @balat) +- Add the missing `logs.threaded` dependency of the Unix tests (#400, + @anmonteiro) # 1.6.2 (2023-06-06)