Make heap size hint available as an env variable

[MilesCranmer]

This makes JULIA_HEAP_SIZE_HINT the environment variable version of the --heap-size-hint command-line flag. Seems like there was interest in #45369 (comment).

The same syntax is used as for the command-line version with, for example, 2G => 2 GB and 200M => 200 MB.

@oscardssmith want to take a look?

[quinnj]

Bump; this would be nice

[tecosaur]

It would be nice if the envvar could also be added to the docs 🙂

[MilesCranmer]

Where should it go? It wasn't clear to me where to put it.

[MilesCranmer]

@tecosaur I couldn’t find documentation on --heap-size-hint aside from the CLI help message. Where should the env var docs go? I’m happy to add them I just don’t know where.

[lgoettgens]

On https://docs.julialang.org/en/v1/manual/environment-variables/, all ENV variables are explained. So I would look for it there to find more information

[MilesCranmer]

Done.

[MilesCranmer]

Ping. Would be nice to have this.

[IanButterworth]

The units seem a bit inconsistent.. lowercase in the top list, uppercase in the example, then two-letter uppercase in the cli docs

julia/src/jloptions.c

Lines 234 to 237 in e1e7763

	" --heap-size-hint=<size> Forces garbage collection if memory usage is higher\n"
	" than the given value. The value may be specified as a\n"
	" number of bytes, optionally in units of KB, MB, GB,\n"
	" or TB, or as a percentage of physical memory with %.\n\n"

[MilesCranmer]

Just for reference – the current method in Julia, for whatever reason, is written as to not be case sensitive and actually only takes the first character – so, e.g., 5GB would get parsed as 5g. So technically these are all valid. For example:

julia --heap-size-hint=1giga

will successfully set a 1 GB heap size hint. This is totally valid (though not documented, I guess?) on the current Julia.

I personally don't have a preference other than I agree consistency is always good. Wdyt? In retrospect I think the parsing should have required a specific case and number of characters. But too late for that now as all Julia from 1.9+ have this quirk.

[MilesCranmer]

The inconsistency is also found in the existing docs. e.g., the current code is

    "                                               number of bytes, optionally in units of KB, MB, GB,\n"
    "                                               or TB, or as a percentage of physical memory with %.\n\n"

while other docs give the single-letter version: https://julialang.org/blog/2023/04/julia-1.9-highlights/#memory_usage_hint_for_the_gc_with_--heap-size-hint

[IanButterworth]

I would've thought matching here would make most sense https://docs.julialang.org/en/v1.12-dev/manual/command-line-interface/ so uppercase 2 chars. (Though I see 1.10 does give 'G` as an example.. but better to match current version)

[MilesCranmer]

Ok will do the 2-char version, upper-case, everywhere.

Except B and % as those are single chars

[MilesCranmer]

Hm, I take that back. It looks weird. Note that most unix tools, a single upper-case character is used. For example, dd, rsync, ulimit - they all use K for kilobytes, G for gigabytes, M for megabytes.

All slurm commands use this convention too.

Even ls will display file sizes with a single character unit: ls -l.

[MilesCranmer]

Ok I made everything single char in the docs. (Note that it's backwards compatible; it's just the docs were inconsistent and ambiguous before)

Stale