UtilsShared utilities of arrayjit: the global settings and configuration reading (command line, environment, config file, profiles) with its key registry and cache-identity classification, debug-artifact and log paths with their startup cleanup, routine-log capture, C-stderr and device-init safeguards, and small list, sexp and float-rendering helpers.
Counts one completed backend compile (code generation or deferred device compile) on this domain.
The number of backend compiles completed on this domain so far; see count_backend_compile.
type settings = {mutable log_level : Base.int;mutable debug_log_from_routines : Base.bool;If the debug_log_from_routines flag is true _and_ the flag log_level > 1, backends should generate code (e.g. fprintf statements) to log the execution, and arrange for the logs to be emitted via ppx_minidebug.
mutable output_debug_files_in_build_directory : Base.bool;Writes compilation related files in the build_files subdirectory of the run directory (additional files, or files that would otherwise be in temp directory). When both output_debug_files_in_build_directory = true and log_level > 1, compilation should also preserve debug and line information for runtime debugging.
mutable fixed_state_for_init : Base.int Base.option;mutable print_decimals_precision : Base.int;When rendering arrays etc., outputs this many decimal digits.
*)mutable check_half_prec_constants_cutoff : Base.float Base.option;If given, generic code optimization should fail if a half precision FP16 constant exceeds the cutoff.
*)mutable default_prng_variant : Base.string;The default variant of threefry4x32 PRNG to use. Options: "crypto" (20 rounds) or "light" (2 rounds). Defaults to "light" for better performance.
*)mutable large_models : Base.bool;If true, use uint64 for indexing arithmetic. If false, use uint32 for indexing arithmetic. This affects all backends' kernel index parameters and local index variables, and gates the per-pool offset width (uint32 caps a pool at 4 GB; see the pool allocator). Decoupled in intent from element indexing within a single tensor, though both currently follow it.
*)}Process-wide runtime settings, initialized from the configuration.
val sexp_of_settings : settings -> Sexplib0.Sexp.tval settings : settingsThe global settings record, set from the configuration at startup; see restore_settings.
The configuration keys this process has read through the configuration getters so far.
Every recognized configuration key; a source naming any other key is warned about.
type config_key_class = | AggregateSelects values for other keys rather than acting itself; those keys carry the classification.
*)| Code_borneChanges the lowered code or its placements, hence the canonical digest (Ir.Schedule_cache.digest, the "digest" key component) that every cache key starts with. Nothing to add: the code is the identity.
| Keyed of Base.stringNot fully captured by the lowered code, so it has to be carried explicitly — by this named component of Ir.Schedule_cache.key_components. This is the class gh-ocannl-568 was an omission from.
| Search_shapingShapes which schedule a search proposes, times or crowns, but not what a crowned one means or how fast it then runs: a saved schedule carries its own ops and replay re-derives nothing from these. Two processes differing only here may find different winners; each is a valid winner for the other.
*)| Placement_shapingSteers Train.tune_placements above any single search: which placement programs it searches (each a different program, keyed on its own digest) and which of them ships. No single Autotune.tune call reads it, so it is neither in the cache key nor in the search trajectory's identity (config_class_fingerprint of Search_shaping): a search's timed record is the same record whatever the level above it was told (gh-ocannl-1192).
| Untimed_modelSteers the untuned regime's untimed pick: Autotune.model_default, the pick by the analytic cost model -- whether a recipe's untuned compile routes through it, and how widely it searches. It times nothing and neither replays nor stores a schedule-cache entry, and no Autotune.tune call reads these keys, so they are neither in the cache key nor in the search trajectory's identity (config_class_fingerprint of Search_shaping): a search's timed record is the same record whatever the untuned regime beside it was told (gh-ocannl-1241). Autotune.seeded_default's keys started here and are Search_shaping since the search seeds its plan first (gh-ocannl-1388).
| Execution_neutralHost-side behavior only: logging, debug artifacts, directories, validation and error reporting, allocation layout, launch mechanics. Nothing a kernel does depends on it.
*)What a configuration key does to the identity a compilation cache keys on.
val config_key_classification :
(config_key_class * Base.string * Base.string Base.list) Base.listThe class of every known key, as (class, reason, keys) groups.
val classify_config_key :
Base.string ->
(config_key_class * Base.string) Base.optionThe class and reason recorded for a key, or None when it is unclassified.
Parses true/1 or false/0, any case, stripped; raises Invalid_argument naming arg_name.
type config_value_kind = | Flag| IntegerInt.of_string of the stripped text
| Float_numberFloat.of_string of the stripped text, NaN excluded
| Keyworda mode name, stripped and lowercased, such as auto; which names are modes is the read site's ~parse (registered_keyword), so the kind itself refuses nothing
| Textstripped text, such as a path
*)| Positive_float_or_unsetan override that only a positive float sets: empty and non-positive numbers mean "not overridden", as Autotune.peak_override reads it
| Float_at_least of {}a float clamped up to floor, NaN excluded: every spelling the read site cannot tell apart from another canonicalizes alike, so the read (Sketch_families.pad_waste_max) and the fingerprint share one owner of the clamp
How a key's value parses: the one parse shared by the typed getters and the class fingerprint.
val canonical_config_value :
config_value_kind ->
Base.String.t ->
Base.String.t Base.Option.tThe value's canonical spelling under the kind, or None when it does not parse as one.
val config_key_defaults :
(Base.string * (config_value_kind * Base.string)) Base.listThe built-in default and value kind of each key whose resolved value an identity renders.
val registered_config_default :
Base.string ->
(config_value_kind * Base.string) Base.optionThe key's config_key_defaults row, if it has one.
Whether to trace each setting's source to stderr; unused in-tree, a switch a program may flip.
Whether to print each resolved setting to stderr as JSON; unused in-tree, a switch to flip.
The environment spelling of a config key: OCANNL_ followed by the key in uppercase.
Whether the runtime's getenv matches names case-insensitively (native Windows, not Cygwin).
type env_var_class = | Env_not_addressednot ocannl-prefixed: someone else's variable entirely
| Env_reserved of Base.stringin a reserved non-configuration namespace, named by its prefix
*)| Env_config_key of Base.string| Env_unread_spelling of Base.stringa known key, spelled in a way nothing reads: dashed, or not fully uppercase where case matters. A configuration ERROR rather than a warning -- see unread_env_vars.
| Env_unread_reserved of Base.stringin a reserved namespace, in a casing its reader does not consult
*)| Env_unknown_key of Base.stringaddressed to the configuration, naming no key
*)What an environment variable name is to OCANNL's configuration.
val classify_env_var :
?case_insensitive:Base.bool ->
Base.String.t ->
env_var_classClassifies a variable name; case_insensitive defaults to env_names_case_insensitive.
Whether the test suite's ambient record carries the variable: config-addressed, not the backend.
Non-empty config-addressed variables nothing reads, as sorted (name, is_fatal, reason).
A key's dash-led command-line spellings: prefixed, then prefix-free unless qualified_only.
Argument prefixes: each cmdline_var_names spelling followed by _, -, = or nothing.
A configuration token's shape and its normalized key.
The prefixes that can begin a qualified command-line configuration token.
type config_token_parse = | Accepted of config_token| Ambiguous of {explicit : config_token Base.option;candidates : config_token Base.list;fallback : config_token;}| Rejected of {reason : config_token_rejection;qualified : config_token Base.option;}A lexed token: one reading, longest-first candidate readings, or a rejection.
*)val parse_config_token :
?documentation:Base.bool ->
Base.String.t ->
config_token_parseLexes a token without consulting known_config_keys; documentation admits bare assignments.
Keys whose prefix-free command-line spellings are never claimed, such as profile.
val cmdline_arg_value :
?qualified_only:Base.bool ->
Base.String.t ->
Base.String.t ->
Base.String.t Base.optioncmdline_arg_value n arg is arg's value for key n, unless a longer registered key owns arg.
val read_cmdline_var :
?qualified_only:Base.bool ->
Base.String.t ->
(Base.String.t * Base.String.t) Base.optionThe first command-line value for a key, with the Sys.argv element it came from.
Whether a raw command-line argument addresses some known key under any spelling read.
The environment value for a key, with the variable's name; an empty value counts as unset.
val describe_config_level : config_level -> Base.stringA level's name in prose, such as "the commandline".
type config_source = | From_cmdline of Base.stringthe matching Sys.argv element
| From_env of Base.stringthe matching environment variable
*)| From_config_file| From_profile of config_level * Base.stringthe level that picked the profile, and its name
*)| From_defaultval config_source_label : config_source -> Base.stringA short provenance tag, such as "environment" or "profile 'reproducible' via the commandline".
val describe_config_source :
value:Base.string ->
default:Base.string ->
config_source ->
Base.stringThe sourcing-trace line for a resolved value, or for the default used when nothing set it.
val resolve_config_value :
cmdline:('a -> ('b * Base.string) Base.Option.t) ->
env:('a -> ('b * Base.string) Base.Option.t) ->
file:('a -> 'b Base.Option.t) ->
profile:(config_level * Base.string * ('a -> 'b Base.Option.t)) Base.option ->
default:'b ->
arg_name:'a ->
'b * config_sourceThe precedence walk: each level's explicit value, then the profile picked there, else default.
val parse_config_lines :
source:Base.String.t ->
Base.String.t Base.List.t ->
(Base.String.t * Base.String.t) Base.List.tParses ocannl_config-syntax lines into (key, value) pairs; source names them in errors.
The settings of the ocannl_config file found up from the working directory, if any.
The embedded profile payloads by name, each a partial ocannl_config text.
val parse_profile_payload :
name:Base.string ->
Base.String.t ->
(Base.String.t, Base.String.t) Base.Hashtbl.tParses a profile payload into a table; fails on an unknown or profile-ineligible key.
val resolve_profile_selection :
cmdline:(Base.string -> (Base.String.t * Base.string) Base.Option.t) ->
env:(Base.string -> (Base.String.t * Base.string) Base.Option.t) ->
file:(Base.string -> Base.String.t Base.Option.t) ->
Base.String.t * config_sourceThe normalized profile name picked by ordinary source precedence, with its source.
val active_profile :
(config_level * Base.String.t * (Base.String.t, Base.String.t) Base.Hashtbl.t)
Base.Option.tThe profile picked for this run, if any: its level, name and parsed payload.
One resolution of one setting: the key, the raw value settled on, and where it came from.
A JSON string literal: quote, backslash and control characters escaped, other bytes as they are.
val config_record_to_json : config_record -> Base.stringThe one-line JSON object (schema version 1) the log_config_json stream prints for a record.
val resolved_config : Base.unit -> config_record Base.List.tEvery setting this process has resolved so far, in first-resolution order.
val registered_getter_of_kind : config_value_kind -> Base.stringThe name of the typed getter reading keys of a kind, such as "registered_int".
val get_global_arg_with_source :
default:Base.String.t ->
arg_name:Base.string ->
Base.String.t * config_sourceget_global_arg with the value's source; refuses a key with a config_key_defaults row.
The value of config key arg_name from the command line, environment, config file or profile, else default.
Raised by a typed getter when a setting's value does not parse as its key's kind.
A registered Flag key's value, defaulting to its config_key_defaults row.
A registered Integer key's value; raises Invalid_config_value on unparsable text.
A registered Float_number key's value; raises Invalid_config_value on unparsable text.
A registered Positive_float_or_unset key's value; None when empty or not positive.
A registered Float_at_least key's value, clamped up to its floor.
val registered_keyword :
arg_name:Base.string ->
expected:Base.string ->
parse:(Base.String.t -> 'a Base.option) ->
'aA registered Keyword key's mode by parse of the lowercased value; expected lists the modes.
val profile_key_source :
Base.String.t ->
(Base.String.t * config_source) Base.optionA key's resolved value and source, None when nothing sets it; neither logged nor recorded.
val config_class_fingerprint :
?resolve:(key:Base.String.t -> Base.String.t -> Base.string) ->
?reads:(Base.string -> Base.bool) ->
config_key_class ->
Base.String.tkey=value; for each read key of the class resolved off its default: the class's identity.
val profile_payload_sources :
Base.String.t ->
(Base.String.t * (Base.String.t * config_source) Base.option) Base.List.tEach key of the named profile's payload with its profile_key_source resolution.
val inherited_env_key_sources :
Base.unit ->
(Base.String.t * Base.string * (Base.String.t * config_source) Base.option)
Base.List.tEach environment variable spelling a key, with the key and where it actually resolved from.
A boolean setting: get_global_arg parsed by bool_of_config_string.
The operating system's id of this process (unlike Unix.getpid on Windows).
module Artifacts_lock : sig ... endThe advisory lock that keeps a sibling's startup cleanup off this process's artifacts.
The debug-artifact directory build_files/<prefix>/, created if missing.
The path of an artifact in build_files_dir; shields this process's artifacts from cleanups.
The file extension of a dynamically loaded library on this platform.
The OS id of a process blocking an exclusive lock on the file: 0 if none, -1 if unknown.
Whether a process with this OS id is running; one that cannot be queried counts as running.
A random token drawn once per process, telling apart processes that report the same OS id.
The most bytes of a kernel name that an owner-recording artifact's file name carries.
The cleaned kernel name, cut at a UTF-8 boundary with a digest suffix if over the limit.
val kept_library_name :
pid:Base.int ->
nonce:Base.string ->
run_id:Base.int ->
Base.String.t ->
Base.stringThe owner- and run-recording file name of a library kept in the build directory.
The prefix every OCANNL temporary library's file name opens with.
val temp_library_prefix :
pid:Base.int ->
nonce:Base.string ->
run_id:Base.int ->
Base.String.t ->
Base.stringThe owner- and run-recording Filename.temp_file prefix of a temporary library.
Seconds since its last write before a startup removes a gone owner's temporary library.
val parse_kept_library_name : Base.String.t -> kept_library Base.optionInverts kept_library_name; None for any other file name.
val parse_temp_library_name : Base.String.t -> kept_library Base.optionThe owner and compile of a temp_library_prefix-named library; None for any other name.
val owned_artifact_file :
run_id:Base.int ->
extension:Base.string ->
Base.String.t ->
Base.String.tWhere this process keeps an artifact of a kernel's compile run_id, under an owner-recording name.
Where this process keeps the library of a kernel's compile run_id.
The log directory log_files/<prefix>/, created if missing, prefixed as build_files_dir.
The path of a log in log_files_dir; shields this process's logs from sibling cleanups.
The ppx_minidebug runtime, configured from the debug-logging settings.
Resets settings to the values the configuration gives.
Whether compilation keeps debug information: debug files on and log_level > 1.
Whether kernels log their execution: debug_log_from_routines on and log_level > 1.
Points C stderr at its own dup of the real stderr; the stub behind c_stderr_detached, unused in-tree, so a caller that took over fd 2 can redo the detachment.
Whether C stderr was detached at startup, so foreign C chatter skips a later fd 2 redirect.
Whether this C runtime's stderr can be replaced at all (glibc, Darwin).
Whether the host is macOS (Darwin), as this library's build target says (gh-ocannl-1741): the one predicate behind the cc backend's kernel link flags and the tests gating on Darwin, read without shelling out to uname.
Whether the host is arm64 macOS, which refuses to map unsigned code (gh-ocannl-1741).
Collapses ROCm's per-event C stderr lines into a count; the stub behind c_stderr_noise_collapsed, unused in-tree.
Whether ROCm's per-event C stderr chatter is collapsed, installing the filter when forced.
What bounded_exit_teardown did with one resource.
The exit_stream_teardown_timeout used when the setting is absent or not a finite number.
One resource for bounded_exit_teardown; what names it in diagnostics.
val bounded_exit_teardown :
exit_teardown_resource Base.list ->
exit_teardown_outcome Base.listTears down each resource once idle, all under one exit timeout; never raises.
Whether this build can arm the device-init deadline at all (not on Windows).
The fixed start of the diagnostic the device-init deadline writes.
Test-only: run inside with_device_init_deadline's guarded region, before the guarded call.
Test-only: run right before a GPU backend's one-time driver initialization call.
Runs a device init or query under device_init_deadline seconds, dying by SIGALRM past it.
A fresh run id per call, unique across the process's backends.
val union_find :
equal:('a -> 'a -> Base.bool) ->
('a, 'a, 'b) Base.Map.t ->
key:'a ->
rank:Base.Int.t ->
'a * Base.Int.tThe root of key in a parent-pointer map, with rank plus the number of steps taken.
val union_add :
equal:('a -> 'a -> Base.bool) ->
('a, 'a, 'b) Base.Map.t ->
'a ->
'a ->
('a, 'a, 'b) Base.Map.tMerges the classes of two elements in a parent-pointer map.
Filters the list keeping the first occurrence of each element.
val sorted_diff :
compare:('a -> 'b -> Base.int) ->
'a Base.List.t ->
'b Base.list ->
'a Base.List.tThe multiset difference of two lists sorted in increasing order.
Removes the first element of the list equal to the given one.
Prepends elem to a sexp list, or pairs it with an atom.
Whether elem equals the atom, or is a member of the list.
Strips leading zeros from a float rendering's exponent, so it does not depend on the C runtime.
A decimal floating literal that parses back to exactly the double; non-finite ones as words.
module Lazy : sig ... endBase.Lazy plus ppx_minidebug's sexp converters.
Whether something is skipped, required, or optional with a callback for when it is missing.
val sexp_of_requirement : requirement -> Sexplib0.Sexp.tval output_to_build_file :
fname:Base.String.t ->
(PPrint.ToChannel.document -> Base.unit) Base.optionWhen debug files are on, truncates the build file fname and returns a printer appending to it.
An error the user's program or configuration caused, rather than a bug.
An open file for generated code: its path, its channel, and the flush-and-close.
val open_build_file :
base_name:Base.String.t ->
extension:Base.String.t ->
build_file_channelOpens base_name ^ extension in the build directory when debug files are on, else a temp file.
The prefix marking a routine log line on stdout for capture_stdout_logs to collect.
Registers a handler of the captured lines carrying prefix (prefix removed).
Runs f, handing stdout's log lines to the registered processors, then clearing them.
Runs a logged GPU launch (then drain) in a capture window when stream-file logs need one.
val log_debug_routine_logs :
log_contents:Base.string Base.List.t ->
stream_name:Base.String.t ->
Base.unitAppends routine log lines to the stream's log file, or to the debug trace when that is off.
log_debug_routine_logs of a file's lines, then removes the file.
The digest of a well-formed, nonzero IOPlatformUUID found in ioreg output.
On macOS, the host's hashed platform UUID and, if available, the OS build version.
The headers a C or C++ text includes by #include <...>, in order.
A found directory as a capability record: resolved path, plus missing headers or their digest.
Re-exports the shared datatypes: Set_O, safe_lazy, Tree_map, map-ref helpers, ...
module Set_O : sig ... endval safe_lazy : Base.string -> (Base.unit -> 'a) -> 'a safe_lazyval safe_force : 'a safe_lazy -> 'aval is_safe_val : 'a safe_lazy -> boolval hash_fold_safe_lazy :
'a ->
Base__.Ppx_hash_lib.Std.Hash.state ->
'b safe_lazy ->
Base__.Ppx_hash_lib.Std.Hash.stateval sexp_of_safe_lazy : ('a -> Base.Sexp.t) -> 'a safe_lazy -> Base.Sexp.tmodule Tree_map : sig ... endA persistent map implemented as a balanced binary tree. The sexp_of function preserves and displays the tree structure.
module Cpu_topology : sig ... endCPU topology facts for the worker-pool uniformity policy.
module Atomic_file : sig ... endPublishing a file so that no reader ever observes a half-written one.
module Host_load : sig ... endHost CPU accounting, telling a co-tenant apart from a routine's own variance.