perf: render-path optimizations (-21-36% render time, -50% allocations)

source/Handlebars/BindingContext.cs

@@ -66,6 +66,7 @@ internal void SetDataObject(object? data)
  private void Initialize()
  {
  Root = ParentContext?.Root ?? this;
+ HasFrameHelpers = ParentContext?.HasFrameHelpers ?? false;
 
  ContextDataObject.AddOrReplace(ChainSegment.Root, Root.Value, out WellKnownVariables[(int) WellKnownVariable.Root]);
 
@@ -117,9 +118,17 @@ out WellKnownVariables[(int) WellKnownVariable.Parent]
  internal CascadeIndex<string, IHelperDescriptor<BlockHelperOptions>, StringEqualityComparer> BlockHelpers { get; }
 
  internal TemplateDelegate? PartialBlockTemplate { get; set; }
-
+
  internal short PartialDepth { get; set; }
 
+ /// <summary>
+ /// <c>true</c> once any code obtained this frame's (or an ancestor frame's) helper
+ /// registries for writing — see <see cref="IHelpersRegistry"/>. Until then the
+ /// per-frame helper chain is known to be empty, letting hot paths
+ /// (<see cref="Helpers.LateBindHelperDescriptor"/>) skip the cascade lookup entirely.
+ /// </summary>
+ internal bool HasFrameHelpers { get; set; }
+
  public object? Value { get; set; }
 
  [MethodImpl(MethodImplOptions.AggressiveInlining)]
@@ -203,8 +212,16 @@ private static void PopulateHash(HashParameterDictionary hash, object from)
  }
  }
 
- IIndexed<string, IHelperDescriptor<HelperOptions>> IHelpersRegistry.GetHelpers() => Helpers;
+ IIndexed<string, IHelperDescriptor<HelperOptions>> IHelpersRegistry.GetHelpers()
+ {
+ HasFrameHelpers = true;
+ return Helpers;
+ }
 
- IIndexed<string, IHelperDescriptor<BlockHelperOptions>> IHelpersRegistry.GetBlockHelpers() => BlockHelpers;
+ IIndexed<string, IHelperDescriptor<BlockHelperOptions>> IHelpersRegistry.GetBlockHelpers()
+ {
+ HasFrameHelpers = true;
+ return BlockHelpers;
+ }
  }
 }

source/Handlebars/Decorators/BlockDecoratorOptions.cs

@@ -84,8 +84,8 @@ public void Template(in EncodedTextWriter writer, object? context)
  [MethodImpl(MethodImplOptions.AggressiveInlining)]
  public void Template(in EncodedTextWriter writer, BindingContext context) => OriginalTemplate(writer, context);
 
- IIndexed<string, IHelperDescriptor<HelperOptions>> IHelpersRegistry.GetHelpers() => Frame.Helpers;
+ IIndexed<string, IHelperDescriptor<HelperOptions>> IHelpersRegistry.GetHelpers() => ((IHelpersRegistry) Frame).GetHelpers();
 
- IIndexed<string, IHelperDescriptor<BlockHelperOptions>> IHelpersRegistry.GetBlockHelpers() => Frame.BlockHelpers;
+ IIndexed<string, IHelperDescriptor<BlockHelperOptions>> IHelpersRegistry.GetBlockHelpers() => ((IHelpersRegistry) Frame).GetBlockHelpers();
  }
 }

source/Handlebars/Decorators/DecoratorOptions.cs

@@ -25,8 +25,8 @@ BindingContext frame
 
  public PathInfo Name { get; }
 
- IIndexed<string, IHelperDescriptor<HelperOptions>> IHelpersRegistry.GetHelpers() => Frame.Helpers;
+ IIndexed<string, IHelperDescriptor<HelperOptions>> IHelpersRegistry.GetHelpers() => ((IHelpersRegistry) Frame).GetHelpers();
 
- IIndexed<string, IHelperDescriptor<BlockHelperOptions>> IHelpersRegistry.GetBlockHelpers() => Frame.BlockHelpers;
+ IIndexed<string, IHelperDescriptor<BlockHelperOptions>> IHelpersRegistry.GetBlockHelpers() => ((IHelpersRegistry) Frame).GetBlockHelpers();
  }
 }

source/Handlebars/Extensions/EnumerableExtensions.cs

