Flight4s

Flight4s is a Scala 3 GPU programming platform built under the GPUFlight organization.

The first implementation is CUDA-first: its typed DSL and IR generate inspectable CUDA C++ for compilation with NVRTC. The project name deliberately does not bind the overall platform to one GPU vendor, leaving room for future HIP or Metal backends after the CUDA architecture and backend boundary are proven.

Status

Flight4s is pre-alpha and under active design. The current implementation provides:

• CUDA scalar type witnesses, including F16, BF16, and FP8 formats;
• typed expressions, places, statements, control flow, and reductions;
• distinct module constants, rank-aware kernel shared arrays, and lexical local arrays;
• module and kernel validation for memory ownership, scope, access, and static literal bounds on constant, local, and shared arrays;
• typed kernel signatures and compile-time-checked launch argument tuples;
• ordered CUDA ABI descriptors and exact scalar/device-pointer byte encoding;
• aligned direct launch storage with stable descriptor codes and slot offsets;
• validated 1D, 2D, and 3D grid/block configuration with optional clusters;
• a JNI-facing launch request with reference metadata validation;
• a C++ JNI launcher with native ABI validation and void** construction;
• ordinary and clustered cuLaunchKernelEx execution without implicit sync;
• structural validation independent of code generation;
• validation-gated deterministic CUDA C++ source generation;
• inspectable generated module and typed kernel artifacts with explicit C++20 compiler options;
• explicit compute-capability targets and ordered NVRTC option resolution;
• native NVRTC compilation with inspectable PTX, compiler logs, compiler version, target, and exact generated-source provenance;
• structured NVRTC compilation failures that retain source, options, and logs;
• public CudaContext, CudaModule, CudaStream, CudaEvent, and typed CudaFunction[Args] resources;
• retained CUDA primary contexts with compute-capability discovery;
• typed context-owned CudaDeviceBuffer[T] allocation and deterministic AutoCloseable cleanup;
• typed context-owned CudaPinnedBuffer[T] allocation backed by reusable page-locked host memory;
• exact whole-buffer and partial-range synchronous transfers between same-context pinned and device buffers;
• context-owned completion events with recording, non-blocking queries, host synchronization, and same-context stream dependencies;
• exact whole-buffer synchronous host/device copies through native-order direct staging storage;
• host codecs for every current scalar type, preserving raw F16, BF16, and FP8 representations;
• context-owned default-mode and non-blocking CUDA streams with explicit synchronization;
• whole-buffer and partial-range asynchronous pinned-memory transfers on explicit streams;
• reverse-creation-order cleanup across context-owned modules, buffers, and streams;
• typed function resolution that preserves the generated kernel signature and retains Driver-reported resource attributes;
• typed CudaFunction.launch submission from the original KernelInvocation[Args];
• source-compatible default-stream launch and same-context explicit-stream launch with automatic in-flight resource retention;
• explicit context synchronization through CudaContext.synchronize();
• launch-time kernel provenance and dynamic shared-memory validation;
• context-scoped cuLaunchKernelEx with structured CUDA Driver failures;
• structured CUDA Driver failures with PTX JIT information and error logs;
• CUDA declaration emission for constants, global parameters, static and dynamic shared memory, and lexical local memory;
• a generated, compiled, and executed typed vectorAdd integration test;
• a generated, compiled, and executed dynamic shared-memory block reduction with CPU-reference verification;
• golden-source tests, native NVRTC contract tests, JNI integration tests, and an optional nvcc compilation test.

Execution and resource lifetimes

• Launches: Typed launches are asynchronous on CUDA's default stream or an owned explicit stream. CudaContext.synchronize() waits for all context work, while CudaStream.synchronize() waits for one explicit stream; launch never synchronizes implicitly.
• Copies: Device-buffer copies are whole-buffer and synchronous through temporary pageable direct staging. Reusable CudaPinnedBuffer[T] storage provides a page-locked synchronous path without repeated direct-buffer allocation; its same-context device-buffer transfers also support explicit-stream cuMemcpyHtoDAsync and cuMemcpyDtoHAsync operations.
• Events and dependencies: CudaEvent.record, query, and synchronize provide completion markers, while CudaStream.waitFor establishes GPU-side stream dependencies. Pinned/device source and destination ranges are independently validated.
• In-flight work: Asynchronous copies and launches retain participating pinned buffers, device buffers, and modules through stream, event, or context completion. Explicit-stream work completes through stream, event, or context completion; default-stream launches complete through context synchronization. Closing an in-flight resource makes it unavailable immediately and defers native release.
• Teardown: Pinned host reads and writes are rejected during transfers. A stream synchronizes tracked work before destruction, and a context waits for pending default-stream launches before native teardown.

Diagnostics and source locations

NVRTC diagnostics retain generated CUDA locations and map them to the closest known Scala SourceSpan while preserving the original compiler log. Scala 3 call-site capture now populates spans for DSL declarations, stores, accumulation, structured control flow, reductions, and barriers. Fine-grained expression/operator spans remain a later increment.

Compilation artifacts and caches

• Identity: A versioned canonical SHA-256 covers generated CUDA, resolved options, target, compiler/codegen versions, program name, and kernel ABI/launch metadata.
• Memory: NvrtcCompilationCache is a caller-owned bounded in-memory LRU of successful PTX compilations. Cache hits rebind PTX metadata to the current generated Scala artifact.
• Persistent artifacts: NvrtcCompiler.version() queries the loaded compiler without creating or compiling a program, so it participates in the key before lookup. The versioned, checksum-verified NvrtcArtifactStore atomically persists generated CUDA C++, PTX, compiler logs, and compilation metadata while rebinding diagnostics to the current Scala source map.
• Persistent mode: NvrtcCompilationCache.persistent(maximumEntries, store) composes memory, disk, then NVRTC. Store I/O failures are cache misses; invalid entries are removed and repaired by successful recompilation. clear() clears memory only, while clearPersistent() clears the disk layer.

Native module reuse

Within one CudaContext, load also deduplicates live native CUDA modules by the SHA-256 identity of their PTX. Each caller receives its own provenance-aware CudaModule wrapper, while the shared native module unloads only after the final wrapper and its in-flight work release. Idle modules are not retained after the final close.

Build

Flight4s requires JDK 17 or newer and sbt:

sbt test

The optional native CUDA launcher requires CMake, a C++20 compiler (GCC 10+, Clang 10+, or Visual Studio 2022+), JDK headers, and CUDA Toolkit 12 or newer:

cmake -S native -B native/build -DBUILD_TESTING=ON
cmake --build native/build --config Release
ctest --test-dir native/build -C Release --output-on-failure

See native/README.md for JNI and GPU integration tests.

Coordinates

The planned core artifact is:

"io.github.gpu-flight" %% "flight4s-core" % "<version>"

No release has been published yet.

License

Flight4s is licensed under the terms in LICENSE.