Skip to content

Update Gc.control documentation to OCaml 5 #13440

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
kayceesrk merged 3 commits into from
Sep 23, 2024
Merged

Update Gc.control documentation to OCaml 5 #13440

kayceesrk merged 3 commits into from
Sep 23, 2024

Conversation

@jmid
Copy link
Member

@jmid jmid commented Sep 13, 2024

While continuing on a Gc module test I spotted a bit more documentation needing updating on OCaml 5:

  • 3 Gc.control fields (major_heap_increment, max_overhead, and window_size) are out of date, as they are unavailable. I've slightly adjusted the existing documentation of allocation_policy to make the four of them uniform
  • stack_limit's documented default should reflect OCaml 5's much higher default value

I can see that the stack_limit was adjusted in #11238 as part of the 5.0 release
and that the manual was updated in #13066 as part of the 5.2 release.

For easy reference, the relevant parts underlying Gc.get does not extract fields 1, 4, 6, and 7:

ocaml/runtime/gc_ctrl.c

Lines 122 to 136 in f2ff4a4

CAMLprim value caml_gc_get(value v)
{
CAMLparam0 (); /* v is ignored */
CAMLlocal1 (res);
res = caml_alloc_tuple (11);
Store_field (res, 0, Val_long (Caml_state->minor_heap_wsz)); /* s */
Store_field (res, 2, Val_long (caml_percent_free)); /* o */
Store_field (res, 3, Val_long (atomic_load_relaxed(&caml_verb_gc))); /* v */
Store_field (res, 5, Val_long (caml_max_stack_wsize)); /* l */
Store_field (res, 8, Val_long (caml_custom_major_ratio)); /* M */
Store_field (res, 9, Val_long (caml_custom_minor_ratio)); /* m */
Store_field (res, 10, Val_long (caml_custom_minor_max_bsz)); /* n */
CAMLreturn (res);
}

and the same is true for Gc.set:

ocaml/runtime/gc_ctrl.c

Lines 155 to 163 in f2ff4a4

CAMLprim value caml_gc_set(value v)
{
uintnat newminwsz = caml_norm_minor_heap_size (Long_val (Field (v, 0)));
uintnat newpf = norm_pfree (Long_val (Field (v, 2)));
uintnat new_verb_gc = Long_val (Field (v, 3));
uintnat new_max_stack_size = Long_val (Field (v, 5));
uintnat new_custom_maj = norm_custom_maj (Long_val (Field (v, 8)));
uintnat new_custom_min = norm_custom_min (Long_val (Field (v, 9)));
uintnat new_custom_sz = Long_val (Field (v, 10));

The default stack size is documented in these lines (note: it is 128M words):

ocaml/runtime/caml/config.h

Lines 195 to 197 in f2ff4a4

/* Default maximum size of the stack (words). */
/* (1 Gib for 64-bit platforms, 512 Mib for 32-bit platforms) */
#define Max_stack_def (128 * 1024 * 1024)

@jmid
Copy link
Member Author

jmid commented Sep 16, 2024

Rebased on trunk to avoid merge conflicts in Changes

ghost
ghost reviewed Sep 18, 2024
View reviewed changes
gasche
gasche approved these changes Sep 20, 2024
View reviewed changes
Copy link
Member

@gasche gasche left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I warmly welcome documentation improvements. Thanks! Approved.

@jmid
Copy link
Member Author

jmid commented Sep 20, 2024

Thanks, I've updated Changes accordingly.

Would be good to cherry-pick this one to 5.3 along with #13424 (the latter first then this one, to avoid Changes conflicts)

@kayceesrk kayceesrk merged commit b516815 into ocaml:trunk Sep 23, 2024
@kayceesrk kayceesrk added this to the 5.3 milestone Sep 23, 2024
@jmid jmid deleted the gc-control-docs branch September 23, 2024 11:59
@jmid jmid mentioned this pull request Sep 24, 2024
Merged
dra27 pushed a commit that referenced this pull request Oct 2, 2024
@kayceesrk @dra27
Merge pull request #13440 from jmid/gc-control-docs
6e8620f 
Update Gc.control documentation to OCaml 5

(cherry picked from commit b516815)
@jmid jmid mentioned this pull request Jan 10, 2025
Merged
@Octachron Octachron mentioned this pull request Apr 11, 2025
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gasche gasche gasche approved these changes

+1 more reviewer
Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

documentation merge-me

Projects

None yet

Milestone

5.3.0

Development

Successfully merging this pull request may close these issues.

3 participants

@jmid @gasche @kayceesrk