Skip to content

[Feature] Replace scattered runtime env-var knobs with a structured config API #834

@lyfne123

Description

@lyfne123

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions