Skip to content

Commit f56afe2

Browse files
authored
perf(arith): improve arithmetic op speed vs PUC-Lua (#1)
* perf(arith): scaffold arith-vs-puc speedup work - seed branch to close the arithmetic speed gap against PUC-Lua - empty seed commit to open the Draft PR (CI, multi-machine sync); real changes land in follow-up commits Tags: #perf #arith #puc Co-Authored-By: htjulia <htjulia1@gmail.com> * perf(vm): inline monomorphic arith/bit fast paths - the ADD/SUB/MUL/bit/ADDI opcodes shared generic helpers (arithIF, arithBit, arithImm) that took the int/float op as a function-pointer argument; Go cannot inline through an indirect call, so every hot arithmetic op paid two non-inlined calls (the helper + the op itself) - replace them with per-op monomorphic helpers (addIF/subIF/mulIF, bandIF/borIF/bxorIF/shlIF/shrIF, addImm) that name the op directly, letting iAdd/fAdd/… inline as direct calls; int-wrap and float semantics stay bit-identical, so behavior is unchanged - arith 4M-float loop drops 1.90x -> 1.45x vs PUC 5.4.8 (166.9->131.8ms, -21%) on M2 Max; string-heavy workload unmoved (no regression) - drop the now-unused generic helpers Tags: #perf #arith #vm #puc Co-Authored-By: htjulia <htjulia1@gmail.com> * docs(bench): re-base cross-engine table on steady-state runs - the published ratios were measured at workloads short enough (8-60ms) that fixed costs (state init, first GC cycle, os.clock resolution) inflated them - a 20k-node tree_build read as ~1.8x when its steady-state cost is ~1.2x - scale tree_build (20k->200k nodes) and string_build (120k->1.2M) so each pass runs ~100ms+, measuring throughput rather than startup - refresh BENCHMARKS.md to the Intel i7-4790K @06d1c54 long-run numbers: tree 1.24x / arith 2.19x / string 1.31x vs PUC 5.4.8; note why short runs mislead and that arith inlining closed ~2.45x->2.19x - align README/ROADMAP wording (~1.2-1.3x table/string, ~2.2x arith) and log the arith fast-path perf win under CHANGELOG Unreleased Tags: #docs #bench #perf #puc Co-Authored-By: htjulia <htjulia1@gmail.com> * perf(strlib): pool matchState for find/match/gsub - each find/match/gsub call allocated a fresh matchState - a struct with a fixed maxCaptures array plus two string->[]byte conversions - which showed up as ~6% of allocations and ~17% of byte churn on pattern-heavy string workloads - recycle call-scoped matchStates through a sync.Pool, reusing the capture array and the src/pat byte buffers; only the LState reference is dropped on release so a pooled state never pins it - gmatch is left on the plain allocator on purpose: its matchState escapes into the returned iterator closure and outlives the call - StringHeavyExec: B/op -17%, allocs -6% (benchstat n=6); wall-clock neutral, as the workload is CPU/GC-scan bound. captures and replacements copy out of src, so reusing the backing after release is safe - race clean, conformance 30/33 unchanged (pm.lua / strings.lua pass) Tags: #perf #strlib #alloc Co-Authored-By: htjulia <htjulia1@gmail.com> * docs(changelog): cut 0.1.1 release notes - promote the Unreleased perf work to a dated [0.1.1] section and reset Unreleased to Planned only, ahead of tagging main after this merges - record both perf changes (arith/bit inline, matchState pooling) plus the benchmark re-base and the community-health docs that 0.1.1 will ship - patch bump: performance + docs only, no API or behaviour change (30/33) Tags: #docs #changelog #release Co-Authored-By: htjulia <htjulia1@gmail.com>
1 parent 2e069e8 commit f56afe2

9 files changed

Lines changed: 194 additions & 52 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 29 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,33 @@ separately from the luapure release version.
1111

1212
### Planned
1313
- Track **PUC-Lua 5.5** as it stabilizes upstream (see [`ROADMAP.md`](ROADMAP.md)).
14-
- Performance: reduce execution-time allocation churn; trim the table get/set
15-
hot path.
14+
- Performance: keep narrowing the speed/allocation gap to the reference (see
15+
[`ROADMAP.md`](ROADMAP.md) for the current levers).
16+
17+
## [0.1.1] — 2026-06-29
18+
19+
Performance and documentation. No API or observable-behaviour change;
20+
conformance stays at 30/33.
21+
22+
### Changed
23+
- **Performance — arithmetic hot path.** Inlined the monomorphic arith/bit fast
24+
paths (`OP_ADD`/`SUB`/`MUL`, the bitwise ops, and `OP_ADDI`): replacing the
25+
shared function-pointer helpers with per-op variants lets the int/float ops
26+
inline as direct calls. A tight float loop drops from ~2.45× to ~2.2× PUC; the
27+
in-repo `ArithHeavyExec` benchmark is ~10% faster (`benchstat`, no allocation
28+
change). Behaviour is bit-identical.
29+
- **Performance — pattern-match allocation.** `string.find`/`match`/`gsub` now
30+
recycle their `matchState` through a `sync.Pool` instead of allocating one per
31+
call; pattern-heavy workloads drop ~17% byte churn and ~6% of allocations.
32+
(`string.gmatch` keeps a per-call state — it escapes into the iterator.)
33+
34+
### Documentation
35+
- Re-based the cross-engine benchmark table on steady-state runs: the
36+
`tree_build`/`string_build` workloads are sized to ~100 ms+ so fixed costs no
37+
longer inflate the ratios. Refreshed `docs/BENCHMARKS.md`, `README.md`, and
38+
`ROADMAP.md` (now ~1.2–1.3× on table/string, ~2.2× on a tight float loop).
39+
- Added a Contributor Covenant code of conduct, GitHub issue forms, and a pull
40+
request template.
1641

1742
## [0.1.0] — 2026-06-28
1843

@@ -54,5 +79,6 @@ Observable semantics still match PUC; these are structural:
5479
- Configurable memory-limit caps stand in for PUC's malloc-failure path (Go
5580
cannot turn OOM into a catchable error).
5681

57-
[Unreleased]: https://github.com/htcom-code/lua-pure/compare/v0.1.0...HEAD
82+
[Unreleased]: https://github.com/htcom-code/lua-pure/compare/v0.1.1...HEAD
83+
[0.1.1]: https://github.com/htcom-code/lua-pure/compare/v0.1.0...v0.1.1
5884
[0.1.0]: https://github.com/htcom-code/lua-pure/releases/tag/v0.1.0

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,7 @@ C toolchain, luapure is the gap the table above shows.
4343

4444
## Performance
4545

46-
Pure Go costs roughly **1.3–1.6× PUC on table/string work and ~2.45× on a tight
46+
Pure Go costs roughly **1.2–1.3× PUC on table/string work and ~2.2× on a tight
4747
arithmetic loop** — measured back-to-back against the C interpreter, with no
4848
cgo. See [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md) for the full cross-engine
4949
numbers (PUC vs cgo bindings vs luapure) and methodology.

‎ROADMAP.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,8 @@ reference. The discipline is fixed:
6767
`BenchmarkTreeBuildExec`, `BenchmarkProtectedCall`) are the guardrail.
6868

6969
Current standing vs other engines (latest snapshot in [`docs/BENCHMARKS.md`](docs/BENCHMARKS.md)):
70-
within ~1.5× of the reference C interpreter (and its cgo binding, aarzilli/golua)
71-
on table/string work, ~2.45× on a tight float loop — as pure Go, with no cgo.
70+
within ~1.2–1.3× of the reference C interpreter (and its cgo binding, aarzilli/golua)
71+
on table/string work, ~2.2× on a tight float loop — as pure Go, with no cgo.
7272

7373
Current levers, ordered by intent — not commitments:
7474

‎docs/BENCHMARKS.md‎

Lines changed: 19 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -29,30 +29,38 @@ Lower is faster. Ratio = engine ÷ PUC (1.00 = parity with the C interpreter).
2929

