perf: reduce parser and renderer allocations

Author: osteele

BENCHMARKS.md

@@ -0,0 +1,69 @@
+# Performance Benchmarks
+
+This file records performance work that affects the template parser and
+renderer. It includes experiments that were kept and approaches that were
+removed or rejected after evaluation.
+
+## Reproduction
+
+The measurements below were collected on 2026-08-12 with Go 1.26.5 on an
+Apple M1 (`darwin/arm64`). Each result is the median of eight one-second runs
+with one logical processor:
+
+```bash
+GOMAXPROCS=1 go test -run '^$' \
+  -bench '^(BenchmarkEngine_Parse|BenchmarkTemplate_Render|BenchmarkTemplate_RenderStructProperty|BenchmarkTemplate_RenderIncludes)$' \
+  -benchmem -benchtime=1s -count=8 .
+```
+
+Absolute timings vary across machines and thermal conditions. Allocation
+counts and large relative changes are more stable.
+
+## Overall result
+
+| Benchmark | Time before | Time after | Change | Bytes before | Bytes after | Change | Allocations before | Allocations after | Change |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| Parse | 48.47 ms | 41.16 ms | -15% | 62.61 MB | 13.74 MB | -78% | 136,095 | 130,077 | -4% |
+| Loop render | 540.87 µs | 441.59 µs | -18% | 315,880 B | 147,856 B | -53% | 12,248 | 11,247 | -8% |
+| Struct property render | 462.43 µs | 340.41 µs | -26% | 207,880 B | 95,856 B | -54% | 8,748 | 7,747 | -11% |
+| 100 repeated includes | 467.51 µs | 97.05 µs | -79% | 1,331,160 B | 84,272 B | -94% | 4,610 | 1,433 | -69% |
+
+## Incremental trials
+
+The table records adjacent benchmark sweeps, so each row isolates one change
+more closely than the overall comparison.
+
+| Trial | Benchmark | Time | Bytes/op | Allocs/op | Decision |
+| --- | --- | ---: | ---: | ---: | --- |
+| Pool generated yacc parsers | Parse | 48.47 → 36.21 ms | 62.61 → 19.61 MB | 136,095 → 128,100 | Kept: large time and memory reduction |
+| Preallocate scanned tokens | Parse | 36.21 → 36.81 ms | 19.61 → 13.71 MB | 128,100 → 128,077 | Kept: neutral time, 30% fewer bytes, three-line change |
+| Pass render contexts by pointer | Loop render | 540.87 → 477.73 µs | 315,880 → 163,888 B | 12,248 → 12,249 | Kept: 12% faster and 48% fewer bytes |
+| Precompute literal values | Loop render | 477.73 → 430.79 µs | 163,888 → 147,856 B | 12,249 → 11,247 | Kept: 10% faster and 1,002 fewer allocations |
+| Compile include arguments once | Repeated includes | 461.66 → 377.95 µs | 272,883 → 232,078 B | 4,511 → 3,811 | Kept: 18% faster |
+| Stream partial output | Repeated includes | 377.95 → 343.03 µs | 232,078 → 219,277 B | 3,811 → 3,411 | Kept: 9% faster and avoids a temporary result string |
+| Render-scoped compiled partial cache | Repeated includes | 343.03 → 107.12 µs | 219,277 → 100,273 B | 3,411 → 1,633 | Kept: 69% faster while preserving mutable stores |
+| Cache struct metadata | Struct property render | 441.93 → 336.65 µs | 207,904 → 95,904 B | 8,748 → 7,748 | Kept: 24% faster and 54% fewer bytes |
+
+Literal values now allocate their runtime wrappers during parsing instead of
+during every render. This slightly offsets the parser pool's allocation-count
+reduction, but benefits every subsequent render of a compiled template.
+
+## Tried and not kept
+
+- **Process-wide compiled partial cache:** Rejected after the design trial. A
+  cache shared across renders would require template-store invalidation,
+  concurrency control, and configuration revision tracking. The render-scoped
+  cache obtains the large repeated-partial win, rereads the store, compares the
+  source bytes, and cannot become stale across top-level renders.
+- **Eager render-scoped cache allocation:** Implemented initially, then removed.
+  It charged templates that never render partials and allocated a discarded map
+  for every child context. The final implementation initializes the map only on
+  the first partial compilation.
+- **Caching missing struct properties:** Implemented initially, then removed.
+  It could retain an unbounded set of user-controlled property names in a
+  process-wide map. The final cache stores only successful lookups, whose count
+  is bounded by the fields and methods of encountered types.
+- **Handwritten default-delimiter scanner:** Rejected before implementation.
+  After parser pooling, regular-expression matching was no longer the dominant
+  allocator. Reimplementing delimiter, trimming, and malformed-token behavior
+  would add substantial compatibility risk for a smaller remaining CPU target.

CHANGELOG.md

@@ -3,6 +3,26 @@
 
 ## Unreleased
 
+### Performance
+
+- Benchmarks on Apple M1 improved as follows (median of eight runs): parsing is
+  15% faster with 78% fewer allocated bytes; loop rendering is 18% faster with
+  53% fewer bytes; struct-property rendering is 26% faster with 54% fewer
+  bytes; and 100 repeated includes are 79% faster with 94% fewer bytes.
+- Reduced parse allocations by pooling generated expression parsers and
+  preallocating template tokens.
+- Reduced render allocations by sharing the internal render context and
+  compiling literal values once.
+- Compile include arguments once, stream partial output directly, and reuse
+  unchanged compiled partials within a top-level render.
+- Cache successful struct property and method metadata lookups.
+- See [BENCHMARKS.md](BENCHMARKS.md) for measurements and rejected trials.
+
+### Fixed
+
+- Preserve `os.IsNotExist` compatibility when a template read fails and the
+  template-store root closes successfully.
+
 ## 1.9.1 (2026-08-12)
 
 ### Changed

expressions/expressions.y

@@ -127,7 +127,7 @@ loop_modifiers: /* empty */ { $$ = loopModifiers{} }
 ;
 
 expr:
-  LITERAL { val := $1; $$ = func(Context) values.Value { return values.ValueOf(val) } }
+  LITERAL { val := values.ValueOf($1); $$ = func(Context) values.Value { return val } }
 | IDENTIFIER { name := $1; $$ = func(ctx Context) values.Value { return values.ValueOf(ctx.Get(name)) } }
 | expr PROPERTY { $$ = makeObjectPropertyExpr($1, $2) }
 | expr '[' expr ']' { $$ = makeIndexExpr($1, $3) }

expressions/parser.go

@@ -7,10 +7,15 @@ package expressions
 
 import (
 	"fmt"
+	"sync"
 
 	"github.com/osteele/liquid/values"
 )
 
+var yaccParserPool = sync.Pool{
+	New: func() any { return new(yyParserImpl) },
+}
+
 type parseValue struct {
 	Assignment
 	Cycle
@@ -52,14 +57,24 @@ func parse(source string) (p *parseValue, err error) {
 	// FIXME hack to recognize EOF
 	lex := newLexer([]byte(source + ";"))
 
-	n := yyParse(lex)
+	n := parseWithPooledYaccParser(lex)
 	if n != 0 {
 		return nil, SyntaxError(fmt.Errorf("syntax error in %q", source).Error())
 	}
 
 	return &lex.parseValue, nil
 }
 
+func parseWithPooledYaccParser(lex yyLexer) int {
+	p := yaccParserPool.Get().(*yyParserImpl)
+	defer func() {
+		*p = yyParserImpl{}
+		yaccParserPool.Put(p)
+	}()
+
+	return p.Parse(lex)
+}
+
 // EvaluateString is a wrapper for Parse and Evaluate.
 func EvaluateString(source string, ctx Context) (any, error) {
 	expr, err := Parse(source)

expressions/y.go

@@ -46,7 +46,9 @@ func Scan(data string, loc SourceLoc, delims []string) (tokens []Token) {
 	// TODO error on unterminated {{ and {%
 	// TODO probably an error when a tag contains a {{ or {%, at least outside of a string
 	p, pe := 0, len(data)
-	for _, m := range tokenMatcher.FindAllStringSubmatchIndex(data, -1) {
+	matches := tokenMatcher.FindAllStringSubmatchIndex(data, -1)
+	tokens = make([]Token, 0, 2*len(matches)+1)
+	for _, m := range matches {
 		ts, te := m[0], m[1]
 		if p < ts {
 			tokens = append(tokens, Token{Type: TextTokenType, SourceLoc: loc, Source: data[p:ts]})

parser/scanner.go

@@ -66,7 +66,7 @@ type TemplateStore interface {
 }
 
 type rendererContext struct {
-	ctx  nodeContext
+	ctx  *nodeContext
 	node *TagNode
 	cn   *BlockNode
 }
@@ -160,44 +160,65 @@ func (c rendererContext) RenderChildren(w io.Writer) Error {
 }
 
 func (c rendererContext) RenderFile(filename string, b map[string]any) (string, error) {
+	buf := new(bytes.Buffer)
+	if err := c.RenderFileTo(buf, filename, b); err != nil {
+		return "", err
+	}
+
+	return buf.String(), nil
+}
+
+// RenderFileTo renders a template directly to a writer while inheriting the
+// parent lexical scope. It is used as an optional internal extension to Context.
+func (c rendererContext) RenderFileTo(w io.Writer, filename string, b map[string]any) error {
 	bindings := make(map[string]any, len(c.ctx.bindings)+len(b))
 	maps.Copy(bindings, c.ctx.bindings)
 	maps.Copy(bindings, b)
 
-	return c.renderFile(filename, bindings)
+	return c.renderFileTo(w, filename, bindings)
 }
 
 // RenderFileIsolated renders a template without inheriting the parent lexical scope.
 // It is intentionally not part of Context, so adding the render tag does not break
 // third-party Context implementations.
 func (c rendererContext) RenderFileIsolated(filename string, bindings map[string]any) (string, error) {
-	return c.renderFile(filename, maps.Clone(bindings))
+	buf := new(bytes.Buffer)
+	if err := c.RenderFileIsolatedTo(buf, filename, bindings); err != nil {
+		return "", err
+	}
+
+	return buf.String(), nil
 }
 
-func (c rendererContext) renderFile(filename string, bindings map[string]any) (string, error) {
+// RenderFileIsolatedTo renders a template directly to a writer without
+// inheriting the parent lexical scope.
+func (c rendererContext) RenderFileIsolatedTo(w io.Writer, filename string, bindings map[string]any) error {
+	return c.renderFileTo(w, filename, maps.Clone(bindings))
+}
+
+func (c rendererContext) renderFileTo(w io.Writer, filename string, bindings map[string]any) error {
 	source, err := c.ctx.config.TemplateStore.ReadTemplate(filename)
 	if err != nil && errors.Is(err, fs.ErrNotExist) {
 		// Is it cached?
 		if cval, ok := c.ctx.config.Cache[filename]; ok {
 			source = cval
 		} else {
-			return "", err
+			return err
 		}
 	} else if err != nil {
-		return "", err
-	}
-
-	root, err := c.ctx.config.Compile(string(source), parser.SourceLoc{Pathname: filename, LineNo: 1})
-	if err != nil {
-		return "", err
+		return err
 	}
 
-	buf := new(bytes.Buffer)
-	if err := Render(root, buf, bindings, c.ctx.config); err != nil {
-		return "", err
+	root, ok := c.ctx.cachedPartial(filename, source)
+	if !ok {
+		root, err = c.ctx.config.Compile(string(source), parser.SourceLoc{Pathname: filename, LineNo: 1})
+		if err != nil {
+			return err
+		}
+		c.ctx.cachePartial(filename, source, root)
 	}
 
-	return buf.String(), nil
+	return renderWithContext(root, w, c.ctx.child(bindings))
 }
 
 // InnerString renders the children to a string.

render/context.go

@@ -39,5 +39,12 @@ func (tl *FileTemplateStore) ReadTemplate(filename string) ([]byte, error) {
 	source, readErr := root.ReadFile(rel)
 	closeErr := root.Close()
 
-	return source, errors.Join(readErr, closeErr)
+	switch {
+	case readErr == nil:
+		return source, closeErr
+	case closeErr == nil:
+		return source, readErr
+	default:
+		return source, errors.Join(readErr, closeErr)
+	}
 }

render/file_template_store.go

@@ -1,6 +1,7 @@
 package render
 
 import (
+	"bytes"
 	"maps"
 
 	"github.com/osteele/liquid/expressions"
@@ -11,25 +12,55 @@ import (
 // This type has a clumsy name so that render.Context, in the public API, can
 // have a clean name that doesn't stutter.
 type nodeContext struct {
-	bindings map[string]any
-	config   Config
-	exprCtx  expressions.Context
+	bindings     map[string]any
+	config       Config
+	exprCtx      expressions.Context
+	partialCache map[string]cachedPartial
+}
+
+type cachedPartial struct {
+	source []byte
+	root   Node
 }
 
 // newNodeContext creates a new evaluation context.
-func newNodeContext(scope map[string]any, c Config) nodeContext {
+func newNodeContext(scope map[string]any, c Config) *nodeContext {
 	// The assign tag modifies the scope, so make a copy first.
 	// TODO this isn't really the right place for this.
 	vars := make(map[string]any, len(scope))
 	maps.Copy(vars, scope)
 
 	c.Config.StrictVariables = c.StrictVariables
-	ctx := nodeContext{bindings: vars, config: c}
+	ctx := nodeContext{
+		bindings: vars,
+		config:   c,
+	}
 	ctx.exprCtx = expressions.NewContext(vars, c.Config.Config)
-	return ctx
+	return &ctx
+}
+
+func (c *nodeContext) child(scope map[string]any) *nodeContext {
+	child := newNodeContext(scope, c.config)
+	child.partialCache = c.partialCache
+	return child
+}
+
+func (c *nodeContext) cachedPartial(filename string, source []byte) (Node, bool) {
+	entry, ok := c.partialCache[filename]
+	return entry.root, ok && bytes.Equal(entry.source, source)
+}
+
+func (c *nodeContext) cachePartial(filename string, source []byte, root Node) {
+	if c.partialCache == nil {
+		c.partialCache = make(map[string]cachedPartial)
+	}
+	c.partialCache[filename] = cachedPartial{
+		source: bytes.Clone(source),
+		root:   root,
+	}
 }
 
 // Evaluate evaluates an expression within the template context.
-func (c nodeContext) Evaluate(expr expressions.Expression) (out any, err error) {
+func (c *nodeContext) Evaluate(expr expressions.Expression) (out any, err error) {
 	return expr.Evaluate(c.exprCtx)
 }

render/node_context.go

@@ -11,7 +11,7 @@ import (
 type Node interface {
 	SourceLocation() parser.SourceLoc // for error reporting
 	SourceText() string               // for error reporting
-	render(*trimWriter, nodeContext) Error
+	render(*trimWriter, *nodeContext) Error
 }
 
 // BlockNode represents a {% tag %}…{% endtag %}.