@@ -12,7 +12,14 @@ internal static class EnumerableExtensions
  public static bool Any(this IEnumerable builder)
  {
  var enumerator = builder.GetEnumerator();
- return enumerator.MoveNext();
+ try
+ {
+ return enumerator.MoveNext();
+ }
+ finally
+ {
+ (enumerator as IDisposable)?.Dispose();
+ }
  }
 
  public static bool IsOneOf<TSource, TExpected>(this IEnumerable<TSource> source)

source/Handlebars/HandlebarsUtils.cs

@@ -40,11 +40,25 @@ public static bool IsFalsy([NotNullWhen(false)] object? value, bool includeZero)
  return IsFalsyJsonElement(element, includeZero);
  }
 
- if (IsNumber(value) && !includeZero)
+ if (includeZero) return false;
+
+ // Typed zero checks in likelihood order; avoids IsNumber's isinst cascade
+ // followed by Convert.ToBoolean's IConvertible dispatch on the hot path.
+ return value switch
  {
- return !Convert.ToBoolean(value);
- }
- return false;
+ int i => i == 0,
+ long l => l == 0L,
+ double d => d == 0d,
+ float f => f == 0f,
+ decimal m => m == 0m,
+ byte b8 => b8 == 0,
+ sbyte s8 => s8 == 0,
+ short s16 => s16 == 0,
+ ushort u16 => u16 == 0,
+ uint u32 => u32 == 0u,
+ ulong u64 => u64 == 0ul,
+ _ => false
+ };
  }
 
  private static bool IsFalsyJsonElement(JsonElement element, bool includeZero)
@@ -84,23 +98,13 @@ public static bool IsFalsyOrEmpty([NotNullWhen(false)] object? value, bool inclu
  || (element.ValueKind == JsonValueKind.Array && element.GetArrayLength() == 0);
  }
 
+ // O(1) emptiness checks that avoid allocating an enumerator for the common
+ // collection shapes; the IEnumerable fallback boxes List<T>-style struct enumerators.
+ if (value is ICollection collection) return collection.Count == 0;
+
  return value is IEnumerable enumerable && !enumerable.Any();
  }
 
- private static bool IsNumber([NotNullWhen(true)] object? value)
- {
- return value is sbyte
- || value is byte
- || value is short
- || value is ushort
- || value is int
- || value is uint
- || value is long
- || value is ulong
- || value is float
- || value is double
- || value is decimal;
- }
  }
 }
 

source/Handlebars/Helpers/BlockHelpers/LateBindBlockHelperDescriptor.cs

@@ -1,10 +1,18 @@
+using System;
+using System.Runtime.CompilerServices;
 using HandlebarsDotNet.Collections;
 using HandlebarsDotNet.PathStructure;
 
 namespace HandlebarsDotNet.Helpers.BlockHelpers
 {
  public sealed class LateBindBlockHelperDescriptor : IHelperDescriptor<BlockHelperOptions>
  {
+ // See LateBindHelperDescriptor: ObservableList.Count locks per call, so the
+ // "are there helper resolvers" check is cached behind an observer-maintained flag.
+ private ObservableList<IHelperResolver>? _observedResolvers;
+ private IObserver<IObservableEvent<IHelperResolver>>? _observerRoot; // strong root: ObservableList holds observers weakly
+ private volatile bool _hasResolvers;
+
  public LateBindBlockHelperDescriptor(string name) => Name = name;
 
  public PathInfo Name { get; }
@@ -16,16 +24,18 @@
 
  public void Invoke(in EncodedTextWriter output, in BlockHelperOptions options, in Context context, in Arguments arguments)
  {
- if(options.Frame.BlockHelpers.TryGetValue(Name, out var contextHelper))
+ // Frame-local helpers only exist once something wrote to a frame's helper registry
+ // (decorators / in-render registration); skip the cascade walk in the common case.
+ if(options.Frame.HasFrameHelpers && options.Frame.BlockHelpers.TryGetValue(Name, out var contextHelper))
  {
  contextHelper.Invoke(options, context, arguments);
  return;
  }
-
- // TODO: add cache
+
  var configuration = options.Frame.Configuration;
  var helperResolvers = (ObservableList<IHelperResolver>) configuration.HelperResolvers;
- if(helperResolvers.Count != 0)
+ if (!ReferenceEquals(_observedResolvers, helperResolvers)) ObserveResolvers(helperResolvers);
+ if (_hasResolvers)
  {
  for (var index = 0; index < helperResolvers.Count; index++)
  {
@@ -39,5 +49,19 @@
  configuration.BlockHelpers["blockHelperMissing"]!.Value
  .Invoke(output, options, context, arguments);
  }
+
+ [MethodImpl(MethodImplOptions.NoInlining)]
+ private void ObserveResolvers(ObservableList<IHelperResolver> resolvers)
+ {
+ // Subscribe before snapshotting Count so a concurrent Add can never be missed;
+ // duplicate subscriptions from a racing first call are benign (same flag).
+ var observer = ObserverBuilder<IObservableEvent<IHelperResolver>>.Create(this)
+ .OnEvent<AddedObservableEvent<IHelperResolver>>((_, state) => state._hasResolvers = true)
+ .Build();
+ resolvers.Subscribe(observer);
+ _observerRoot = observer;
+ if (resolvers.Count != 0) _hasResolvers = true;
+ _observedResolvers = resolvers;
+ }
  }
-}
+}

source/Handlebars/Helpers/LateBindHelperDescriptor.cs

@@ -1,10 +1,19 @@
+using System;
+using System.Runtime.CompilerServices;
 using HandlebarsDotNet.Collections;
 using HandlebarsDotNet.PathStructure;
 
 namespace HandlebarsDotNet.Helpers
 {
  public sealed class LateBindHelperDescriptor : IHelperDescriptor<HelperOptions>
  {
+ // ObservableList.Count takes a ReaderWriterLockSlim per call, and this descriptor runs
+ // for every simple {{name}} on every render — so the "are there helper resolvers" check
+ // is cached in a flag kept up to date by subscribing to the (append-only) resolver list.
+ private ObservableList<IHelperResolver>? _observedResolvers;
+ private IObserver<IObservableEvent<IHelperResolver>>? _observerRoot; // strong root: ObservableList holds observers weakly
+ private volatile bool _hasResolvers;
+
  public LateBindHelperDescriptor(string name) => Name = name;
 
  public PathInfo Name { get; }
@@ -13,15 +22,17 @@
  {
  var bindingContext = options.Frame;
 
- if(options.Frame.Helpers.TryGetValue(Name, out var contextHelper))
+ // Frame-local helpers only exist once something wrote to a frame's helper registry
+ // (decorators / in-render registration); skip the cascade walk in the common case.
+ if(bindingContext.HasFrameHelpers && bindingContext.Helpers.TryGetValue(Name, out var contextHelper))
  {
  return contextHelper.Invoke(options, context, arguments);
  }
-
- // TODO: add cache
+
  var configuration = options.Frame.Configuration;
  var helperResolvers = (ObservableList<IHelperResolver>) configuration.HelperResolvers;
- if (helperResolvers.Count != 0)
+ if (!ReferenceEquals(_observedResolvers, helperResolvers)) ObserveResolvers(helperResolvers);
+ if (_hasResolvers)
  {
  var targetType = arguments.Length > 0 ? arguments[0]!.GetType() : null;
  for (var index = 0; index < helperResolvers.Count; index++)
@@ -35,13 +46,27 @@
 
  var value = PathResolver.ResolvePath(bindingContext, Name);
  if (!(value is UndefinedBindingResult)) return value;
-
+
  return configuration.Helpers["helperMissing"]!.Value.Invoke(options, context, arguments);
  }
 
  public void Invoke(in EncodedTextWriter output, in HelperOptions options, in Context context, in Arguments arguments)
  {
  output.Write(Invoke(options, context, arguments));
  }
+
+ [MethodImpl(MethodImplOptions.NoInlining)]
+ private void ObserveResolvers(ObservableList<IHelperResolver> resolvers)
+ {
+ // Subscribe before snapshotting Count so a concurrent Add can never be missed;
+ // duplicate subscriptions from a racing first call are benign (same flag).
+ var observer = ObserverBuilder<IObservableEvent<IHelperResolver>>.Create(this)
+ .OnEvent<AddedObservableEvent<IHelperResolver>>((_, state) => state._hasResolvers = true)
+ .Build();
+ resolvers.Subscribe(observer);
+ _observerRoot = observer;
+ if (resolvers.Count != 0) _hasResolvers = true;
+ _observedResolvers = resolvers;
+ }
  }
-}
+}

source/Handlebars/IO/PolledStringWriter.cs

@@ -7,7 +7,11 @@ namespace HandlebarsDotNet
 {
  public class ReusableStringWriter : StringWriter
  {
- private static readonly InternalObjectPool<ReusableStringWriter, Policy> Pool = new InternalObjectPool<ReusableStringWriter, Policy>(new Policy(16));
+ // Retain up to 32K chars (64KB, below the LOH threshold) so that templates producing
+ // typical page-sized output keep their grown StringBuilder across renders. The previous
+ // 4096-char limit made any render larger than 4KB discard the writer, forcing every
+ // subsequent render to re-grow a fresh StringBuilder(16) chunk by chunk.
+ private static readonly InternalObjectPool<ReusableStringWriter, Policy> Pool = new InternalObjectPool<ReusableStringWriter, Policy>(new Policy(16, 32 * 1024));
 
  private IFormatProvider _formatProvider = null!;
 

source/Handlebars/IO/SafeStrings.cs

@@ -1,4 +1,5 @@
 using System.Runtime.CompilerServices;
+using System.Threading;
 
 namespace HandlebarsDotNet.IO
 {
@@ -16,15 +17,26 @@ internal static class SafeStrings
  private static readonly ConditionalWeakTable<string, object> Marked = new();
  private static readonly object Sentinel = new();
 
+ // Marking only ever happens when a helper's captured output is written (ReturnInvoke).
+ // Most applications never mark a single string, yet IsSafe sits on the hot path of every
+ // string written to output — so keep a global "has anything ever been marked" latch to
+ // skip the ConditionalWeakTable probe entirely until the first Mark. The latch is written
+ // with release semantics after the table entry exists, so a true reader always observes
+ // the corresponding table entry; a stale false reader merely re-encodes on the same
+ // thread-interleaving that was already possible before the mark completed.
+ private static bool _anyMarked;
+
  [MethodImpl(MethodImplOptions.AggressiveInlining)]
  public static string Mark(string value)
  {
  if (value.Length == 0) return value;
  Marked.GetValue(value, _ => Sentinel);
+ Volatile.Write(ref _anyMarked, true);
  return value;
  }
 
  [MethodImpl(MethodImplOptions.AggressiveInlining)]
- public static bool IsSafe(string value) => value.Length == 0 || Marked.TryGetValue(value, out _);
+ public static bool IsSafe(string value)
+ => value.Length == 0 || (Volatile.Read(ref _anyMarked) && Marked.TryGetValue(value, out _));
  }
 }

source/Handlebars/ObjectDescriptors/ObjectDescriptorFactory.cs

@@ -1,5 +1,6 @@
 using System;
 using System.Diagnostics.CodeAnalysis;
+using System.Threading;
 using HandlebarsDotNet.Collections;
 using HandlebarsDotNet.EqualityComparers;
 using HandlebarsDotNet.Runtime;
@@ -25,18 +26,31 @@ public class ObjectDescriptorFactory : IObjectDescriptorProvider, IObserver<IObs
 
  private readonly IObserver<IObservableEvent<IObjectDescriptorProvider>> _observer;
 
+ private int _version;
+
  public static ObjectDescriptorFactory? Current => AmbientContext.Current?.ObjectDescriptorFactory;
-
+
+ /// <summary>
+ /// Monotonic stamp bumped whenever the provider set changes; lets external
+ /// per-call-site descriptor caches (see <see cref="PathStructure.ChainSegment"/>)
+ /// detect that previously resolved descriptors may be stale.
+ /// </summary>
+ internal int Version => Volatile.Read(ref _version);
+
  public ObjectDescriptorFactory(ObservableList<IObjectDescriptorProvider>? providers = null)
  {
  _providers = new ObservableList<IObjectDescriptorProvider>();
-
+
  if (providers != null) Append(providers);
-
- _observer = ObserverBuilder<IObservableEvent<IObjectDescriptorProvider>>.Create(_descriptorsCache)
- .OnEvent<AddedObservableEvent<IObjectDescriptorProvider>>((@event, state) => state.Clear())
+
+ _observer = ObserverBuilder<IObservableEvent<IObjectDescriptorProvider>>.Create(this)
+ .OnEvent<AddedObservableEvent<IObjectDescriptorProvider>>((@event, state) =>
+ {
+ state._descriptorsCache.Clear();
+ Interlocked.Increment(ref state._version);
+ })
  .Build();
-
+
  _providers.Subscribe(this);
  }