Hyperbee.Expressions.Compiler 1.4.6

Hyperbee Expression Compiler

A high-performance, IR-based expression compiler for .NET. Drop-in replacement for Expression.Compile() that is 9-34x faster and allocates up to 50% less than the System compiler and supports all expression tree patterns — including those that FastExpressionCompiler doesn't.

Why Another Expression Compiler?

We ❤️ FastExpressionCompiler. FEC is faster than Hyperbee Expression Compiler, and allocates less memory — and for many workloads it's the right choice. If FEC compiles your expressions correctly, use it.

FEC's single-pass, low allocation, IL emission approach supports most, but not all, expression patterns. See FEC issues; patterns like compound assignments inside TryCatch, complex closure captures, and certain value-type operations aren't supported.

Hyperbee takes a middle ground: a multi-pass IR pipeline that lowers expression trees to an intermediate representation, runs optimization passes, validates structural correctness, and then emits IL. This architecture trades a small amount of speed and allocation overhead for correct IL across all expression tree patterns while significantly outperforming the System Compiler.

Performance

HEC is consistently 9-34x faster than the System Compiler and within 1.16-1.54x of FEC across all tiers — while producing correct IL for the sub-set of patterns FEC doesn't support (NegateChecked overflow, NaN comparisons, value-type instance calls, compound assignments in TryCatch, etc.).

The Complex tier standout (~34x vs System) is where the multi-pass IR architecture pays off against the System compiler's heavyweight compilation pipeline. The Switch tier at 1.54x is the widest gap vs FEC.

Compilation Benchmarks

BenchmarkDotNet v0.15.8, Windows 11
Intel Core i9-9980HK CPU 2.40GHz, 1 CPU, 16 logical and 8 physical cores
.NET SDK 10.0.103 — .NET 9.0.12, X64 RyuJIT x86-64-v3

Allocation Profile

The multi-pass IR pipeline allocates roughly 1.8–4.4× more than FEC per compilation call but up to 50% less than the System Compiler. The overhead is per-compilation, not per-execution — compiled delegates run at equivalent speed regardless of which compiler produced them. For hot paths that compile once and cache, the allocation difference is negligible. For workloads that re-compile frequently (dynamic LINQ providers, interpreted rule engines), prefer FEC when its patterns cover your use case.

Execution Benchmarks

All three compilers produce delegates with equivalent runtime performance. For non-trivial expressions (Complex, Loop), the difference is zero — the compiled IL is structurally identical. For trivial expressions (Simple, Switch), sub-nanosecond differences reflect JIT inlining decisions around DynamicMethod boundaries, not meaningful execution overhead.

Note: FEC returns N/A for the Loop tier due to a known compilation issue with loop/break expressions. HEC compiles and runs it correctly.

The sub-nanosecond Simple/Closure/TryCatch numbers (< 2 ns absolute) are at the boundary of ShortRun precision (3 iterations). The 1–4x ratios represent 1–3 extra clock cycles and should be interpreted as "roughly equivalent" rather than a meaningful performance gap.

Compiler Comparison

Summary: Use FEC when its speed advantage matters and your expression patterns are in its comfort zone. Use Hyperbee when you need correct compilation across all patterns with near-FEC performance.

Getting Started

Installation

dotnet add package Hyperbee.Expressions.Compiler

Basic Usage

using Hyperbee.Expressions.Compiler;

// Direct compilation — drop-in replacement for Expression.Compile()
var lambda = Expression.Lambda<Func<int, int, int>>(
    Expression.Add( a, b ), a, b );

var fn = HyperbeeCompiler.Compile( lambda );
var result = fn( 1, 2 ); // 3

Extension Method

using Hyperbee.Expressions.Compiler;

var fn = lambda.CompileHyperbee();

Safe Compilation

// Returns null instead of throwing on unsupported patterns
var fn = HyperbeeCompiler.TryCompile( lambda );

// Falls back to System compiler on failure
var fn = HyperbeeCompiler.CompileWithFallback( lambda );

Compile to MethodBuilder

Emit the expression tree directly into a static MethodBuilder on a dynamic type — useful when building assemblies with AssemblyBuilder/TypeBuilder. Only expressions with embeddable constants (no closures over heap objects) are supported; use TryCompileToMethod for a non-throwing variant.

var ab = AssemblyBuilder.DefineDynamicAssembly( new AssemblyName( "MyAssembly" ), AssemblyBuilderAccess.Run );
var mb = ab.DefineDynamicModule( "MyModule" );
var tb = mb.DefineType( "MyType", TypeAttributes.Public | TypeAttributes.Class );
var method = tb.DefineMethod( "Add", MethodAttributes.Public | MethodAttributes.Static,
    typeof( int ), [typeof( int ), typeof( int )] );

var a = Expression.Parameter( typeof( int ), "a" );
var b = Expression.Parameter( typeof( int ), "b" );
HyperbeeCompiler.CompileToMethod( Expression.Lambda( Expression.Add( a, b ), a, b ), method );

var type = tb.CreateType();
var result = (int) type.GetMethod( "Add" )!.Invoke( null, [1, 2] )!; // 3

Architecture

The compiler uses a four-stage pipeline:

Expression Tree
      |
      v
  [1. Lower]         ExpressionLowerer: tree → flat IR instruction stream
      |
      v
  [2. Transform]     StackSpillPass → PeepholePass → DeadCodePass → IRValidator
      |
      v
  [3. Map]           Build constants array for non-embeddable values
      |
      v
  [4. Emit]          ILEmissionPass: IR → CIL via ILGenerator → DynamicMethod
      |
      v
    Delegate

Optimization Passes

Supported Frameworks

• .NET 8.0
• .NET 9.0
• .NET 10.0

Credits

• FastExpressionCompiler by Maksim Volkau — the inspiration and benchmark target. FEC pioneered high-performance expression compilation and remains the fastest option available. ❤️
• System.Linq.Expressions — the reference implementation and correctness baseline.

License

Licensed under the MIT License.