|
| 1 | +--- |
| 2 | +layout: default |
| 3 | +title: API Reference |
| 4 | +parent: Compiler |
| 5 | +nav_order: 2 |
| 6 | +--- |
| 7 | + |
| 8 | +# API Reference |
| 9 | + |
| 10 | +--- |
| 11 | + |
| 12 | +## HyperbeeCompiler |
| 13 | + |
| 14 | +`HyperbeeCompiler` is a static class -- the primary entry point for all compilation operations. |
| 15 | + |
| 16 | +```csharp |
| 17 | +using Hyperbee.Expressions.Compiler; |
| 18 | +``` |
| 19 | + |
| 20 | +### Compile |
| 21 | + |
| 22 | +```csharp |
| 23 | +static TDelegate Compile<TDelegate>( Expression<TDelegate> lambda, CompilerDiagnostics? diagnostics = null ) |
| 24 | + where TDelegate : Delegate |
| 25 | + |
| 26 | +static Delegate Compile( LambdaExpression lambda, CompilerDiagnostics? diagnostics = null ) |
| 27 | +``` |
| 28 | + |
| 29 | +Compiles the expression tree and returns a delegate. Throws on unsupported patterns. |
| 30 | + |
| 31 | +```csharp |
| 32 | +var fn = HyperbeeCompiler.Compile<Func<int, int>>( |
| 33 | + x => Expression.Add( x, Expression.Constant( 1 ) ) |
| 34 | +); |
| 35 | +Console.WriteLine( fn( 41 ) ); // 42 |
| 36 | +``` |
| 37 | + |
| 38 | +### TryCompile |
| 39 | + |
| 40 | +```csharp |
| 41 | +static TDelegate? TryCompile<TDelegate>( Expression<TDelegate> lambda ) where TDelegate : Delegate |
| 42 | +static Delegate? TryCompile( LambdaExpression lambda ) |
| 43 | +``` |
| 44 | + |
| 45 | +Compiles and returns `null` on failure instead of throwing. |
| 46 | + |
| 47 | +```csharp |
| 48 | +var fn = HyperbeeCompiler.TryCompile( lambda ); |
| 49 | +if ( fn is null ) |
| 50 | + Console.WriteLine( "Compilation failed" ); |
| 51 | +``` |
| 52 | + |
| 53 | +### CompileWithFallback |
| 54 | + |
| 55 | +```csharp |
| 56 | +static TDelegate CompileWithFallback<TDelegate>( Expression<TDelegate> lambda ) where TDelegate : Delegate |
| 57 | +static Delegate CompileWithFallback( LambdaExpression lambda ) |
| 58 | +``` |
| 59 | + |
| 60 | +Attempts HEC compilation; falls back to `lambda.Compile()` (System compiler) on failure. |
| 61 | +Use during migration when some expressions may not yet be supported. |
| 62 | + |
| 63 | +```csharp |
| 64 | +var fn = HyperbeeCompiler.CompileWithFallback( lambda ); |
| 65 | +``` |
| 66 | + |
| 67 | +### UseAsDefault / ClearDefault |
| 68 | + |
| 69 | +```csharp |
| 70 | +static ICoroutineDelegateBuilder? UseAsDefault() |
| 71 | +static ICoroutineDelegateBuilder? ClearDefault() |
| 72 | +``` |
| 73 | + |
| 74 | +Sets or clears HEC as the process-wide default builder for `AsyncBlockExpression` reductions. |
| 75 | +Call at application startup to make HEC compile all `BlockAsync` state machines, even when the |
| 76 | +outer lambda is compiled by another compiler. |
| 77 | + |
| 78 | +```csharp |
| 79 | +// In Program.cs or AssemblyInitialize |
| 80 | +HyperbeeCompiler.UseAsDefault(); |
| 81 | + |
| 82 | +// In test teardown |
| 83 | +HyperbeeCompiler.ClearDefault(); |
| 84 | +``` |
| 85 | + |
| 86 | +### CompileToMethod |
| 87 | + |
| 88 | +```csharp |
| 89 | +static void CompileToMethod( LambdaExpression lambda, MethodBuilder method ) |
| 90 | +static bool TryCompileToMethod( LambdaExpression lambda, MethodBuilder method ) |
| 91 | +``` |
| 92 | + |
| 93 | +Emits the expression tree directly into a `MethodBuilder`. The method must be `static` and its |
| 94 | +parameter signature must match the lambda. |
| 95 | + |
| 96 | +Non-embeddable constants (object references, delegates, nested lambdas) are not permitted -- |
| 97 | +all constants must be embeddable IL values (primitives, `Type` tokens, `null`). |
| 98 | + |
| 99 | +```csharp |
| 100 | +var typeBuilder = moduleBuilder.DefineType( "MyType" ); |
| 101 | +var methodBuilder = typeBuilder.DefineMethod( |
| 102 | + "Add", |
| 103 | + MethodAttributes.Public | MethodAttributes.Static, |
| 104 | + typeof(int), [typeof(int), typeof(int)] |
| 105 | +); |
| 106 | + |
| 107 | +var a = Parameter( typeof(int), "a" ); |
| 108 | +var b = Parameter( typeof(int), "b" ); |
| 109 | +var lambda = Lambda( Add( a, b ), a, b ); |
| 110 | + |
| 111 | +HyperbeeCompiler.CompileToMethod( lambda, methodBuilder ); |
| 112 | + |
| 113 | +var type = typeBuilder.CreateType(); |
| 114 | +var method = type.GetMethod("Add")!; |
| 115 | +Console.WriteLine( method.Invoke( null, [10, 32] ) ); // 42 |
| 116 | +``` |
| 117 | + |
| 118 | +### CompileToInstanceMethod |
| 119 | + |
| 120 | +```csharp |
| 121 | +static void CompileToInstanceMethod( LambdaExpression lambda, MethodBuilder method ) |
| 122 | +static bool TryCompileToInstanceMethod( LambdaExpression lambda, MethodBuilder method ) |
| 123 | +``` |
| 124 | + |
| 125 | +Like `CompileToMethod` but without the static-method requirement. For instance methods on value |
| 126 | +types (e.g., `IAsyncStateMachine.MoveNext()`), the lambda's first parameter maps to IL `arg.0` |
| 127 | +(the implicit `this` managed pointer). |
| 128 | + |
| 129 | +--- |
| 130 | + |
| 131 | +## HyperbeeExpressionCompiler |
| 132 | + |
| 133 | +`HyperbeeExpressionCompiler` implements `IExpressionCompiler` as a DI-friendly singleton wrapper |
| 134 | +around `HyperbeeCompiler`. |
| 135 | + |
| 136 | +```csharp |
| 137 | +public sealed class HyperbeeExpressionCompiler : IExpressionCompiler |
| 138 | +{ |
| 139 | + public static readonly IExpressionCompiler Instance; |
| 140 | + |
| 141 | + public Delegate Compile( LambdaExpression lambda ); |
| 142 | + public TDelegate Compile<TDelegate>( Expression<TDelegate> lambda ) where TDelegate : Delegate; |
| 143 | + public Delegate? TryCompile( LambdaExpression lambda ); |
| 144 | + public TDelegate? TryCompile<TDelegate>( Expression<TDelegate> lambda ) where TDelegate : Delegate; |
| 145 | + |
| 146 | + public static ICoroutineDelegateBuilder? UseAsDefault(); |
| 147 | +} |
| 148 | +``` |
| 149 | + |
| 150 | +### DI Registration |
| 151 | + |
| 152 | +```csharp |
| 153 | +// Register HEC as the IExpressionCompiler implementation |
| 154 | +services.AddSingleton<IExpressionCompiler>( HyperbeeExpressionCompiler.Instance ); |
| 155 | +``` |
| 156 | + |
| 157 | +### With UseAsDefault |
| 158 | + |
| 159 | +`HyperbeeExpressionCompiler.UseAsDefault()` is a convenience passthrough to |
| 160 | +`HyperbeeCompiler.UseAsDefault()`. Call it at startup to make HEC compile all `BlockAsync` |
| 161 | +state machines, even in expressions compiled by the System compiler. |
| 162 | + |
| 163 | +```csharp |
| 164 | +// In Program.cs |
| 165 | +HyperbeeExpressionCompiler.UseAsDefault(); |
| 166 | +``` |
| 167 | + |
| 168 | +--- |
| 169 | + |
| 170 | +## HyperbeeCompilerExtensions |
| 171 | + |
| 172 | +Extension methods for `LambdaExpression`: |
| 173 | + |
| 174 | +```csharp |
| 175 | +// In namespace Hyperbee.Expressions.Compiler |
| 176 | +public static TDelegate CompileHyperbee<TDelegate>( this Expression<TDelegate> lambda ) |
| 177 | + where TDelegate : Delegate |
| 178 | +``` |
| 179 | + |
| 180 | +```csharp |
| 181 | +using Hyperbee.Expressions.Compiler; |
| 182 | + |
| 183 | +var fn = lambda.CompileHyperbee(); |
| 184 | +``` |
| 185 | + |
| 186 | +--- |
| 187 | + |
| 188 | +## Notes |
| 189 | + |
| 190 | +- All `HyperbeeCompiler` methods are thread-safe -- there is no shared mutable state. |
| 191 | +- `CompileToMethod` and `CompileToInstanceMethod` do not support closures. Use `Compile()` for |
| 192 | + expressions with captured variables or non-embeddable constants. |
| 193 | +- See [Diagnostics](diagnostics.md) for `CompilerDiagnostics` and IR capture. |
| 194 | +- See [Performance](performance.md) for benchmark comparisons. |
0 commit comments