Commit8d1bfa18Recorded25 Sep 2026Repositorysigil-geometry
Update README and CHANGELOG for the widened allocation check
Message
123 checks covering all 80 ! forms; ELF numbers; the constructs the hot paths avoid (macros, named lets, case-lambda, rest arguments); NaN comparison semantics; predicates in the API tables.
Changed
CHANGELOG.md | 6 +++++-
README.md | 60 +++++++++++++++++++++++++++++++++++++++---------------------
2 files changed, 44 insertions(+), 22 deletions(-)Diff
CHANGELOG.mdmodified
@@ -25,6 +25,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
25
weights for picking), plus plane and box helpers. 26
- Every operation that produces a value has an allocation-free `!` form 27
whose destination may alias its inputs. Measured at zero allocations−28
per call for all 55 checked operations on wasm and on bytecode.+28
per call on wasm and on bytecode, over 123 checks covering all 80+29
`!` forms and their other branches. 30
- `scripts/check-targets`: the test suite and the allocation check on 31
bytecode, native ELF and wasm.+32
- Tolerant comparisons (`vec3-approx=?`, `mat4-approx=?`,+33
`quat-same-rotation?` and the rest) that never accept NaN, written+34
around sigil 0.22.7's `<=`, `>=` and `=`, which answer #t for NaN.README.mdmodified
@@ -110,8 +110,12 @@ contract is the bytes.
110
gives zero. Arguments that describe nothing (a perspective with 111
`near <= 0`, a plane with a zero normal) raise an error. 112
- **Tolerant comparison.** `vec3-approx=?`, `mat4-approx=?` and friends−113
take an optional epsilon (default 1e-5, relative above magnitude 1).−114
`quat-same-rotation?` treats `q` and `-q` as equal.+113
take an optional epsilon (default 1e-5, relative above magnitude 1,+114
must be positive). A NaN on either side is never approx=?.+115
`quat-same-rotation?` compares components up to sign, so `q` and `-q`+116
match and a non-unit quaternion does not match a unit one. Passing the+117
epsilon explicitly allocates one list cell per call (it is a rest+118
argument); the default allocates nothing. 119
120
## API 121
@@ -122,7 +126,7 @@ allocating twin without the `!`):
126
127
| | | 128
|---|---|−125
| make | `vec3`, `make-vec3`, `vec3-copy`, `vec3-copy!`, `vec3-set!`, `vec3?` |+129
| make | `vec3`, `make-vec3`, `vec3-copy`, `vec3-copy!`, `vec3-set!`, `vec3?` (size check) | 130
| access | `vec3-x`, `vec3-y`, `vec3-z` (`vec4-w`), `vec3->list` | 131
| arithmetic | `vec3-add!`, `vec3-sub!`, `vec3-mul!` (per component), `vec3-scale!`, `vec3-negate!`, `vec3-lerp!` | 132
| measure | `vec3-dot`, `vec3-length`, `vec3-length-squared`, `vec3-normalize!`, `vec2-distance`, `vec3-distance` |@@ -134,7 +138,7 @@ allocating twin without the `!`):
138
139
| | mat4 | mat3 | 140
|---|---|---|−137
| make | `mat4` (16 values), `make-mat4`, `mat4-identity!`, `list->mat4`, `mat4-copy!` | `mat3`, `make-mat3`, `mat3-identity!`, `list->mat3`, `mat3-copy!` |+141
| make | `mat4` (16 values), `make-mat4`, `mat4-identity!`, `list->mat4`, `mat4-copy!`, `mat4?` | `mat3`, `make-mat3`, `mat3-identity!`, `list->mat3`, `mat3-copy!`, `mat3?` | 142
| access | `mat4-ref m col row`, `mat4-set!`, `mat4->list` | `mat3-ref`, `mat3-set!`, `mat3->list` | 143
| algebra | `mat4-mul!`, `mat4-transpose!`, `mat4-inverse!`, `mat4-determinant` | `mat3-mul!`, `mat3-transpose!`, `mat3-inverse!`, `mat3-determinant` | 144
| build | `mat4-translation!`, `mat4-scaling!`, `mat4-rotation-x!` / `-y!` / `-z!`, `mat4-rotation! axis angle`, `mat4-from-quat!`, `mat4-from-trs! t q s` | `mat3-from-mat4!`, `mat3-normal-matrix!`, `mat3-from-quat!` |@@ -144,7 +148,7 @@ allocating twin without the `!`):
148
149
### Quaternions: `(sigil geometry quat)` 150
−147
`quat`, `make-quat`, `quat-identity!`, `quat-from-axis-angle!`,+151
`quat`, `make-quat`, `quat?`, `quat-identity!`, `quat-from-axis-angle!`, 152
`quat-from-mat3!`, `quat-from-mat4!`, `quat-mul!`, `quat-conjugate!`, 153
`quat-inverse!`, `quat-normalize!`, `quat-dot`, `quat-length`, 154
`quat-slerp!`, `quat-nlerp!`, `quat-rotate-vec3!`, `quat-angle`,@@ -189,27 +193,41 @@ That makes a sight line a ray with `dir = target - eye`, where a hit with
193
## Allocation, measured 194
195
`scripts/check-targets` counts GC allocations over 1000 calls of each of−192
55 operations (every `!` form plus the scalar and ray functions),−193
against an empty-loop baseline and a positive control. Results with−194
sigil 0.22.7:+196
123 checks, against an empty-loop baseline and a positive control. The+197
checks cover all 80 exported `!` forms, the scalar, ray and comparison+198
functions, and the other branches of the ops that have them (a+199
projection's divide by w, a singular inverse, a degenerate look-at, each+200
branch of the matrix-to-quaternion conversion, zero-length normalize, ray+201
misses). The script refuses to run if an exported `!` form has no check.+202
Results with sigil 0.22.7: 203
204
| target | allocations per call | 205
|---|---|−198
| native wasm (the web) | 0 for all 55 |−199
| bytecode | 0 for all 55 |−200
| native ELF | 0 for 42; one per argument for the 13 that take 4 or more arguments (see below) |+206
| native wasm (the web) | 0 for all 123 |+207
| bytecode | 0 for all 123 |+208
| native ELF | 0 for 87; the other 36 allocate where the call crosses from native code into bytecode (see below) | 209
210
On a native ELF build, sigil 0.22.7 loads a dependency package's 211
compiled bytecode rather than its native code, so an app's calls into−204
sigil-geometry cross from native to bytecode, and that crossing−205
allocates for calls with 4 or more arguments. It is a property of the−206
toolchain's ELF bundles, not of this package, and the wasm build is not−207
affected.−208
−209
The package uses no `syntax-rules` macros in its hot paths, on purpose:−210
under native codegen, each global a macro template introduces is looked−211
up at run time through `%hygiene-ref`, which allocates on every call.−212
Helper procedures cost nothing.+212
sigil-geometry cross from native to bytecode. That crossing allocates one+213
object per argument for calls with 4 or more arguments, and 2 for a call+214
to a procedure with a rest argument (the `approx=?` family). It is a+215
property of the toolchain's ELF bundles, not of this package, and the+216
wasm build is not affected.+217
+218
What the package avoids in its hot paths, and why (each measured to+219
allocate on every call under native codegen):+220
+221
- `syntax-rules` macros whose template names a global: native codegen+222
looks the global up at run time through `%hygiene-ref`, which conses.+223
Helper procedures cost nothing.+224
- Named-let loops (3 to 5 objects per call) and `case-lambda` (2 to 4):+225
loops are top-level recursive procedures instead.+226
- Passing a rest argument (one list cell).+227
+228
Sigil 0.22.7 also answers #t to `(<= x y)`, `(>= x y)` and `(= x y)` when+229
an operand is NaN, so the comparisons here are written with `<` and `>`,+230
which answer correctly. 231
232
## Development 233
@@ -225,7 +243,7 @@ guix shell -m manifest.scm -- scripts/check-targets
243
into the app in `harness/` with the allocation check, runs it on each 244
target (wasm under Node), and reports per target. A target passes when 245
every test ran and passed and, where the geometry code is native or all−228
bytecode, no `!` form allocated.+246
bytecode, none of the 123 checks allocated. 247
248
## License 249