feat(enactment): hibernate_after to reduce idle memory (audit #6) (#77)

Author: fahchen

lib/coloured_flow/runner/enactment/enactment.ex

@@ -77,11 +77,18 @@ defmodule ColouredFlow.Runner.Enactment do
     field :timeout, timeout(),
       enforce: false,
       doc: "The enactment timeout; see `ColouredFlow.Runner.Enactment.Lifespan` for details."
+
+    field :hibernate_after, timeout(),
+      enforce: false,
+      doc:
+        "The idle duration after which the GenServer hibernates; " <>
+          "see `ColouredFlow.Runner.Enactment.Lifespan` for details."
   end
 
   @type option() ::
           {:enactment_id, enactment_id()}
           | {:timeout, timeout()}
+          | {:hibernate_after, timeout()}
 
   @type options() :: [option()]
 
@@ -92,13 +99,17 @@ defmodule ColouredFlow.Runner.Enactment do
     GenServer.start_link(
       __MODULE__,
       options,
-      name: Registry.via_name({:enactment, enactment_id})
+      name: Registry.via_name({:enactment, enactment_id}),
+      hibernate_after: Lifespan.hibernate_after_from_options(options)
     )
   end
 
   @impl GenServer
   def init(options) do
-    state = struct(__MODULE__, options)
+    state =
+      __MODULE__
+      |> struct(options)
+      |> Map.put(:hibernate_after, Lifespan.hibernate_after_from_options(options))
 
     {:ok, state, {:continue, :populate_state}}
   end

lib/coloured_flow/runner/enactment/lifespan.ex

@@ -1,27 +1,77 @@
 defmodule ColouredFlow.Runner.Enactment.Lifespan do
   @moduledoc """
   The lifespan of a `ColouredFlow.Runner.Enactment` GenServer can be configured
-  through the config. The default timeout is `:infinity`.
+  through the config. Two knobs are exposed:
+
+  - `:timeout` — how long the process may sit idle before it shuts itself down.
+    Defaults to `:infinity` (the enactment is long-lived).
+  - `:hibernate_after` — how long the process may sit idle before BEAM moves its
+    state into hibernation, compressing memory at the cost of a small wake-up
+    latency on the next message. Defaults to `15_000` ms.
+
+  Both values follow the same precedence: per-`enactment` option (passed to
+  `ColouredFlow.Runner.Enactment.start_link/1`) overrides application config,
+  which in turn overrides the built-in default.
 
   Example:
 
   ```elixir
   config :coloured_flow,
-          ColouredFlow.Runner.Enactment.Lifespan,
-          timeout: 60 * 1000 # 1 minute
+         ColouredFlow.Runner.Enactment,
+         timeout: 60 * 1000,           # 1 minute
+         hibernate_after: 15 * 1000    # 15 seconds
   ```
+
+  > #### `:timeout` shadows `:hibernate_after` {: .info}
+  >
+  > Per OTP `gen_server` semantics, `:hibernate_after` only takes effect when the
+  > GenServer's `noreply` timeout is `:infinity`. With a finite `:timeout`, BEAM
+  > uses that as the receive timeout (which fires the inactivity-shutdown path)
+  > and ignores `:hibernate_after`. Hibernation is therefore most useful with the
+  > default `:timeout` of `:infinity`.
   """
 
   alias ColouredFlow.Runner.Enactment
 
   @default_timeout :infinity
+  @default_hibernate_after 15_000
 
   @spec timeout(Enactment.state()) :: timeout()
   def timeout(%Enactment{timeout: nil}) do
-    :coloured_flow
-    |> Application.get_env(ColouredFlow.Runner.Enactment, [])
-    |> Keyword.get(:timeout, @default_timeout)
+    fetch_env(:timeout, @default_timeout)
   end
 
   def timeout(%Enactment{timeout: timeout}), do: timeout
+
+  @doc """
+  Resolves the `:hibernate_after` value for a running enactment, falling back to
+  application config and the built-in default when no per-enactment value was
+  supplied.
+  """
+  @spec hibernate_after(Enactment.state()) :: timeout()
+  def hibernate_after(%Enactment{hibernate_after: nil}) do
+    fetch_env(:hibernate_after, @default_hibernate_after)
+  end
+
+  def hibernate_after(%Enactment{hibernate_after: hibernate_after}), do: hibernate_after
+
+  @doc """
+  Resolves the `:hibernate_after` value at `start_link/1` time, before the
+  GenServer state struct exists. Mirrors `hibernate_after/1` but reads from the
+  raw options keyword list.
+  """
+  @spec hibernate_after_from_options(Enactment.options()) :: timeout()
+  def hibernate_after_from_options(options) when is_list(options) do
+    case Keyword.get(options, :hibernate_after) do
+      nil -> fetch_env(:hibernate_after, @default_hibernate_after)
+      value -> value
+    end
+  end
+
+  @spec fetch_env(atom(), timeout()) :: timeout()
+  defp fetch_env(key, default) do
+    :coloured_flow
+    |> Application.get_env(ColouredFlow.Runner.Enactment, [])
+    |> Keyword.get(key, default)
+  end
 end

mix.exs

@@ -52,6 +52,7 @@ defmodule ColouredFlow.MixProject do
          runtime: false
        ]},
       {:kino, "~> 0.14.1", only: [:dev, :test]},
