Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions .github/workflows/jit-benchmark.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
name: Native JIT validation and benchmark

on:
push:
branches:
- "feat/**"
paths:
- "native/internal/tell/jit*.go"
- "native/internal/tell/jit*.s"
- "native/internal/tell/bytecode.go"
- "native/internal/tell/jit_test.go"
- ".github/workflows/jit-benchmark.yml"
pull_request:
paths:
- "native/internal/tell/jit*.go"
- "native/internal/tell/jit*.s"
- "native/internal/tell/bytecode.go"
- "native/internal/tell/jit_test.go"
- ".github/workflows/jit-benchmark.yml"
workflow_dispatch:

permissions:
contents: read

concurrency:
group: tell-jit-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
linux-amd64:
name: Linux amd64 / JIT tests and benchmark
runs-on: ubuntu-24.04
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version: "1.23.x"
- name: Run native Tell tests and race detector
working-directory: native
run: |
go test ./internal/tell
go test -race ./internal/tell
go vet ./internal/tell
- name: Benchmark interpreter, JIT, and auto mode
working-directory: native
run: |
go test ./internal/tell -run '^$' -bench '^BenchmarkTypedNumericFunctionEngines$' -benchmem -benchtime=250ms -count=1
32 changes: 32 additions & 0 deletions .github/workflows/native.yml
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,38 @@ jobs:
go test ./...
go test -race ./...
go vet ./...
- name: Benchmark interpreter, JIT, and automatic bytecode execution
working-directory: native
run: |
go test ./internal/tell -run '^
run: ./scripts/build-all.sh
- name: Verify process-level runtime conformance
run: |
python scripts/conformance.py --runtime both --fixtures conformance/smoke-v1.json --native-bin releases/tell-linux-amd64
python scripts/conformance.py --runtime both --fixtures conformance/runtime-v1.json --native-bin releases/tell-linux-amd64
- name: Run Tell source examples as tests
run: ./releases/tell-linux-amd64 test examples
- name: Upload native binaries
uses: actions/upload-artifact@v4
with:
name: tell-native-binaries
path: releases/
if-no-files-found: error
-bench '^BenchmarkTypedNumericFunctionEngines
run: ./scripts/build-all.sh
- name: Verify process-level runtime conformance
run: |
python scripts/conformance.py --runtime both --fixtures conformance/smoke-v1.json --native-bin releases/tell-linux-amd64
python scripts/conformance.py --runtime both --fixtures conformance/runtime-v1.json --native-bin releases/tell-linux-amd64
- name: Run Tell source examples as tests
run: ./releases/tell-linux-amd64 test examples
- name: Upload native binaries
uses: actions/upload-artifact@v4
with:
name: tell-native-binaries
path: releases/
if-no-files-found: error
-benchmem -benchtime=250ms -count=1
- name: Build Linux, macOS and Windows binaries
run: ./scripts/build-all.sh
- name: Verify process-level runtime conformance
Expand Down
18 changes: 18 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,6 +95,24 @@ Typed parameter and return contracts are enforced during normal execution
and preserved in bytecode. Existing dynamic Tell programs remain supported
without `--typed`; see the [typed Go dialect guide](docs/TYPED_TELL.md).

## Native Go execution engines

The Go runtime offers direct interpretation, AOT compilation to portable
`.tbc` bytecode, and an initial native JIT tier for hot typed numeric
functions:

~~~sh
tell program.tell
tell build program.tell
tell --engine jit program.tell
tell --engine auto --jit-threshold 24 --jit-stats program.tell
~~~

The JIT currently targets Linux x86-64 and a restricted typed numeric
function subset; everything else keeps running in the interpreter. The
portable `.tbc` build is not a standalone native executable. See the
[execution engine guide](docs/EXECUTION_ENGINES.md) for details and benchmarks.

## Compile native executables with TellC

TellC is an experimental C++ compiler that translates its typed dialect through LLVM into a native executable. Its dialect is separate from the dynamically typed language used by the Go and Python runtimes; programs are not necessarily interchangeable. For example:
Expand Down
6 changes: 5 additions & 1 deletion docs/ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,11 @@ The source interpreter path is shown above. The native CLI also has an early com
Tell source -> existing parser -> supported statement/expression compiler -> tell-bytecode-v1 JSON -> Go stack VM
```

It supports `Let`, `Set`, `Remember` field initialization, output statements, bare expressions, `If`/`Otherwise`, `While`, `Repeat`, `For each`, loop break/continue, `Try`/`If something goes wrong`, `Raise an error saying ...`, recursive embedding of local `.tell` modules, user functions, returns, recursion, named arguments, lexical closures, and the initial class model with constructors, fields, methods, single inheritance, and overrides, plus expressions accepted by the native parser. Repeated module imports share cached module exports in a run. Unsupported statements are rejected. A conservative type-annotation prepass checks expressions with statically known types. A scalar constant-folding pass simplifies safe literal expressions, and a verifier checks instruction references and stack heights across control-flow joins before execution. The compiler still lowers directly from the expression AST to stack bytecode without a distinct typed AST or optimization IR; it has no whole-program type inference, broader optimizer, JIT, or AOT compilation of Tell programs. The Go executable itself is a native-compiled interpreter.
It supports `Let`, `Set`, `Remember` field initialization, output statements, bare expressions, `If`/`Otherwise`, `While`, `Repeat`, `For each`, loop break/continue, `Try`/`If something goes wrong`, `Raise an error saying ...`, recursive embedding of local `.tell` modules, user functions, returns, recursion, named arguments, lexical closures, and the initial class model with constructors, fields, methods, single inheritance, and overrides, plus expressions accepted by the native parser. Repeated module imports share cached module exports in a run. Unsupported statements are rejected. A conservative type-annotation prepass checks expressions with statically known types. A scalar constant-folding pass simplifies safe literal expressions, and a verifier checks instruction references and stack heights across control-flow joins before execution. The compiler still lowers directly from the expression AST to stack bytecode without a distinct typed AST or optimization IR. The Go VM now supports three execution paths: direct source interpretation, AOT lowering to portable `.tbc` bytecode, and an opt-in native JIT tier for a narrow subset of typed numeric functions on Linux/amd64. The JIT caches eligible functions after first use (or after a hot threshold in auto mode); unsupported functions remain in the interpreter. This is not yet native AOT output or a whole-program optimizer.

## Execution engines

See [Execution Engines](EXECUTION_ENGINES.md) for the portable-bytecode AOT path, native JIT subset, automatic hot-function tiering, platform limits, and benchmark instructions.

## Persistent sessions

Expand Down
13 changes: 13 additions & 0 deletions docs/CLI_REFERENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -81,6 +81,19 @@ Both runtimes accept `--version`, `--types`, `--max-call-depth N`, and `--max-lo

Both runtimes support `tell check --types program.tell` (or `tell --types program.tell`) for conservative static type and declaration checks. Known primitive and class annotations are checked when initializer or reassigned value types can be inferred; unresolved dynamic expressions remain checked at runtime. `tell build` performs the native conservative checks automatically.

The native Go CLI also accepts `--engine interp|jit|auto` when running source or
`.tbc` files. `interp` is the default. `jit` attempts native compilation on
first function call; `auto` warms functions in the interpreter before
compiling eligible typed numeric functions. The initial native backend is
Linux x86-64 only; unsupported functions and other platforms use the
interpreter. Use `--jit-threshold N` to change auto mode's default 24-call
threshold and `--jit-stats` to report compiled functions and execution
counts. See [Execution Engines](EXECUTION_ENGINES.md) for the eligible
instruction subset and fallback rules.

`tell build` is AOT compilation to portable `.tbc` bytecode. It does not
currently emit standalone native machine-code executables.

## Not implemented yet

There is no package-management CLI, debugger, or language server. `tell new` and `tell init` scaffold a runnable project but do not resolve or install dependencies. The initial `build` command compiles only the documented native subset. `tell format` is a source formatter, not a compiler.
131 changes: 131 additions & 0 deletions docs/EXECUTION_ENGINES.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,131 @@
# Tell execution engines

The native Go runtime has three execution paths. Select a path with
`--engine` when running a source program or a `.tbc` artifact.

## Interpreter

The interpreter remains the compatibility default:

~~~sh
tell program.tell
tell --engine interp program.tell
tell --engine interp program.tbc
~~~

Source is parsed and evaluated directly by the existing Go runtime. This path
supports the full Go-interpreter language implementation and is the fallback
for bytecode functions that cannot be safely compiled by the current JIT.

## AOT: portable bytecode

The build command compiles source ahead of execution into the versioned,
portable `tell-bytecode-v1` artifact:

~~~sh
tell build program.tell
tell build program.tell --output build/program.tbc
tell run build/program.tbc
~~~

This is AOT compilation to the Go VM's portable stack bytecode. It avoids
parsing and lowering source at each run and embeds compiled local modules.
It is **not** native machine-code AOT and does not produce a standalone OS
executable. The artifact is still run by the Go runtime.

## JIT: native hot-function compilation

Run either source or bytecode with:

~~~sh
tell --engine jit program.tell
tell --engine jit program.tbc
~~~

The first native backend is Linux x86-64 only. It lazily compiles eligible
functions when they are called. The compiled machine code is cached for the
duration of the process. Executable memory follows a write-then-execute
transition: pages are writable while emitted, then changed to read/execute.

The initial native code generator is deliberately conservative. A function
is eligible only when:

- every parameter is explicitly typed as `number` or `decimal`;
- its return type is `number` or `decimal`;
- it is not a method, variadic function, or function with default arguments;
- the body is a straight-line expression using numeric constants, parameter
loads, unary `+`/`-`, binary `+`, `-`, `*`, and a return.

Division is deliberately left in the interpreter because Tell reports
division-by-zero as a language error, while a raw floating-point divide would
produce an infinity. Control flow, recursion, dynamic values, strings,
collections, I/O, calls, comparisons, and other operations are not
machine-compiled yet. Those functions execute through the existing bytecode
interpreter, even in `jit` mode. This preserves behavior while the JIT's
supported subset grows.

The initial backend is implemented with a small Linux/amd64 code emitter. It
does not add an LLVM or CGo build dependency. Other operating systems and CPU
architectures use the interpreter fallback; explicit `--engine jit` reports
that the native backend is unavailable there.

## Automatic tiering

Use automatic mode for a mixed program:

~~~sh
tell --engine auto --jit-threshold 24 program.tell
tell --engine auto --jit-threshold 24 program.tbc
~~~

Eligible functions run in the interpreter during warm-up. After the configured
number of calls, the runtime compiles the function once and routes subsequent
calls to native code. Unsupported functions remain interpreted. The default
threshold is 24 calls.

To inspect what actually ran:

~~~sh
tell --engine auto --jit-stats program.tell
~~~

The report shows compiled functions, native calls, and interpreted calls. A
function being declared as typed does not automatically make its body JIT
eligible; the body must match the supported numeric subset.

## Validation and performance

The Go test suite compares native and interpreted results, verifies the
automatic hot threshold, and verifies interpreter fallback for control flow
and division-by-zero semantics. A benchmark is available:

~~~sh
cd native
go test ./internal/tell -run '^
-bench BenchmarkTypedNumericFunctionEngines -benchmem
~~~

### Initial CI benchmark sample

One Linux amd64 CI run (Ubuntu 24.04, Go 1.23.x, 250 ms per sub-benchmark)
measured the warmed-up execution of the same typed function containing 159
numeric arithmetic operations:

| Engine | Time per call | Allocations per call |
| --- | ---: | ---: |
| Interpreter | 6,362 ns | 167 |
| Native JIT | 608 ns | 9 |
| Auto (after warm-up) | 623 ns | 9 |

This is a synthetic, compute-heavy function benchmark. The harness excludes
one-time JIT compilation from the timed section and calls the compiled
function directly; it does not measure source parsing, whole-program startup,
I/O, dynamic code, or end-to-end application performance. Treat the numbers
as an initial reference for this specific supported subset, not a universal
speedup guarantee. Benchmark representative applications before making
product-wide performance claims.