3030
| workload | PUC (s) | golua (cgo) | luapure (pure Go) |
3131
|---|---:|---:|---:|
32-
| `tree_build` — build + DFS-sum a 20k-node tree | 0.0096 | ~1.0× | **1.45×** |
33-
| `arith` — 4M-iteration float loop | 0.122 | ~1.0× | **2.45×** |
34-
| `string_build` — format + concat 120k strings | 0.064 | ~1.0× | **1.47×** |
32+
| `tree_build` — build + DFS-sum a 200k-node tree | 0.111 | ~1.0× | **1.24×** |
33+
| `arith` — 4M-iteration float loop | 0.120 | ~1.0× | **2.19×** |
34+
| `string_build` — format + concat 1.2M strings | 0.689 | ~1.0× | **1.31×** |
35+
36+
Each workload is sized so a single pass runs ~100 ms or more. Short runs let
37+
fixed costs (state init, the first GC cycle, `os.clock` resolution) dominate and
38+
*inflate* the ratio — at a 20k-node tree the same `tree_build` reads as 1.8×,
39+
which is a measurement artifact, not the steady-state cost.
3540

3641
**Takeaways**
3742
- **golua (cgo) ≈ PUC** (~1.0×) — expected, since it executes the very same C
3843
interpreter; it mainly shows that the cgo call layer adds little for
3944
whole-script runs.
40-
- **luapure (pure Go) costs ~1.3–1.6× on table/string work and ~2.45× on a tight
45+
- **luapure (pure Go) costs ~1.2–1.3× on table/string work and ~2.2× on a tight
4146
float loop** versus the C engine — with **no cgo**: it cross-compiles, has no C
42-
toolchain dependency, and gives one independent VM per goroutine. Closing the
43-
arithmetic gap (alloc churn, hot-path) is the standing perf focus — see
47+
toolchain dependency, and gives one independent VM per goroutine.
48+
- The arithmetic loop is the widest gap and the standing perf focus. Inlining the
49+
monomorphic arith/bit fast paths (`addIF`/`mulIF`/… in `lua/lvm.go`) closed it
50+
from ~2.45× to **~2.19×** here; the residual is Go's `switch` dispatch versus
51+
C's computed-goto, which a bytecode-threading rewrite would address. See
4452
[`ROADMAP.md`](../ROADMAP.md).
4553

4654
## Provenance
4755

4856
| | |
4957
|---|---|
50-
| machine | Darwin x86_64 (Intel Core i7-4790K) |
51-
| date | 2026-06-28 |
52-
| luapure commit | `c87ce8f` |
53-
| Go | 1.24.0 |
58+
| machine | Darwin x86_64 (Intel Core i7-4790K @ 4.0 GHz) |
59+
| date | 2026-06-29 |
60+
| luapure commit | `06d1c54` (branch `perf/arith-vs-puc`) |
61+
| Go | 1.24 |
5462
| golua | `aarzilli/golua` (cgo) against Homebrew `lua@5.4` (Lua 5.4.8), built `-tags "lua54 llua"` |
55-
| method | same self-timed `.lua` on each engine; **best of 7** `os.clock()` CPU-time runs |
63+
| method | same self-timed `.lua` on each engine; **best of 7** `os.clock()` CPU-time runs, cross-checked back-to-back over several rounds; workloads sized to ~100 ms+ per pass |
5664

5765
## How to reproduce
5866

‎docs/bench/string_build.lua‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
-- string_build: format many small strings and concatenate them.
2+
-- Count is sized so the loop runs ~100ms+ per pass: short runs let fixed costs
3+
-- (state init, first GC cycle, os.clock resolution) inflate the cross-engine
4+
-- ratio, so this measures steady-state throughput.
25
local function work()
36
local t = {}
4-
for i = 1, 120000 do
7+
for i = 1, 1200000 do
58
t[i] = string.format("item-%d=%d", i, (i * i) % 1000)
69
end
710
local joined = table.concat(t, ",")