+      {:mimic, "~> 1.7", only: :test},
       {:postgrex, ">= 0.0.0"},
       {:telemetry, "~> 1.0"},
       {:typed_structor, "~> 0.6", override: true}

mix.lock

@@ -15,12 +15,14 @@
   "ex_machina": {:hex, :ex_machina, "2.8.0", "a0e847b5712065055ec3255840e2c78ef9366634d62390839d4880483be38abe", [:mix], [{:ecto, "~> 2.2 or ~> 3.0", [hex: :ecto, repo: "hexpm", optional: true]}, {:ecto_sql, "~> 3.0", [hex: :ecto_sql, repo: "hexpm", optional: true]}], "hexpm", "79fe1a9c64c0c1c1fab6c4fa5d871682cb90de5885320c187d117004627a7729"},
   "file_system": {:hex, :file_system, "1.1.1", "31864f4685b0148f25bd3fbef2b1228457c0c89024ad67f7a81a3ffbc0bbad3a", [:mix], [], "hexpm", "7a15ff97dfe526aeefb090a7a9d3d03aa907e100e262a0f8f7746b78f8f87a5d"},
   "fss": {:hex, :fss, "0.1.1", "9db2344dbbb5d555ce442ac7c2f82dd975b605b50d169314a20f08ed21e08642", [:mix], [], "hexpm", "78ad5955c7919c3764065b21144913df7515d52e228c09427a004afe9c1a16b0"},
