Skip to content

runtime.md

Latest commit

 

History

History
102 lines (83 loc) · 4.26 KB

runtime.md

File metadata and controls

102 lines (83 loc) · 4.26 KB
Raw
title Runtime Component
audience developers, maintainers, contributors
prerequisites contributor architecture guide, completed native handle policy
related ../architecture.md, index.md, policy.md, compiler.md, pipeline.md
status maintained
publication reviewed

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
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.
Evidence What it establishes
Allocatable runtime tests Allocation state, operations, descriptor handoffs, and NumPy views.
Pointer runtime tests Association, nullification, pointer descriptors, and views.
Memory-management runtime tests Owner retention, release, and array handoffs.
Native-support tests Bundled payload discovery and installation inputs.
Compiled runtime compatibility The payload and Python runtime working through a real extension.

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.