‎docs/bench/tree_build.lua‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,10 @@
11
-- tree_build: build a balanced binary tree from a flat node map, then DFS-sum.
22
-- Pure in-memory table work. Common Lua 5.1/5.4 syntax.
3+
-- N is sized so the loop runs ~100ms+ per pass: short runs let fixed costs
4+
-- (state init, first GC cycle, os.clock resolution) inflate the cross-engine
5+
-- ratio, so this measures steady-state throughput.
36
local function work()
4-
local N = 20000
7+
local N = 200000
58
local nodes = {}
69
for i = 1, N do
710
nodes[i] = { i, (i > 1) and math.floor(i / 2) or 0, (i * 2654435761) % 1000003, {} }

‎lua/lstrlib_pattern.go‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
package luapure
22

3-
import "strings"
3+
import (
4+
"strings"
5+
"sync"
6+
)
47

58
// Lua pattern matching (lstrlib.c match engine), ported to operate on byte
69
// slices with integer indices. Captures track an init offset and a length, with
@@ -371,6 +374,32 @@ func newMatchState(L *LState, s, p string) *matchState {
371374
return &matchState{L: L, src: []byte(s), pat: []byte(p), depth: maxMatchDepth}
372375
}
373376

377+
// matchStatePool recycles matchState values for the call-scoped pattern
378+
// functions (find/match/gsub). A matchState carries a fixed maxCaptures array
379+
// plus src/pat byte buffers; allocating one per call showed up as ~7% of
380+
// string-workload allocations. The capture array holds only ints and the
381+
// byte buffers hold no Lua pointers, so reuse is safe — we only drop the L
382+
// reference on release so a pooled state never pins an LState.
383+
//
384+
// gmatch is excluded on purpose: its matchState escapes into the returned
385+
// iterator closure and outlives the call, so it keeps using newMatchState.
386+
var matchStatePool = sync.Pool{New: func() any { return &matchState{} }}
387+
388+
func acquireMatchState(L *LState, s, p string) *matchState {
389+
ms := matchStatePool.Get().(*matchState)
390+
ms.L = L
391+
ms.src = append(ms.src[:0], s...) // reuse backing array across calls
392+
ms.pat = append(ms.pat[:0], p...)
393+
ms.level = 0
394+
ms.depth = maxMatchDepth
395+
return ms
396+
}
397+
398+
func releaseMatchState(ms *matchState) {
399+
ms.L = nil // don't pin the LState in the pool
400+
matchStatePool.Put(ms)
401+
}
402+
374403
// --- the four pattern functions ---
375404