+  "ham": {:hex, :ham, "0.3.2", "02ae195f49970ef667faf9d01bc454fb80909a83d6c775bcac724ca567aeb7b3", [:mix], [], "hexpm", "b71cc684c0e5a3d32b5f94b186770551509e93a9ae44ca1c1a313700f2f6a69a"},
   "jason": {:hex, :jason, "1.4.4", "b9226785a9aa77b6857ca22832cffa5d5011a667207eb2a0ad56adb5db443b8a", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "c5eb0cab91f094599f94d55bc63409236a8ec69a21a67814529e8d5f6cc90b3b"},
   "jet_credo": {:git, "https://github.com/Byzanteam/jet_credo.git", "7e5855de2e8b41abfb0a1f5870bbc768a325f4e8", [ref: "7e5855de2e8b41abfb0a1f5870bbc768a325f4e8"]},
   "kino": {:hex, :kino, "0.14.2", "46c5da03f2d62dc119ec5e1c1493f409f08998eac26015ecdfae322ffff46d76", [:mix], [{:fss, "~> 0.1.0", [hex: :fss, repo: "hexpm", optional: false]}, {:nx, "~> 0.1", [hex: :nx, repo: "hexpm", optional: true]}, {:plug, "~> 1.0", [hex: :plug, repo: "hexpm", optional: true]}, {:table, "~> 0.1.2", [hex: :table, repo: "hexpm", optional: false]}], "hexpm", "f54924dd0800ee8b291fe437f942889e90309eb3541739578476f53c1d79c968"},
   "makeup": {:hex, :makeup, "1.1.2", "9ba8837913bdf757787e71c1581c21f9d2455f4dd04cfca785c70bbfff1a76a3", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cce1566b81fbcbd21eca8ffe808f33b221f9eee2cbc7a1706fc3da9ff18e6cac"},
   "makeup_elixir": {:hex, :makeup_elixir, "0.16.2", "627e84b8e8bf22e60a2579dad15067c755531fea049ae26ef1020cad58fe9578", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "41193978704763f6bbe6cc2758b84909e62984c7752b3784bd3c218bb341706b"},
   "makeup_erlang": {:hex, :makeup_erlang, "1.0.1", "c7f58c120b2b5aa5fd80d540a89fdf866ed42f1f3994e4fe189abebeab610839", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "8a89a1eeccc2d798d6ea15496a6e4870b75e014d1af514b1b71fa33134f57814"},
+  "mimic": {:hex, :mimic, "1.12.0", "34c9d1fb8e756df09ca5f96861d273f2bb01063df1a6a51a4c101f9ad7f07a9c", [:mix], [{:ham, "~> 0.2", [hex: :ham, repo: "hexpm", optional: false]}], "hexpm", "eaa43d495d6f3bc8099b28886e05a1b09a2a6be083f6385c3abc17599e5e2c43"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},
   "postgrex": {:hex, :postgrex, "0.19.1", "73b498508b69aded53907fe48a1fee811be34cc720e69ef4ccd568c8715495ea", [:mix], [{:db_connection, "~> 2.1", [hex: :db_connection, repo: "hexpm", optional: false]}, {:decimal, "~> 1.5 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:table, "~> 0.1.0", [hex: :table, repo: "hexpm", optional: true]}], "hexpm", "8bac7885a18f381e091ec6caf41bda7bb8c77912bb0e9285212829afe5d8a8f8"},
   "rustler_precompiled": {:hex, :rustler_precompiled, "0.8.3", "4e741024b0b097fe783add06e53ae9a6f23ddc78df1010f215df0c02915ef5a8", [:mix], [{:castore, "~> 0.1 or ~> 1.0", [hex: :castore, repo: "hexpm", optional: false]}, {:rustler, "~> 0.23", [hex: :rustler, repo: "hexpm", optional: true]}], "hexpm", "c23f5f33cb6608542de4d04faf0f0291458c352a4648e4d28d17ee1098cddcc4"},

test/coloured_flow/runner/enactment/lifespan_test.exs

@@ -4,6 +4,8 @@ defmodule ColouredFlow.Runner.Enactment.LifespanTest do
 
   import ColouredFlow.MultiSet, only: :sigils
 
+  alias ColouredFlow.Runner.Enactment.Lifespan
+
   describe "terminated due to inactivity" do
     setup :setup_flow
     setup :setup_enactment
@@ -28,4 +30,119 @@ defmodule ColouredFlow.Runner.Enactment.LifespanTest do
       }
     end
   end
+
+  describe "hibernate_after" do
+    setup :setup_flow
+    setup :setup_enactment
+
+    @describetag cpnet: :simple_sequence
+
+    @tag initial_markings: [%Marking{place: "input", tokens: ~MS[1]}]
+    test "hibernates the GenServer after the configured idle duration",
+         %{enactment: enactment} do
+      # `hibernate_after` only kicks in when the GenServer's `noreply` timeout
+      # is `:infinity` (see OTP `gen_server` `loop/5`); a finite timeout takes
+      # priority and produces a synthetic `:timeout` message instead. The
+      # production default for `Lifespan.timeout/1` is already `:infinity`, but
+      # the test config sets it to `60_000`, so we override per-enactment to
+      # exercise the hibernate path here.
+      [enactment_server: enactment_server] =
+        start_enactment(%{enactment: enactment}, timeout: :infinity, hibernate_after: 100)
+
+      # Make sure the boot continues have completed before we start measuring
+      # idle time, so the hibernate timer is actually counting down on an
+      # empty mailbox.
+      :ok = wait_enactment_requests_handled!(enactment_server)
+
+      assert eventually(fn -> hibernated?(enactment_server) end),
+             "expected #{inspect(enactment_server)} to hibernate within the deadline; " <>
+               "current_function=#{inspect(Process.info(enactment_server, :current_function))}, " <>
+               "status=#{inspect(Process.info(enactment_server, :status))}, " <>
+               "messages=#{inspect(Process.info(enactment_server, :messages))}"
+    end
+  end
+
+  describe "hibernate_after resolution" do
+    use Mimic
+
+    test "hibernate_after_from_options prefers explicit option" do
+      expect_enactment_env(hibernate_after: 7_000)
+
+      assert Lifespan.hibernate_after_from_options(hibernate_after: 42) === 42
+    end
+
+    test "hibernate_after_from_options falls back to application env" do
+      expect_enactment_env(hibernate_after: 7_000)
+
+      assert Lifespan.hibernate_after_from_options([]) === 7_000
+    end
+
+    test "hibernate_after_from_options falls back to the built-in default" do
+      expect_enactment_env([])
+
+      assert Lifespan.hibernate_after_from_options([]) === 15_000
+    end
+
+    test "hibernate_after/1 prefers per-state value" do
+      expect_enactment_env(hibernate_after: 7_000)
+
+      state = %Enactment{enactment_id: "irrelevant", hibernate_after: 42}
+
+      assert Lifespan.hibernate_after(state) === 42
+    end
+
+    test "hibernate_after/1 falls back to application env when state value is nil" do
+      expect_enactment_env(hibernate_after: 7_000)
+
+      state = %Enactment{enactment_id: "irrelevant"}
+
+      assert Lifespan.hibernate_after(state) === 7_000
+    end
+  end
+
+  # A hibernated GenServer is observable in two ways:
+  #
+  # - `:current_function` becomes `{:gen_server, :loop_hibernate, _}` once the
+  #   process has fully entered the hibernate loop, OR `{:erlang, :hibernate, _}`
+  #   while it is in the middle of the transition.
+  # - `:status` is `:waiting` and the heap is compacted.
+  #
+  # We accept either current_function form so the assertion is robust against
+  # the exact moment we sample.
+  defp hibernated?(pid) do
+    case Process.info(pid, :current_function) do
+      {:current_function, {:gen_server, :loop_hibernate, _arity}} -> true
+      {:current_function, {:erlang, :hibernate, _arity}} -> true
+      _other -> false
+    end
+  end
+
+  # Poll the predicate up to ~1s, in 20ms slices, giving the runtime time to
+  # transition into hibernation without burning a fixed long sleep.
+  defp eventually(fun, deadline_ms \\ 1_000, slice_ms \\ 20) do
+    wait_until(fun, System.monotonic_time(:millisecond) + deadline_ms, slice_ms)
+  end
+
+  defp wait_until(fun, deadline, slice) do
+    if fun.() do
+      true
+    else
+      if System.monotonic_time(:millisecond) >= deadline do
+        false
+      else
+        Process.sleep(slice)
+        wait_until(fun, deadline, slice)
+      end
+    end
+  end
+
+  # Stub `Application.get_env/3` for the runner-enactment keyword list. Used as
+  # `stub` (not `expect`) because not every test under this describe block hits
+  # the env path — tests that pass an explicit per-state value short-circuit
+  # before reaching `Application.get_env/3`.
+  defp expect_enactment_env(env) when is_list(env) do
+    Mimic.stub(Application, :get_env, fn
+      :coloured_flow, ColouredFlow.Runner.Enactment, [] -> env
+    end)
+  end
 end

test/test_helper.exs

@@ -12,4 +12,9 @@ end
 
 Ecto.Adapters.SQL.Sandbox.mode(ColouredFlow.TestRepo, :manual)
 
+# Mimic-mockable modules. Tests that want to override behaviour call
+# `Mimic.copy/1` on these in their `setup` block (or `use Mimic` at the
+# top of the file) and `Mimic.expect/3` per test.
+Mimic.copy(Application)
+
 ExUnit.start(capture_log: true)