sg: inlining codegen, capture locals, [FastClonerTrustNullability], [FastClonerSafeHandle], add mapperly to benchmark

Author: lofcz

README.md

@@ -19,6 +19,7 @@ The fastest deep cloning library, supporting anything from <code>.NET 4.6</code>
 - **The Fastest** - [Benchmarked](https://github.com/lofcz/FastCloner?tab=readme-ov-file#performance) to beat all other libraries with third-party independent benchmarks verifying the performance. **300x** speed-up vs `Newtonsoft.Json` and **160x** vs `System.Text.Json`
 - **The Most Correct** - Cloning objects is hard: `<T>`, `abstract`, immutables, read-only, pointers, circular dependencies, deeply nested graphs.. we have over [600 tests](https://github.com/lofcz/FastCloner/tree/next/FastCloner.Tests) verifying correct behavior in these cases and we are transparent about the [limitations](https://github.com/lofcz/FastCloner?tab=readme-ov-file#limitations)
 - **Novel Algorithm** - FastCloner recognizes that certain cloning code cannot be generated in certain scenarios and uses highly optimized reflection-based approach instead for these types - this only happens for the members that need this, not entire objects
+- **Zero-Overhead Abstractions** - The generator uses call site analysis to eliminate indirection via inlining of generated methods. This ensures the generated code behaves like a single optimized block, just as if you hand-wrote it for maximum performance.
 - **Embeddable** - FastCloner has no dependencies outside the standard library. Source generator and reflection parts can be installed independently
 - **Gentle & Caring** - FastCloner detects standard attributes like `[NonSerialized]` making it easy to try without polluting codebase with custom attributes. Type usage graph for generics is built automatically producing performant cloning code without manual annotations
 - **Easy Integration** - `FastDeepClone()` for AOT cloning, `DeepClone()` for reflection cloning. That's it!
@@ -143,7 +144,7 @@ Animal pet = new Dog { Name = "Buddy", Breed = "Labrador" };
 Animal clone = pet.FastDeepClone(); // Returns a cloned Dog
 ```
 
-### Explicitly Including Types with `[FastClonerInclude]`
+### Explicitly Including Types
 
 When a type is only used dynamically (not visible at compile time), use `[FastClonerInclude]` to ensure the generator creates cloning code for it:
 
@@ -167,7 +168,7 @@ public abstract class Plugin
 }
 ```
 
-### Cloning Context with `FastClonerContext`
+### Custom Cloning Context
 
 For advanced scenarios, create a custom cloning context to explicitly register types you want to clone. This is useful when you need a centralized cloning entry point or want to clone types from external assemblies:
 
@@ -205,6 +206,37 @@ if (ctx.TryClone(obj, out var cloned))
 }
 ```
 
+### Nullability Trust
+
+The generator can be instructed to fully trust nullability annotations. When `[FastClonerTrustNullability]` attribute is applied, FastCloner will skip null checks for non-nullable reference types (e.g., `string` vs `string?`), assuming the contract is valid.
+
+```csharp
+[FastClonerClonable]
+[FastClonerTrustNullability] // Skip null checks for non-nullable members
+public class HighPerformanceDto
+{
+    public string Id { get; set; } // No null check generated
+    public string? Details { get; set; } // Null check still generated
+}
+```
+
+This eliminates branching and improves performance slightly. If a non-nullable property is actually null at runtime, this may result in a `NullReferenceException` in the generated code.
+
+### Safe Handles
+
+When you have a struct that acts as a handle to internal state or a singleton (where identity matters), use `[FastClonerSafeHandle]`. This tells FastCloner to shallow-copy the readonly fields instead of deep-cloning them, preserving the original internal references.
+
+```csharp
+[FastClonerSafeHandle]
+public struct MyHandle
+{
+    private readonly object _internalState; // Preserved (shared), not deep cloned
+    public int Value; // Cloned normally
+}
+```
+
+This is the default behavior for system types like `System.Net.Http.Headers.HeaderDescriptor` to prevent breaking internal framework logic. Use this attribute if your custom structs behave similarly.
+
 ## Limitations
 
 - Cloning unmanaged resources, such as `IntPtr`s may result in side-effects, as there is no metadata for the length of buffers such pointers often point to.
@@ -239,10 +271,19 @@ Intel Core i7-8700 CPU 3.20GHz (Max: 3.19GHz) (Coffee Lake), 1 CPU, 12 logical a
 
 You can run the benchmark [locally](https://github.com/lofcz/FastCloner/blob/next/FastCloner.Benchmark/BenchMinimal.cs) to verify the results. There are also [third-party benchmarks](https://github.com/AnderssonPeter/Dolly?tab=readme-ov-file#benchmarks) in some of the competing libraries confirming these results.
 
+### Build Times & IDE Performance
+
+FastCloner's source generator is carefully engineered for zero impact on IDE responsiveness and swift build times.
+
+- **Tiered Caching**: We use `ForAttributeWithMetadataName` for highly efficient filtering and strictly separate syntax analysis from code generation.
+- **Smart Models**: Roslyn symbols are immediately projected into lightweight, cache-friendly `TypeModel` records. The generator never holds onto compilation symbols, allowing the incremental pipeline to perfectly cache previous results.
+- **No Compilation Trashing**: We avoid expensive `CompilationProvider` combinations that break generator caching. Code generation only re-runs when your data models actually change, not on every keystroke or unrelated edit.
+- **Allocation Free**: `EquatableArray` collections ensure that change detection is instant and creates no garbage collection pressure.
+
 ## Contributing
 
 If you are looking to add new functionality, please open an issue first to verify your intent is aligned with the scope of the project. The library is covered by over [600 tests](https://github.com/lofcz/FastCloner/tree/next/src/FastCloner.Tests), please run them against your work before proposing changes. When reporting issues, providing a minimal reproduction we can plug in as a new test greatly reduces turnaround time.
 
 ## License
 
-This library is licensed under the [MIT](https://github.com/lofcz/FastCloner/blob/next/LICENSE) license. 💜
+This library is licensed under the [MIT](https://github.com/lofcz/FastCloner/blob/next/LICENSE) license. 💜

src/FastCloner.Benchmark/BenchMinimal.cs

@@ -7,6 +7,7 @@
 using NClone;
 using Newtonsoft.Json;
 using ProtoBuf;
+using Riok.Mapperly.Abstractions;
 using System.Runtime.Serialization.Formatters.Binary;
 using System.Text.Json;
 
@@ -15,10 +16,11 @@ namespace FastCloner.Benchmark;
 [RankColumn]
 [Orderer(BenchmarkDotNet.Order.SummaryOrderPolicy.FastestToSlowest)]
 [MemoryDiagnoser]
-public class BenchMinimal
+public partial class BenchMinimal
 {
     private TestObject testData;
     private IMapper mapper;
+    private TestObjectMapper mapperlyMapper;
 
     [GlobalSetup]
     public void Setup()
@@ -39,6 +41,8 @@ public void Setup()
             cfg.CreateMap<NestedObject, NestedObject>();
         }, new NullLoggerFactory());
         mapper = config.CreateMapper();
+        
+        mapperlyMapper = new TestObjectMapper();
     }
 
     [Benchmark(Baseline = true)]
@@ -133,9 +137,9 @@ public object DeepCopyExpression()
     }
 
     [Benchmark]
-    public object? AnyCloneBenchmark()
+    public object? AnyClone()
     {
-        return AnyClone.CloneExtensions.Clone(testData);
+        return global::AnyClone.CloneExtensions.Clone(testData);
     }
 
     [Benchmark]
@@ -144,9 +148,16 @@ public object DeepCopyExpression()
         return Clone.ObjectGraph(testData);
     }
 
+    [Benchmark]
+    public object? Mapperly()
+    {
+        return mapperlyMapper.TestObjectToTestObject(testData);
+    }
+
 
     [Serializable]
     [FastClonerClonable]
+    [FastClonerTrustNullability]
     [MessagePackObject]
     [ProtoContract]
     public class TestObject
@@ -174,4 +185,10 @@ public class NestedObject
         [ProtoMember(2)]
         public string Description { get; set; }
     }
+
+    [Mapper(UseDeepCloning = true)]
+    public partial class TestObjectMapper
+    {
+        public partial TestObject TestObjectToTestObject(TestObject testObject);
+    }
 }

src/FastCloner.Benchmark/FastCloner.Benchmark.csproj

@@ -10,7 +10,7 @@
 
     <ItemGroup>
       <PackageReference Include="AnyClone" Version="1.1.6" />
-      <PackageReference Include="AutoMapper" Version="15.1.0" />
+      <PackageReference Include="AutoMapper" Version="16.0.0" />
       <PackageReference Include="BenchmarkDotNet" Version="0.15.8" />
       <PackageReference Include="DeepCloner" Version="0.10.4" />
       <PackageReference Include="DeepCopier" Version="1.0.4" />
@@ -23,6 +23,7 @@
       <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
       <PackageReference Include="ObjectCloner" Version="2.2.2" />
       <PackageReference Include="protobuf-net" Version="3.2.56" />
+      <PackageReference Include="Riok.Mapperly" Version="3.7.0" />
       <PackageReference Include="System.Runtime.Serialization.Formatters" Version="10.0.0" />
     </ItemGroup>
 

src/FastCloner.SourceGenerator.Shared/FastClonerClonableAttribute.cs

@@ -15,4 +15,14 @@ public class FastClonerClonableAttribute : Attribute
     public FastClonerClonableAttribute()
     {
     }
+}
+
+/// <summary>
+/// Instructs FastCloner to trust the nullability annotations of reference types.
+/// If a reference type member is not annotated as nullable (e.g. string instead of string?),
+/// FastCloner will NOT generate a null check for it, assuming it will never be null.
+/// </summary>
+[AttributeUsage(AttributeTargets.Class | AttributeTargets.Struct)]
+public class FastClonerTrustNullabilityAttribute : Attribute
+{
 }

src/FastCloner.SourceGenerator/ClassCloneBodyGenerator.cs

@@ -66,7 +66,7 @@ public static void WriteClassCloneBody(
             // When tracking circular references, we must register the instance BEFORE cloning members
             // to avoid infinite recursion (StackOverflowException) in case of cycles.
             // This requires us to instantiate first, then register, then assign members.
-            WriteInstanceCreation(sb, typeName, hasParameterlessConstructor, isRecord, sourceVarName);
+            WriteInstanceCreation(ctx, sb, typeName, hasParameterlessConstructor, isRecord, sourceVarName);
 
             var stateVarForAdd = stateVarName ?? "state";
             var nullConditional = useNullConditional ? "?" : "";
@@ -83,33 +83,55 @@ public static void WriteClassCloneBody(
         }
         else
         {
-            // For non-circular types, we can use object initializer syntax if constructor exists
+            // For non-circular types, we can use mixed statement/initializer syntax
             if (hasParameterlessConstructor)
             {
-                sb.AppendLine($"            var result = new {typeName}");
-                sb.AppendLine("            {");
-
-                var memberAssignments = new List<string>();
+                // Create instance start
+                sb.Append($"            var result = new {typeName}");
+                
+                // Collect init-only and required properties for object initializer
+                var initOnlyMembers = new List<string>();
                 foreach (var member in ctx.Model.Members)
                 {
-                    var assignment = MemberCloneGenerator.GetMemberAssignment(ctx, member, sourceVarName, "null");
-                    if (!string.IsNullOrEmpty(assignment))
+                    if ((member.IsProperty && member.IsInitOnly) || member.IsRequired)
                     {
-                        memberAssignments.Add($"                {assignment}");
+                        var assignment = MemberCloneGenerator.GetMemberAssignment(ctx, member, sourceVarName, "null", "                ");
+                        if (!string.IsNullOrEmpty(assignment))
+                        {
+                            initOnlyMembers.Add($"                {assignment}");
+                        }
                     }
                 }
 
-                if (memberAssignments.Count > 0)
+                if (initOnlyMembers.Count > 0)
                 {
-                    sb.AppendLine(string.Join(",\n", memberAssignments));
+                    sb.AppendLine();
+                    sb.AppendLine("            {");
+                    sb.AppendLine(string.Join(",\n", initOnlyMembers));
+                    sb.AppendLine("            };");
+                }
+                else
+                {
+                    sb.AppendLine("();");
                 }
 
-                sb.AppendLine("            };");
+                // Use statements for everything else (better for JIT and null handling)
+                foreach (var member in ctx.Model.Members)
+                {
+                    // Skip if already handled in initializer (init-only or required)
+                    if ((member.IsProperty && member.IsInitOnly) || member.IsRequired)
+                        continue;
+
+                    if (!member.IsProperty || !member.IsInitOnly)
+                    {
+                        MemberCloneGenerator.WriteMemberCloning(ctx, member, "result", sourceVarName, "null");
+                    }
+                }
             }
             else
             {
                 // Use FormatterServices.GetUninitializedObject to create instance without calling constructor
-                WriteInstanceCreation(sb, typeName, hasParameterlessConstructor, isRecord, sourceVarName);
+                WriteInstanceCreation(ctx, sb, typeName, hasParameterlessConstructor, isRecord, sourceVarName);
 
                 // Then assign members individually (no state needed for non-circular types)
                 foreach (var member in ctx.Model.Members)
@@ -128,7 +150,7 @@ public static void WriteClassCloneBody(
     /// For records, uses the 'with' expression for shallow copy.
     /// </summary>
     /// <param name="sourceVarName">The name of the source variable (usually "source" for classes, "src" for structs after null check)</param>
-    private static void WriteInstanceCreation(StringBuilder sb, string typeName, bool hasParameterlessConstructor, bool isRecord, string sourceVarName = "source")
+    private static void WriteInstanceCreation(CloneGeneratorContext ctx, StringBuilder sb, string typeName, bool hasParameterlessConstructor, bool isRecord, string sourceVarName = "source")
     {
         if (isRecord)
         {
@@ -137,7 +159,29 @@ private static void WriteInstanceCreation(StringBuilder sb, string typeName, boo
         }
         else if (hasParameterlessConstructor)
         {
-            sb.AppendLine($"            var result = new {typeName}();");
+            // Check for required members
+            var requiredMembers = new List<string>();
+            foreach (var member in ctx.Model.Members)
+            {
+                if (member.IsRequired)
+                {
+                    // Assign default! to satisfy compiler contract
+                    // We will assign real values later
+                    requiredMembers.Add($"                {member.Name} = default!");
+                }
+            }
+
+            if (requiredMembers.Count > 0)
+            {
+                sb.AppendLine($"            var result = new {typeName}");
+                sb.AppendLine("            {");
+                sb.AppendLine(string.Join(",\n", requiredMembers));
+                sb.AppendLine("            };");
+            }
+            else
+            {
+                sb.AppendLine($"            var result = new {typeName}();");
+            }
         }
         else
         {
@@ -167,7 +211,7 @@ private static void WriteRecordCloneBody(CloneGeneratorContext ctx, string typeN
             if (member.IsReadOnly)
                 continue;
 
-            var assignment = MemberCloneGenerator.GetMemberAssignment(ctx, member, sourceVarName, "null");
+            var assignment = MemberCloneGenerator.GetMemberAssignment(ctx, member, sourceVarName, "null", "                ");
             if (!string.IsNullOrEmpty(assignment))
             {
                 deepCloneAssignments.Add($"                {assignment}");