376405
func strFind(L *LState) int { return strFindAux(L, true) }
@@ -399,7 +428,8 @@ func strFindAux(L *LState, find bool) int {
399428
L.Push(Nil)
400429
return 1
401430
}
402-
ms := newMatchState(L, s, p)
431+
ms := acquireMatchState(L, s, p)
432+
defer releaseMatchState(ms)
403433
anchor := false
404434
pp := 0
405435
if len(ms.pat) > 0 && ms.pat[0] == '^' {
@@ -498,7 +528,8 @@ func strGsub(L *LState) int {
498528
repl := L.Arg(3)
499529
maxN := L.optInt(4, int64(len(s))+1)
500530

501-
ms := newMatchState(L, s, p)
531+
ms := acquireMatchState(L, s, p)
532+
defer releaseMatchState(ms)
502533
anchor := false
503534
pp := 0
504535
if len(ms.pat) > 0 && ms.pat[0] == '^' {

‎lua/lvm.go‎

Lines changed: 80 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -527,14 +527,44 @@ func (L *LState) pushClosure(p *Proto, encup []*Upvalue, base, ra int) {
527527

528528
// --- arithmetic helpers (op_arith_aux / op_arithf_aux / op_bitwise) ---
529529

530-
func arithIF(v1, v2 Value, iop func(int64, int64) int64, fop func(float64, float64) float64) (Value, bool) {
530+
// addIF/subIF/mulIF are monomorphic fast paths for the arithmetic opcodes
531+
// (OP_ADD/SUB/MUL and their K variants). Taking no function-pointer arguments
532+
// lets the int/float ops inline as direct calls — the indirect call through a
533+
// shared generic helper was a measurable share of arith-heavy execution (the
534+
// hot dispatch loop spends ~all its time here). The int wrap (iAdd) and float
535+
// (fAdd) semantics are the same as the per-op functions they call.
536+
func addIF(v1, v2 Value) (Value, bool) {
531537
if v1.IsInt() && v2.IsInt() {
532-
return Int(iop(v1.AsInt(), v2.AsInt())), true
538+
return Int(iAdd(v1.AsInt(), v2.AsInt())), true
533539
}
534-
n1, ok1 := toNumberNS(v1)
535-
n2, ok2 := toNumberNS(v2)
536-
if ok1 && ok2 {
537-
return Float(fop(n1, n2)), true
540+
if n1, ok := toNumberNS(v1); ok {
541+
if n2, ok := toNumberNS(v2); ok {
542+
return Float(fAdd(n1, n2)), true
543+
}
544+
}
545+
return Value{}, false
546+
}
547+
548+
func subIF(v1, v2 Value) (Value, bool) {
549+
if v1.IsInt() && v2.IsInt() {
550+
return Int(iSub(v1.AsInt(), v2.AsInt())), true
551+
}
552+
if n1, ok := toNumberNS(v1); ok {
553+
if n2, ok := toNumberNS(v2); ok {
554+
return Float(fSub(n1, n2)), true
555+
}
556+
}
557+
return Value{}, false
558+
}
559+
560+
func mulIF(v1, v2 Value) (Value, bool) {
561+
if v1.IsInt() && v2.IsInt() {
562+
return Int(iMul(v1.AsInt(), v2.AsInt())), true
563+
}
564+
if n1, ok := toNumberNS(v1); ok {
565+
if n2, ok := toNumberNS(v2); ok {
566+
return Float(fMul(n1, n2)), true
567+
}
538568
}
539569
return Value{}, false
540570
}
@@ -548,11 +578,50 @@ func arithFlt(v1, v2 Value, fop func(float64, float64) float64) (Value, bool) {
548578
return Value{}, false
549579
}
550580

551-
func arithBit(v1, v2 Value, bop func(int64, int64) int64) (Value, bool) {
552-
i1, ok1 := toIntegerNS(v1)
553-
i2, ok2 := toIntegerNS(v2)
554-
if ok1 && ok2 {
555-
return Int(bop(i1, i2)), true
581+
// bandIF/borIF/bxorIF/shlIF/shrIF are monomorphic fast paths for the bitwise
582+
// opcodes, mirroring addIF/subIF/mulIF: no function-pointer argument, so the
583+
// int op inlines as a direct call.
584+
func bandIF(v1, v2 Value) (Value, bool) {
585+
if i1, ok := toIntegerNS(v1); ok {
586+
if i2, ok := toIntegerNS(v2); ok {
587+
return Int(iBAnd(i1, i2)), true
588+
}
589+
}
590+
return Value{}, false
591+
}
592+
593+
func borIF(v1, v2 Value) (Value, bool) {
594+
if i1, ok := toIntegerNS(v1); ok {
595+
if i2, ok := toIntegerNS(v2); ok {
596+
return Int(iBOr(i1, i2)), true
597+
}
598+
}
599+
return Value{}, false
600+
}
601+
602+
func bxorIF(v1, v2 Value) (Value, bool) {
603+
if i1, ok := toIntegerNS(v1); ok {
604+
if i2, ok := toIntegerNS(v2); ok {
605+
return Int(iBXor(i1, i2)), true
606+
}
607+
}
608+
return Value{}, false
609+
}
610+
611+
func shlIF(v1, v2 Value) (Value, bool) {
612+
if i1, ok := toIntegerNS(v1); ok {
613+
if i2, ok := toIntegerNS(v2); ok {
614+
return Int(iShl(i1, i2)), true
615+
}
616+
}
617+
return Value{}, false
618+
}
619+
620+
func shrIF(v1, v2 Value) (Value, bool) {
621+
if i1, ok := toIntegerNS(v1); ok {
622+
if i2, ok := toIntegerNS(v2); ok {
623+
return Int(iShr(i1, i2)), true
624+
}
556625
}
557626
return Value{}, false
558627
}

0 commit comments

Comments
 (0)