Summary
The simpler runtime currently exposes its host-side tuning/config knobs only as
individual environment variables, read via scattered std::getenv calls in
runtime_maker.cpp. Today this includes at least:
| Env var |
Meaning |
Constraint |
PTO2_RING_HEAP |
per-ring GM heap size |
power-of-2, >= 1024 |
PTO2_RING_TASK_WINDOW |
ring task window size |
power-of-2, >= 4 |
PTO2_RING_DEP_POOL |
dependency pool size |
>= 4 |
PTO2_READY_QUEUE_SHARDS |
AICPU ready-queue shard count |
[1, MAX_AICPU_THREADS] |
PTO2_ORCH_TO_SCHED |
orchestrator->scheduler transition flag |
bool |
Requesting a more ergonomic, programmatic configuration mechanism (a config
struct / API, or Python-level kwargs/config object) so callers don't have to
export environment variables to tune the runtime.
Motivation / Use Case
Configuring runtime parameters through environment variables is awkward in
practice:
- Hard to discover: the full set of knobs, their valid ranges, and
power-of-2 constraints are only visible by reading the C++ source; there is no
single declared schema.
- Inconvenient to set: tuning requires
export PTO2_RING_HEAP=... before
every run, and per-run or per-callable values can't be expressed cleanly. CI,
benchmarks, and notebooks all have to wrangle the process environment.
- Error-prone: invalid values are silently ignored (warn + fall back to
default), and there's no typed validation at the call site.
- Not composable: you cannot configure two runtimes differently within the
same process, since env vars are process-global.
A structured config would make these parameters self-documenting, validated at
the API boundary, and settable per-runtime/per-run.
Proposed API / Behavior
Expose a typed config object that the runtime accepts directly, e.g.:
cfg = RuntimeConfig(
ring_heap=2048, # PTO2_RING_HEAP
ring_task_window=8, # PTO2_RING_TASK_WINDOW
ring_dep_pool=8, # PTO2_RING_DEP_POOL
ready_queue_shards=4, # PTO2_READY_QUEUE_SHARDS
orch_to_sched=True, # PTO2_ORCH_TO_SCHED
)
runtime.run(callable, args, config=cfg)
Suggested behavior:
- Validation (range / power-of-2) raises a clear error instead of silent fallback.
- Precedence: explicit config arg > environment variable > compile-time default,
so existing env-var usage keeps working for backward compatibility.
Alternatives Considered
- Keep env vars only — current state; the ergonomics problems above remain.
- Config file (TOML/JSON) — better than env vars for discoverability, but a
typed in-process API composes better with existing call sites.
Additional Context
Summary
The simpler runtime currently exposes its host-side tuning/config knobs only as
individual environment variables, read via scattered
std::getenvcalls inruntime_maker.cpp. Today this includes at least:PTO2_RING_HEAPPTO2_RING_TASK_WINDOWPTO2_RING_DEP_POOLPTO2_READY_QUEUE_SHARDSPTO2_ORCH_TO_SCHEDRequesting a more ergonomic, programmatic configuration mechanism (a config
struct / API, or Python-level kwargs/config object) so callers don't have to
export environment variables to tune the runtime.
Motivation / Use Case
Configuring runtime parameters through environment variables is awkward in
practice:
power-of-2 constraints are only visible by reading the C++ source; there is no
single declared schema.
export PTO2_RING_HEAP=...beforeevery run, and per-run or per-callable values can't be expressed cleanly. CI,
benchmarks, and notebooks all have to wrangle the process environment.
default), and there's no typed validation at the call site.
same process, since env vars are process-global.
A structured config would make these parameters self-documenting, validated at
the API boundary, and settable per-runtime/per-run.
Proposed API / Behavior
Expose a typed config object that the runtime accepts directly, e.g.:
Suggested behavior:
so existing env-var usage keeps working for backward compatibility.
Alternatives Considered
typed in-process API composes better with existing call sites.
Additional Context
src/{a2a3,a5}/runtime/tensormap_and_ringbuffer/host/runtime_maker.cpp(
parse_env_uint64, ~lines 56, 226-266).