The JIT is an initial execution tier, not yet a whole-program optimizing
compiler. True native AOT output, additional CPU backends, register
allocation, inlining, deoptimization, and broader typed code generation remain
future work.
30 changes: 19 additions & 11 deletions docs/TYPED_TELL.md
Original file line number Diff line number Diff line change
Expand Up @@ -59,17 +59,25 @@ A runnable native example is available at [native/examples/native-typed.tell](..

## Performance status

This first Go typed-dialect increment adds validation and runtime contract
checks; it does not yet specialize the VM's dynamic value representation.
Go execution still uses the existing general-purpose runtime and bytecode
operations. Do not treat this change as a measured speedup in execution,
memory use, or compilation time.

The next performance phase should use typed semantic information to lower
verified functions to specialized bytecode operations and compact value
representations where benchmarks justify them. Any such change should retain
a dynamic compatibility path and be measured against representative Tell
programs before performance claims are made.
The production .tbc VM now has an initial native JIT tier for a narrow subset
of typed numeric functions on Linux/amd64. Eligible straight-line functions
with number/decimal parameters and return values can be emitted as native
x86-64 floating-point instructions. The runtime caches compiled functions;
auto mode waits for a hot-call threshold before compiling. Unsupported
functions continue through the existing interpreter.

This JIT does not yet specialize the VM's general dynamic value representation
or compile control flow, recursion, collections, I/O, or dynamic calls. It is
a small native-code backend, not LLVM ORC. Division remains interpreted so the
JIT preserves Tell's division-by-zero error semantics. Do not assume a speedup
until the benchmark is run on representative workloads. See
[Execution Engines](EXECUTION_ENGINES.md) for supported instructions and
benchmark instructions.

Future work includes a typed IR, broader native code generation, register
allocation, deoptimization, additional CPU backends, and true standalone
native AOT output. The portable .tbc build remains ahead-of-time compilation
to VM bytecode, not a native executable.

## Migration

Expand Down
43 changes: 40 additions & 3 deletions native/cmd/tell/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,9 @@ func main() {
check := flag.Bool("check", false, "parse the program without running it")
typeCheck := flag.Bool("types", false, "check statically knowable type annotations")
typedMode := flag.Bool("typed", false, "require explicit variable, parameter, and return types")
engine := flag.String("engine", "interp", "execution engine: interp, jit, or auto")
jitThreshold := flag.Int("jit-threshold", 24, "calls per function before auto mode compiles it")
jitStats := flag.Bool("jit-stats", false, "print native JIT compilation and fallback counts")
showVersion := flag.Bool("version", false, "print the Tell version")
quietREPL := flag.Bool("quiet-repl", false, "omit terminal prompts and banner (for IDE integrations)")
buildOutput := flag.String("output", "", "write compiled bytecode to this path")
Expand Down Expand Up @@ -84,8 +87,11 @@ func main() {
fmt.Printf("Tell %s (native Go runtime)\n", version)
return
}
if *maxCallDepth < 1 || *maxLoopIterations < 1 {
exitWithDiagnostic(fmt.Errorf("execution limits must be positive integers"), "<command-line>", diagnostic.UsageError)
if *maxCallDepth < 1 || *maxLoopIterations < 1 || *jitThreshold < 1 {
exitWithDiagnostic(fmt.Errorf("execution limits and JIT threshold must be positive integers"), "<command-line>", diagnostic.UsageError)
}
if !tell.ValidExecutionEngine(*engine) {
exitWithDiagnostic(fmt.Errorf("unknown execution engine %q (expected interp, jit, or auto)", *engine), "<command-line>", diagnostic.UsageError)
}
limits := tell.ExecutionLimits{MaxFunctionCallDepth: *maxCallDepth, MaxLoopIterations: *maxLoopIterations}
if projectMode != "" {
Expand Down Expand Up @@ -186,6 +192,9 @@ func main() {
return
}
if buildMode {
if *engine != "interp" || *jitStats {
exitWithDiagnostic(fmt.Errorf("tell build creates portable AOT bytecode; --engine and --jit-stats apply to execution"), "<command-line>", diagnostic.UsageError)
}
if filename == "-" && *buildOutput == "" {
exitWithDiagnostic(fmt.Errorf("tell build - requires --output"), "<command-line>", diagnostic.UsageError)
}
Expand All @@ -209,9 +218,13 @@ func main() {
return
}
if strings.EqualFold(filepath.Ext(filename), ".tbc") {
if err := tell.RunBytecodeWithLimits(data, filename, os.Stdin, os.Stdout, limits); err != nil {
stats, err := tell.RunBytecodeWithEngine(data, filename, os.Stdin, os.Stdout, limits, *engine, *jitThreshold)
if err != nil {
exitWithDiagnostic(err, filename, diagnostic.RuntimeError)
}
if *jitStats {
printJITStats(stats)
}
return
}
if *check {
Expand Down Expand Up @@ -248,11 +261,35 @@ func main() {
exitWithDiagnostic(err, runName, diagnostic.TypeError)
}
}
if *engine != "interp" {
compiled, compileErr := tell.Compile(string(data), runName)
if compileErr != nil {
if *engine == "jit" {
exitWithDiagnostic(fmt.Errorf("cannot prepare source for JIT execution: %w (this source may be outside the current bytecode compiler subset)", compileErr), runName, diagnostic.SyntaxError)
}
} else {
stats, runErr := tell.RunBytecodeWithEngine(compiled, runName, os.Stdin, os.Stdout, limits, *engine, *jitThreshold)
if runErr != nil {
exitWithDiagnostic(runErr, runName, diagnostic.RuntimeError)
}
if *jitStats {
printJITStats(stats)
}
return
}
}
if err := tell.NewSessionWithLimits(os.Stdin, os.Stdout, limits).Exec(string(data), runName); err != nil {
exitWithDiagnostic(err, runName, diagnostic.RuntimeError)
}
}

func printJITStats(stats tell.EngineStats) {
fmt.Fprintf(os.Stderr,
"execution engines: JIT compiled %d function(s), executed %d native call(s), interpreted %d call(s)\n",
stats.JITCompiledFunctions, stats.JITInvocations, stats.InterpretedCalls,
)
}

func exitWithDiagnostic(err error, filename string, kind diagnostic.Kind) {
os.Exit(reportDiagnostic(os.Stderr, err, filename, kind))
}
Expand Down
Loading
Loading