Initial setup

Author: nmote

.gitignore

@@ -27,3 +27,5 @@ setup.log
 
 # Local OPAM switch
 _opam/
+
+*.swp

README.md

@@ -1,2 +1,58 @@
-# dynamic-gc
-Dynamic tuning for the OCaml garbage collector
+# Dynamic GC
+Dynamic tuning for the OCaml garbage collector.
+
+This utility allows you to instruct the OCaml garbage collector to become more
+aggressive as the size of the major heap grows. This can be useful if you would
+prefer your application to execute quickly with few resources dedicated to
+garbage collection when memory usage is low, but would like to change that
+trade-off when memory usage is high.
+
+Specifically, this utility adjusts the `space_overhead` value at the end of each
+major collection using the [`Gc`](https://ocaml.org/manual/5.3/api/Gc.html)
+module.
+
+## Usage
+
+Install via `opam install dynamic_gc`.
+
+Use according to
+[`DynamicGc.mli`](https://github.com/semgrep/dynamic-gc/blob/main/lib/DynamicGc.mli).
+
+For example, you might put the following at or near the entry point to your
+program. It would allow `space_overhead` to range between 20 and 40, such that
+it is 40 when the size of the major heap is less than 2 GB, 20 when the size of
+the major heap is greater than 4 GB, and linearly interpolated in between.
+
+```
+DynamicGc.(setup_dynamic_tuning
+  {
+    min_space_overhead = 20;
+    max_space_overhead = 40;
+    heap_start_worrying_mb = 2_048;
+    heap_really_worry_mb = 4_096;
+  });
+```
+
+## Caveats
+
+This tunes the garbage collector based on the size of the major heap, not the
+amount of memory that is currently live. Because OCaml 5 does not do compaction
+by default, this means that if your program uses a lot of memory and then
+releases it, the garbage collector may still be set to an aggressive setting
+because the major heap is still large. You may need to manually call
+[`Gc.compact ()`](https://ocaml.org/manual/5.3/api/Gc.html#VALcompact) in order
+to free memory and reduce the size of the major heap, thereby allowing this
+utility to increase the value of `space_overhead`.
+
+This utility relies on garbage collector alarms. This functionality is [broken
+in OCaml
+5.2.0](https://discuss.ocaml.org/t/changes-in-handling-of-gc-parameters-and-alarms-in-5-2-0/14986).
+Upgrade to 5.2.1 instead to use this utility.
+
+## Contributing
+
+To build: `dune build`
+
+To test: `dune test`
+
+To use your local copy in another project: `opam pin .`

dune-project

@@ -0,0 +1,27 @@
+(lang dune 3.17)
+
+(name dynamic_gc)
+
+(generate_opam_files true)
+
+(source
+ (github semgrep/dynamic-gc))
+
+(authors "Nat Mote <nat@semgrep.com>")
+
+(maintainers "Nat Mote <nat@semgrep.com>")
+
+(license MIT)
+
+(documentation https://github.com/semgrep/dynamic-gc)
+
+(package
+ (name dynamic_gc)
+ (synopsis "Dynamically adjust GC behavior based on memory usage")
+ (description "A utility to dynamically adjust garbage collector behavior based
+              on memory usage, allowing your application to prioritize improved
+              run time when memory usage is low, but prioritize decreased memory
+              usage when memory usage is high.")
+ (depends ocaml)
+ (tags
+  ("garbage collector" "gc")))

dynamic_gc.opam

@@ -0,0 +1,35 @@
+# This file is generated by dune, edit dune-project instead
+opam-version: "2.0"
+synopsis: "Dynamically adjust GC behavior based on memory usage"
+description: """
+A utility to dynamically adjust garbage collector behavior based
+              on memory usage, allowing your application to prioritize improved
+              run time when memory usage is low, but prioritize decreased memory
+              usage when memory usage is high."""
+maintainer: ["Nat Mote <nat@semgrep.com>"]
+authors: ["Nat Mote <nat@semgrep.com>"]
+license: "MIT"
+tags: ["garbage collector" "gc"]
+homepage: "https://github.com/semgrep/dynamic-gc"
+doc: "https://github.com/semgrep/dynamic-gc"
+bug-reports: "https://github.com/semgrep/dynamic-gc/issues"
+depends: [
+  "dune" {>= "3.17"}
+  "ocaml"
+  "odoc" {with-doc}
+]
+build: [
+  ["dune" "subst"] {dev}
+  [
+    "dune"
+    "build"
+    "-p"
+    name
+    "-j"
+    jobs
+    "@install"
+    "@runtest" {with-test}
+    "@doc" {with-doc}
+  ]
+]
+dev-repo: "git+https://github.com/semgrep/dynamic-gc.git"

lib/DynamicGc.ml

@@ -0,0 +1,78 @@
+(*
+ * Copyright (C) 2024-2025 Semgrep, Inc.
+ *
+ * This source code is licensed under the MIT license found in the LICENSE file
+ * in the root directory of this source tree.
+ *)
+
+let alarm : Gc.alarm option ref = ref None
+
+type config = {
+  min_space_overhead : int;
+  max_space_overhead : int;
+  heap_start_worrying_mb : int;
+  heap_really_worry_mb : int;
+}
+
+let space_overhead_of_heap_size config heap_size_mb =
+  if config.heap_start_worrying_mb = config.heap_really_worry_mb then begin
+    (* Avoid a division by zero *)
+    if heap_size_mb > config.heap_start_worrying_mb then
+      config.min_space_overhead
+    else config.max_space_overhead
+  end
+  else
+    (* Linear interpolation *)
+    let heap_size_mb = Float.of_int heap_size_mb in
+    let min_space_overhead = Float.of_int config.min_space_overhead in
+    let max_space_overhead = Float.of_int config.max_space_overhead in
+    let heap_start_worrying_mb = Float.of_int config.heap_start_worrying_mb in
+    let heap_really_worry_mb = Float.of_int config.heap_really_worry_mb in
+    let rate =
+      (min_space_overhead -. max_space_overhead)
+      /. (heap_really_worry_mb -. heap_start_worrying_mb)
+    in
+    let intercept = max_space_overhead -. (rate *. heap_start_worrying_mb) in
+    let space_overhead_unbounded = (rate *. heap_size_mb) +. intercept in
+    let space_overhead =
+      max min_space_overhead (min space_overhead_unbounded max_space_overhead)
+    in
+    space_overhead |> Float.round |> Float.to_int
+
+let handle_alarm config () =
+  let { Gc.heap_words; _ } = Gc.quick_stat () in
+  let word_size_bytes = Sys.word_size / 8 in
+  let heap_size_mb = heap_words * word_size_bytes / (1_024 * 1_024) in
+  let space_overhead = space_overhead_of_heap_size config heap_size_mb in
+  Gc.set { (Gc.get ()) with space_overhead }
+
+let setup_dynamic_tuning config =
+  if Option.is_some !alarm then
+    failwith "Gc_.setup_dynamic_tuning called multiple times.";
+  (* Can be the same, but that would be kind of stupid *)
+  if config.min_space_overhead > config.max_space_overhead then
+    failwith
+      "Gc_.setup_dynamic_tuning called with min_space_overhead greater than \
+       max_space_overhead";
+  (* Can be equal if you want a sharp cutover from max space overhead to min! *)
+  if config.heap_start_worrying_mb > config.heap_really_worry_mb then
+    failwith
+      "Gc_.setup_dynamic_tuning called with nonsensical heap size arguments";
+  (* Call this immediately so that we set space_overhead as desired without
+   * first having to wait for a major collection to complete. *)
+  handle_alarm config ();
+  alarm := Some (Gc.create_alarm (handle_alarm config))
+
+let stop_dynamic_tuning () =
+  match !alarm with
+  | Some a ->
+      Gc.delete_alarm a;
+      alarm := None
+  | None ->
+      failwith
+        "Gc_.stop_dynamic_tuning called when dynamic tuning was already \
+         stopped."
+
+module ForTestingDoNotUse = struct
+  let space_overhead_of_heap_size = space_overhead_of_heap_size
+end

lib/DynamicGc.mli

@@ -0,0 +1,50 @@
+(*
+ * Copyright (C) 2024-2025 Semgrep, Inc.
+ *
+ * This source code is licensed under the MIT license found in the LICENSE file
+ * in the root directory of this source tree.
+ *)
+
+(* Utilities for interacting with the OCaml garbage collector. See
+ * https://ocaml.org/manual/5.2/api/Gc.html for context. Without familiarity
+ * with the Gc module, this module is not likely to make a whole lot of sense.
+ * *)
+
+(* Configuration for dynamic GC tuning. This allows us to prioritize time over
+ * space by minimizing time spent garbage collecting when the major heap is
+ * small. As the major heap grows, we can gradually make the GC more aggressive
+ * and begin to prioritize space efficiency at the expense of time. *)
+type config = {
+  (* The minimum value for space_overhead that should be dynamically applied.
+   * This is the MOST aggressive GC setting. *)
+  min_space_overhead : int;
+  (* The maximum setting for space_overhead that should be dynamically applied.
+   * This is the LEAST aggressive GC setting. *)
+  max_space_overhead : int;
+  (* The size of the major heap where we start becoming more aggressive with
+   * space_overhead. Below this size, we always set space_overhead to
+   * max_space_overhead. Above, we interpolate linearly until we reach
+   * min_space_overhead at heap_really_worry_mb. *)
+  heap_start_worrying_mb : int;
+  (* The size of the major heap where we apply the most aggressive setting for
+   * space_overhead (min_space_overhead) in an attempt to minimize memory
+   * consumption at the cost of runtime. *)
+  heap_really_worry_mb : int;
+}
+
+(* Starts dynamic GC tuning based on the given config. Recomputes and applies
+ * the desired space_overhead after each major collection.
+ *
+ * Precondition: As this mutates global state, it cannot be called multiple
+ * times without intervening calls to `stop_dynamic_tuning`. *)
+val setup_dynamic_tuning : config -> unit
+
+(* Stops the ongoing dynamic GC tuning. Does not return space_overhead to its
+ * previous value.
+ *
+ * Precondition: Cannot be called unless dynamic tuning is currently ongoing. *)
+val stop_dynamic_tuning : unit -> unit
+
+module ForTestingDoNotUse : sig
+  val space_overhead_of_heap_size : config -> int -> int
+end

lib/dune

@@ -0,0 +1,4 @@
+(library
+ (public_name dynamic_gc)
+ (name dynamic_gc)
+ (wrapped false))

test/dune

@@ -0,0 +1,3 @@
+(test
+ (name test_dynamic_gc)
+ (libraries dynamic_gc))

test/test_dynamic_gc.ml

@@ -0,0 +1,52 @@
+(*
+ * Copyright (C) 2024-2025 Semgrep, Inc.
+ *
+ * This source code is licensed under the MIT license found in the LICENSE file
+ * in the root directory of this source tree.
+ *)
+
+(* If this grows any more complex, pull in Alcotest and Testo *)
+let check (expected: int) (actual: int) (case_name: string) =
+  if expected <> actual then
+    failwith (Printf.sprintf "%s: expected %d, got %d" case_name expected actual)
+
+(* name, config, heap size, expected space overhead *)
+type case = string * DynamicGc.config * int * int
+
+let simple_config =
+  DynamicGc.
+    {
+      min_space_overhead = 20;
+      max_space_overhead = 40;
+      heap_start_worrying_mb = 1_024;
+      heap_really_worry_mb = 4_096;
+    }
+
+let same_heap_size_cutoff =
+  DynamicGc.
+    {
+      min_space_overhead = 20;
+      max_space_overhead = 40;
+      heap_start_worrying_mb = 1_024;
+      heap_really_worry_mb = 1_024;
+    }
+
+let cases : case list =
+  [
+    ("under worrying limit", simple_config, 512, 40);
+    ("at worrying limit", simple_config, 1_024, 40);
+    ("halfway", simple_config, 2_560, 30);
+    ("at really worrying limit", simple_config, 4_096, 20);
+    ("above really worrying limit", simple_config, 8_192, 20);
+    ("below single cutoff", same_heap_size_cutoff, 1_023, 40);
+    ("at single cutoff", same_heap_size_cutoff, 1_024, 40);
+    ("above single cutoff", same_heap_size_cutoff, 1_025, 20);
+  ]
+
+let check_case (name, config, heap_size, expected_space_overhead) =
+  check
+    expected_space_overhead
+    (DynamicGc.ForTestingDoNotUse.space_overhead_of_heap_size config heap_size)
+    name
+
+let () = List.iter check_case cases