Module Tolk.Setting
Settings.
A setting is a value of the library's global state, read from an environment variable when the program starts and overridable for the extent of a function call with context. It is declared once, with its variable and what its value reaches. Besides settings, tolk reads only where it finds files: CACHEDB (Helpers.cachedb), the system's PATH, LD_LIBRARY_PATH, HOME and XDG_CACHE_HOME, and the variable that names a library's file (C.findlib). Tolk's settings are all declared here (Tolk's settings), so that each can be bound with context. A library that compiles with tolk declares its own settings with this module too, so that the caches key on those that reach its output.
A setting has an initial value, read from its environment variable when it is declared, and a current value on each domain: the innermost context override made on the domain, or else the value it had on the domain that spawned it, when it spawned it, or else the initial value.
Integers are an optional + or - followed by decimal digits, where a single underscore may separate two digits, surrounded by any number of spaces, tabs, newlines, vertical tabs, form feeds and carriage returns. Numbers are an optional + or - followed by inf, infinity or nan in any case, or by a decimal number: digits with an optional fraction (1.5, 1. or .5) and an optional exponent (e or E, an optional sign, and digits), with digits and white space as for integers.
Reach
type reach = What a setting's value reaches.
A compilation makes a schedule, a kernel's program, the optimizations a search picks or a compiled schedule from its arguments: the graph, and the renderer with its compiler. A setting reaches Output if a change of its value alone can change what a compilation that returns makes, for the same measurements, since what a search picks depends on the times it measures. It reaches Process otherwise: then a change makes compilation only print, check, keep, look up or work in parallel otherwise, or raise where it returned.
A compiler names the tools it runs and their options in its cache key (Renderer.Compiler.v), which the caches take with what it makes, so a setting read when a compiler is made, such as where its tools are, reaches the process.
Settings
Declare a setting at a module's top level, so that it is declared before anything is compiled. Every constructor raises Invalid_argument if a setting named key is already declared, or if the variable key holds something its type does not read, non-ASCII digits and white space included, or an integer out of int's range.
type 'a tThe type for settings of type 'a.
int ~reach key default is a setting whose initial value is the integer the variable key holds, or default if key is unset.
bool ~reach key default is a setting whose initial value is true iff the variable key holds a nonzero integer, and default if key is unset.
float ~reach key default is a setting whose initial value is the number the variable key holds, or default if key is unset.
string ~reach key default is a setting whose initial value is the variable key as written, or default if key is unset. A variable set to the empty string is "".
int_option ~reach key is a setting whose initial value is Some n if the variable key holds the integer n, and None if key is unset: the setting's documentation states what None stands for.
The type for settings bound to values.
context bindings f is f (), run with each setting of bindings holding its bound value; when a setting is bound twice, the later binding wins. Each setting gets its previous value back when f returns or raises.
The overrides are seen by what runs meanwhile on the calling domain, and by the domains it spawns meanwhile, which start with its values. Other domains do not see them, so domains override settings independently.
val shaping : unit -> (string * string) listshaping () is the name and the current value on the calling domain, as text, of each setting whose reach is Output, sorted by name: what the caches of programs, schedules and searches key on. Two values have the same text only if they are equal: a number is written in hexadecimal and None as "". While no such setting changes on the calling domain, the result is the same list, and reading it allocates nothing. A context that binds settings to the values they hold leaves it the same list while it runs, and once a context ends the list is the one it found, unless a setting was declared or changed meanwhile.
Tolk's settings
Levels and counts are integers; switches are true when their variable holds a nonzero integer.
debug is the verbosity of diagnostics printed on standard output, from DEBUG. 0 prints nothing and each level adds detail. Defaults to 0.
beam is the width of the beam search that picks kernel optimizations, from BEAM. 0 applies hand-coded optimizations instead. Defaults to 0.
jitbeam is the width of the beam search for the kernels of a captured schedule (Jit), from JITBEAM. None, the default, stands for beam's current value.
no_color makes Helpers.colored leave text unchanged, from NO_COLOR. Defaults to false.
use_tc is how kernel optimization uses tensor cores, from TC. 0 never uses them, 1 uses them, 2 shapes the kernel for them without emitting tensor core instructions. Defaults to 1.
tc_select is the tensor core kernel optimization uses, from TC_SELECT: -1 tries the target's tensor cores in order and uses the first that fits, n uses only the n-th. Defaults to -1.
tc_opt is how hand-coded optimizations (Heuristic) fit a kernel to a tensor core, from TC_OPT: 2 pads the kernel's axes to the core's dimensions, 0 and 1 take only kernels those dimensions divide. Defaults to 0.
tc_min_globals is the number of global axes below which tensor core optimization does not upcast its N axis, from TC_MIN_GLOBALS. Defaults to 0.
stage stages a tensor core's operands through shared memory where the target has it, and a decoded operand through a panel on the host (Stage), and gives a staged core its own tile (Heuristic.hand_coded_optimizations), from STAGE. Off, no operand is staged and no core takes the staged tile. Defaults to true.
transcendental is how code generation decomposes transcendental functions into polynomial approximations, from TRANSCENDENTAL: from 2 on, all of them; below, those the target does not support. Defaults to 1.
split_reduceop lets scheduling split a large reduction into two kernels to expose more parallelism, from SPLIT_REDUCEOP. Defaults to true.
no_memory_planner keeps scheduling from reusing the memory of buffers that are no longer needed, from NO_MEMORY_PLANNER. Defaults to false.
cachelevel enables the Helpers.Diskcache when positive, from CACHELEVEL. Defaults to 2.
cachesize is the most bytes the files of the Helpers.Diskcache hold, from CACHESIZE; 0 sets no bound. Defaults to 5 GiB (5368709120), the default of the compiler cache ccache. Raises Invalid_argument when the module is initialised if CACHESIZE is negative.
ignore_beam_cache makes the beam search ignore the results it cached, from IGNORE_BEAM_CACHE. Defaults to false.
disable_fast_idiv keeps code generation from replacing integer division by a constant with a multiplication and a shift, from DISABLE_FAST_IDIV. Defaults to true.
max_kernel_buffers is the number of buffers one kernel may access, from MAX_KERNEL_BUFFERS. 0 uses the device's limit. Defaults to 0.
emulated_dtypes names the data types code generation emulates with other types, as if the target did not support them, from EMULATED_DTYPES: a ,-separated list, empty items dropped. Defaults to [].
default_float names the data type of floating-point values that do not state one, from DEFAULT_FLOAT. Defaults to "float32".
default_int names the data type of integer values that do not state one, from DEFAULT_INT. Defaults to "int32".
parallel is the number of domains compiling kernels and running the beam search, from PARALLEL. 0 works on the calling domain. Defaults to the cores the process may occupy, as rig's host pool counts them, and at most the domains the runtime recommends: on Linux the CPUs of the main thread's affinity mask, at most the CPU quota of its cgroup v2 or any ancestor rounded up; on macOS its physical cores. The count is taken once, when the program starts.
spec is whether the graphs passed between stages are checked against their specifications, from SPEC: 0 checks nothing, and any other value checks them. Defaults to 1.
check_oob makes specification checks prove that memory accesses stay within their buffers, from CHECK_OOB. Defaults to false.
tuple_order makes linearization order nodes of equal priority by their structure, from TUPLE_ORDER. Otherwise they keep their topological order. Defaults to true.
ccache keeps compiled programs and binaries in the Helpers.Diskcache, from CCACHE. Defaults to true.
allow_tf32 lets float32 matrix multiplications use TF32 tensor cores on NVIDIA devices, from ALLOW_TF32. Defaults to false.
A TF32 core rounds each operand to 10 mantissa bits, so a contraction it computes may err past the bound Nx.contract states: setting it chooses that precision explicitly.
scache is where schedules are cached, from SCACHE: 0 nowhere, 1 in memory, 2 or more also in the Helpers.Diskcache, where a compiled schedule is kept whole too. Defaults to 2.
disallow_broadcast makes an elementwise operation on operands of different shapes fail instead of broadcasting them, from DISALLOW_BROADCAST. Defaults to false.
reduceop_split_threshold is how many times as many elements as its output a reduction's input must have for scheduling to split it, under split_reduceop, from REDUCEOP_SPLIT_THRESHOLD. Defaults to 32768.
reduceop_split_size is n such that the first kernel of a split reduction outputs at most 2n elements, from REDUCEOP_SPLIT_SIZE. Defaults to 22.
mv lets hand-coded optimizations lay out matrix-vector products (Heuristic.hand_coded_optimizations), from MV. Defaults to true.
dmc keeps code generation from merging loads, and stores, of consecutive elements into vector accesses (Coalesce.memory_coalescing), from DMC. Defaults to false.
expand_ssa makes C-style code generation (Cstyle) give every value a local variable, from EXPAND_SSA. Otherwise a value read once is written into the expression that reads it. Defaults to false.
beam_padto adds pads of axes to the candidates of the beam search (Search.actions), from BEAM_PADTO. Defaults to false.
beam_uops_max is the number of instructions from which the beam search drops a candidate, none if it is 0 or less, from BEAM_UOPS_MAX. Defaults to 3000.
beam_upcast_max is the most upcast and unrolled lanes a candidate of the beam search may have (Search.get_kernel_actions), from BEAM_UPCAST_MAX. Defaults to 256.
beam_local_max is the most warp and local threads a candidate of the beam search may have, from BEAM_LOCAL_MAX. Defaults to 1024.
beam_min_progress is the microseconds a round of the beam search must gain for the search to go on, from BEAM_MIN_PROGRESS. Defaults to 0.01.
beam_estimate lets the beam search time a program that launches more than 65536 workgroups launching fewer, and scale its time up, from BEAM_ESTIMATE. Defaults to true.
beam_strict_mode makes the beam search raise what the compilation of a candidate raises, but Failure, instead of dropping the candidate, from BEAM_STRICT_MODE. Defaults to false.
beam_log_surpass_max prints the candidates the beam search drops for exceeding beam_upcast_max, beam_local_max or beam_uops_max, from BEAM_LOG_SURPASS_MAX. Defaults to false.
beam_debug is the verbosity of the beam search's diagnostics, from BEAM_DEBUG: from 1, the kernel searched, the candidates whose timing failed and the result; from 2, every candidate timed. Defaults to 0.
cc is the program Compiler_cpu.clang runs, from CC, read when the compiler is made. Defaults to "clang".
cuda_path is the directory of the CUDA toolkit whose headers Compiler_cuda.nvrtc includes, from CUDA_PATH, read when the compiler is made. "", the default, searches the usual directories.
rocm_path is the directory of the ROCm installation whose comgr library Compiler_amd.hip loads, from ROCM_PATH. Defaults to "/opt/rocm".
assert_compile makes compiling a source whose binary no disk cache table holds raise (Renderer.Compiler.compile_cached), from ASSERT_COMPILE. A beam search's candidates compile through that table too, so a candidate whose binary is not kept raises, which drops it unless Setting.beam_strict_mode holds (Search.beam_search). Defaults to false.
rewrite_stack_limit bounds the work list of Ops.graph_rewrite, from REWRITE_STACK_LIMIT. Defaults to 250000.
debug_linearize prints each node linearization places, with its position, operation, ranges and priority (Linearizer.linearize), from DEBUG_LINEARIZE. Defaults to false.