Skip to content

Add server.gc_initial_heap_mib to start the GC heap at a set size - #1452

Merged
crimson-knight merged 2 commits into
v2-devfrom
feat/gc-starting-heap
Nov 20, 2026
Merged

crimson-knight merged 2 commits into
v2-devfrom
feat/gc-starting-heap

Conversation

@crimson-knight

@crimson-knight crimson-knight commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

What

A typed server setting, server.gc_initial_heap_mib (default 0), with the AMBER_SERVER_GC_INITIAL_HEAP_MIB override. Amber::Server#start grows Boehm GC's heap to that many MiB before it takes requests, in every server process (workers started by run reach start too).

  • Amber::Server::GrowHeapToStartingSize calls GC_expand_hp for the missing bytes. Crystal's LibGC does not bind it, so Amber binds it in its own lib LibAmberGC (no change to stdlib). GC_expand_hp is part of bdwgc's public API in gc.h on macOS, Linux and Windows; libgc is already linked by the runtime. Under -Dgc_none the step does nothing.
  • A heap that is already at least that large (for example because GC_INITIAL_HEAP_SIZE is set) is left alone, and 0 keeps the collector's own starting size, so existing apps see no change.
  • validate! rejects a negative value.
  • Docs: docs/guides/configuration.md (server section, validation rules, env table).

Why

A full-app A/B of a generated amber new -d sqlite app (beta.10 against the beta.11 PR set) showed POST /posts p50 +0.119 ms (2.088 -> 2.207 ms) while peak memory fell from 234 MiB to 25 MiB: the beta.11 app collects a small heap more often. With a 256 MiB starting heap on both sides, beta.11 won every POST metric. The amber_cli companion PR (amberframework/amber_cli#56) writes gc_initial_heap_mib: 16 into every generated environment file; the heap sweep that picks 16 MiB is summarized there and in a comment here.

Specs

  • spec/amber/server/grow_heap_to_starting_size_spec.cr: grows the heap to the starting size; leaves a heap that is already large enough; does nothing for 0.
  • server_config_spec.cr: default 0, YAML read, negative value rejected, 0 accepted.
  • env_override_spec.cr: AMBER_SERVER_GC_INITIAL_HEAP_MIB.

Local (crystal-alpha 1.21.0, macOS arm64): the three spec files pass (95 examples, 0 failures); scripts/check_beta_contract.sh passes; crystal tool format --check is clean; the spec compiles with -Dgc_none.

The CHANGELOG line belongs in the beta.11 section that #1451 starts, so it is left out here to avoid a conflict.

The server grows Boehm GC's heap to server.gc_initial_heap_mib MiB in
each server process before it takes requests (GC_expand_hp, part of
bdwgc's public API). 0, the default, keeps the collector's own starting
size. AMBER_SERVER_GC_INITIAL_HEAP_MIB overrides it, and validate!
rejects a negative value.
@crimson-knight

Copy link
Copy Markdown
Member Author

Heap sweep result (generated amber new -d sqlite app, beta.11 PR set against beta.10, 10 interleaved pairs, default log level). The smallest starting heap whose POST /posts p50 interval is at or below 1.0 is 16 MiB: p50 2.194 -> 2.108 ms (ratio 0.954 [0.945, 0.973]), requests/s 12,708 -> 14,257, p99 11.567 -> 6.609 ms, peak RSS 232.6 -> 33.9 MiB. 4 MiB (p50 1.105) and 8 MiB (1.054) do not get there. An app built from this branch on top of #1451, with gc_initial_heap_mib: 16 set only in production.yml, gives POST p50 2.106 -> 2.082 ms (0.983 [0.970, 0.994]), so the setting matches GC_INITIAL_HEAP_SIZE. Its one worse row is peak RSS on a small JSON route, 17.8 -> 25.7 MiB, which is the heap itself. Its release binary still links no PCRE2 (0 otool -L lines, 0 nm symbols). amberframework/amber_cli#56 generates apps with 16.

@crimson-knight
crimson-knight merged commit 6b51844 into v2-dev Nov 20, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant