Tuple Code Generation
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Tuple Code Generation represents a planned architectural component in the Jazz language compiler aimed at bridging high-level functional tuple constructs with low-level runtime representations. In the Jazz ecosystem, tuples are intended to serve as immutable, ordered collections of heterogeneous types, facilitating pattern matching and data grouping without the overhead of formal class declarations.
The current roadmap identifies "Tuple code generation/runtime behavior" as a planned aspirational feature. While the core language currently supports strong static typing and type inference for expressions, the end-to-end implementation of tuples involves integrating the frontend parser with the LLVM-based backend.
Sources: README.md:23-33, README.md:43-45
Architectural Integration
The generation of tuple code is situated within the transition from the analyzer-facing AST to the LLVM backend. The Jazz project utilizes a multi-stage compiler architecture where source code is parsed into a surface AST, lowered into an analyzer AST, and eventually targeted toward LLVM.
Compiler Pipeline Stages
The following diagram illustrates where tuple generation fits within the existing jazz-next implementation path:
The diagram shows the standard flow from surface parsing to the backend, noting where planned tuple logic interacts with the LLVM generation phase.
Sources: jazz-next/README.md:14-25, README.md:32
Low-Level Tuple Representation
The Jazz project leverages LLVM for high-performance code generation. Based on the underlying llvm-hs bindings used by the project, tuples are mapped to LLVM aggregate types, specifically MDTuple and structured metadata nodes.
LLVM Mapping Components
In the FFI layer, tuples are handled through specific C++ constructors that interface with LLVM's internal IR.
| Component | Description | Source File |
|---|---|---|
MDTuple | The primary LLVM representation for metadata tuples. | MetadataC.cpp |
LLVM_Hs_Get_MDTuple | FFI function to create a new tuple from an array of metadata. | MetadataC.cpp:78-82 |
AggregateZero | Used for zero-initializing aggregates including structs and tuples. | llvm-hs-pure/CHANGELOG.md:73-77 |
LLVM_Hs_GetMDNodeOperands | Utility to extract elements from a tuple-like metadata node. | MetadataC.cpp:113-118 |
Sources: jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/MetadataC.cpp:78-82, jazz-hs/local-deps/llvm-hs-pure/CHANGELOG.md:73-77
Implementation Status
Tuple code generation is currently in the transition from design to active implementation. The project categorizes features into "Implemented Today" and "Planned/Aspirational".
Feature Matrix
| Stage | Status | Notes |
|---|---|---|
| Parsing | Planned | Surface forms for tuples are defined in design stubs. |
| Type Inference | Partial | Core expression inference exists in jazz-next. |
| LLVM Backend | Planned | Targeted as the primary performance backend. |
| Runtime Behavior | Planned | End-to-end runtime behavior is currently a roadmap item. |
Sources: README.md:23-35, jazz-next/README.md:11-13
Data Flow for Tuple Creation
The sequence below describes the intended interaction during the code generation phase when a tuple is encountered:
This sequence illustrates the mapping from high-level analyzer components to the C++ FFI layers for tuple creation.
Sources: jazz-hs/local-deps/llvm-hs/src/LLVM/Internal/FFI/MetadataC.cpp:78-82, jazz-next/README.md:24-25
Technical Constraints and Requirements
- Immutability: Consistent with the Jazz core philosophy, tuples must be immutable bindings.
- LLVM Compatibility: Generation must adhere to LLVM 12.0 standards, which is the version currently targeted by the project's dependencies.
- Governance: Any changes to tuple semantics must follow the repository governance policy, requiring a decision record or RFC before landing in
jazz-next/.
Sources: README.md:17, README.md:46-51, jazz-hs/local-deps/llvm-hs/CHANGELOG.md:3
Summary
Tuple Code Generation in Jazz is a critical upcoming feature designed to integrate high-level collection syntax with LLVM's aggregate type system. While currently classified as an aspirational target, the infrastructure for its implementation—including LLVM FFI bindings for MDTuple and the jazz-next analyzer pipeline—is already established in the codebase. Successful implementation will allow Jazz to support complex data grouping with the performance benefits of a compiled LLVM backend.