Skip to content

Add CUDA device-pointer plane_codec ABI with explicit selection - #2

Merged
khwstolle merged 1 commit into
masterfrom
feat/gpu-plane-codec
Aug 16, 2026
Merged

Add CUDA device-pointer plane_codec ABI with explicit selection#2
khwstolle merged 1 commit into
masterfrom
feat/gpu-plane-codec

Conversation

@khwstolle

Copy link
Copy Markdown
Owner

Summary

Adds a device-pointer plane_codec ABI (encode and decode) so a
GPU-resident codec can operate on device memory directly, supplied
entirely by a third-party plugin. The new symbol pair mirrors the
existing hardware_backend_v1_* CUDA ABI but attaches to the
plane_codec kind, so it participates in container framing the same
way a built-in codec does.

Why

The existing plane_codec dispatch path assumes a contribution's
data already lives in host memory. A GPU-resident codec needs its
compressed and decompressed buffers to stay on-device: routing every
plane through a host round trip would erase most of the reason to use
a GPU codec at all. This adds the missing piece, a symbol pair that
takes device pointers directly, plus the plumbing to reach it from
Rust, Python, and the CLI.

What changed

ABI and dispatch (Rust core)

  • Two new CUDA C-ABI symbols (encode, decode) attached to the
    plane_codec kind. Encode reports its required output size
    explicitly, since the existing decode_rc error code cannot
    round-trip an arbitrary byte count.
  • A DispatchedPlaneCodecCuda trait and native adapter bridge the
    ABI, resolved through a capability-gated router mirroring the
    existing hardware-backend router's caching and hardware_class
    gating.
  • Third-party encode becomes reachable when a codec is explicitly
    selected by name or id. It stays unreachable through the automatic
    trial-encode search, whose return shape the flat third-party ABI
    cannot express.
  • A name/id resolver (resolve_codec_selector) turns a human-typed
    selector into a canonical id, erroring loudly and naming every
    candidate on an ambiguous or unknown name, rather than picking one
    silently.
  • A Rust-only integration test pins that decoding through this router
    never needs the Python bindings.

Python bridge and surface

  • A PyO3 bridge exposes the encode/decode pair to Python, sharing
    DLPack tensor parsing, a buffer-protocol fallback, and
    device-ordinal agreement checking with the existing hardware-backend
    bridge rather than duplicating them.
  • CompressionConfig/DecompressionConfig gain codec/device
    fields; compression gains a guard against a mismatch between an
    explicit device and an input tensor's own device.
  • The CLI gets --codec/--device flags, wired through every
    config-construction path each command reaches.
  • Setting codec or device on a config with no dispatch path to
    consume it raises immediately, naming the field, instead of
    silently falling back to the automatic codec search or CPU-only
    decode.

Testing

  • cargo test --workspace: all passing, clippy clean.
  • pytest across the full suite (maturin develop build): all
    passing; CUDA-dependent paths skip without a GPU.

…d Python/CLI surface

Adds a device-pointer plane_codec ABI (encode and decode) so a
GPU-resident codec can be supplied by a third-party plugin, reachable
by explicit codec selection from Rust, Python, and the CLI.

- Two new CUDA C-ABI symbols mirror the existing hardware_backend_v1_*
  pair, attached to the plane_codec kind; encode reports its required
  buffer size explicitly rather than through decode_rc's lossy -2
  return.
- DispatchedPlaneCodecCuda trait and native adapter, resolved through
  a capability-gated PlaneCodecCudaRouter (native flavor only, mirrors
  HardwareBackendRouter's cache and hardware_class gating).
- Third-party encode, previously refused because the trial-encode loop
  cannot consume its flat ABI return shape, becomes reachable under
  explicit selection.
- resolve_codec_selector turns a name or canonical id into a
  CanonicalId; an ambiguous or unknown selector is a loud error naming
  every candidate.
- A Rust-only integration test pins that the decode path needs no
  Python bindings.
- A PyO3 bridge exposes plane_codec_encode_cuda/decode_cuda, sharing
  DLPack parsing, buffer-protocol fallback, and device-ordinal
  checking with the existing hardware-backend bridge.
- CompressionConfig/DecompressionConfig gain codec/device fields;
  Compressor gains a device-mismatch guard. CLI --codec/--device flags
  are wired through every config-construction site each command
  reaches.
- Setting codec or device on a config with no dispatch path to consume
  it raises immediately, naming the field, instead of silently doing
  the wrong thing.
@khwstolle
khwstolle merged commit 90fe3ed into master Aug 16, 2026
11 of 12 checks passed
@khwstolle
khwstolle deleted the feat/gpu-plane-codec branch August 16, 2026 19:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant