Runtime Component¶

Purpose And Boundaries¶

prik/runtime/ provides Python objects used after a generated extension is imported and the native support compiled into generated bindings. It validates the operations and descriptor metadata supplied by the extension, retains required owners, and exposes the NumPy views permitted by completed policy.

Runtime code enforces decisions already made by policy and represented in the wrapper plan. It does not decide ownership, invent a missing operation, or select a different view behavior from local descriptor facts.

A Native Array Handle At Runtime¶

generated dispatcher + completed capabilities + native backend
  + dtype, rank, ownership, and view policy
  -> NativeArrayHandleBase validation and owner retention
  -> AllocatableArray or PointerArray
  -> state, lifecycle, association, and to_numpy() operations

The dispatcher and capabilities come from the completed wrapper plan. The runtime validates them, retains the owners required for a live NumPy view, and uses the generated native backend for descriptor and lifecycle work. It never infers an operation or ownership rule from the declaration alone.

Local Structure¶

prik/runtime/
├── handles.py
└── native_support/
    ├── prik_binding.h
    └── LICENSE

• handles.py contains the Python runtime. NativeArrayHandleBase validates common metadata and completed capabilities. AllocatableArray adds allocation state, resize, and deallocation; PointerArray adds association, nullification, allocation, resize, and deallocation when supplied.
• native_support/prik_binding.h contains header-only CPython/NumPy conversion, descriptor, validation, capsule, and release support. Change it only with its generated C users and prik/compiler/native_support.py.
• native_support/LICENSE is distributed with the native payload.

to_numpy() returns None for absent storage and otherwise applies the completed view policy. Native argument handoff is performed in the binding against the planned array contract. A returned NumPy array is a view of native storage; a caller that needs independent storage must copy it.

Run The Handle Demonstration¶

python3 prik/runtime/handles.py

if __name__ == "__main__":
    # Generated extensions supply one dispatcher and its completed capabilities.
    state = {"array": np.array([1.0, 2.0, 3.0], dtype=np.float64)}

    def resize(*extents: np.int64) -> None:
        state["array"] = np.zeros(tuple(int(extent) for extent in extents), dtype=np.float64)

    operations = {
        "allocated": lambda: True,
        "shape": lambda: state["array"].shape,
        "to_numpy": lambda: state["array"],
        "resize": resize,
    }

    def invoke(operation: str, args: tuple[Any, ...]) -> Any:
        return operations[operation](*args)

    array = _native_array_handle_from_generated_dispatch(
        "allocatable",
        np.float64,
        1,
        invoke,
        operations,
    )

    print(f"Runtime handle: {type(array).__name__}")
    print(f"Descriptor kind: {array.descriptor_kind}")
    print(f"Initial view: {array.to_numpy().tolist()}")
    array.resize(4)
    print(f"Resized shape: {array.shape}")
    print(f"Generated resize received NumPy extents: {state['array'].shape == (4,)}")

Runtime handle: AllocatableArray
Descriptor kind: allocatable
Initial view: [1.0, 2.0, 3.0]
Resized shape: (4,)
Generated resize received NumPy extents: True

The example creates an allocatable handle, reads its live NumPy view, and resizes it. The compiler installs the native header into a generated binding_support/ directory.

Change Routes And Evidence¶

• Change handle protocol, validation, retention, views, or adapters in handles.py.
• Change the native payload together with its generated users and prik/compiler/native_support.py.
• Update the native backend ABI version when its callback contract or record meaning changes.
• Complete new ownership, lifecycle, operation, or view policy before planning rather than selecting it in runtime code.

An outstanding zero-copy NumPy view cannot be revoked after native reallocation, deallocation, or pointer reassociation. Users must discard or copy such views before changing the native storage.