Serializers
High-performance serialization framework — Binary, JSON, Toon — on shared infrastructure.
Folder Structure
| Folder |
Purpose |
Binaries/ |
High-performance binary serialization with two-phase scan+serialize |
Jsons/ |
Custom JSON serialization using Utf8JsonWriter/Utf8JsonReader |
Toons/ |
LLM-optimized Token-Oriented Object Notation with @meta/@data sections |
Expressions/ |
Expression tree serialization (LINQ Expression ↔ DTO) |
Attributes/ |
Source generator marker attributes |
Shared Infrastructure (Root Files)
Core Base Classes
AcSerializerContextBase.cs — Generic base context AcSerializerContextBase<TMetadata, TOptions> with metadata caching, wrapper slot management, and context pooling. All three serializers derive from this.AcSerializerOptions.cs — Base options: reference handling mode, max depth, custom property mapping, ThrowOnCircularReference.TypeMetadataBase.cs — Cached type analysis: readable/writable properties, IId detection, complexity flags (HasComplexProperties, NeedsReferenceTracking, IsCollection).TypeMetadataWrapper.cs — Wraps metadata with per-context tracking state: typed IdentityMap instances (Int32/Int64/Guid), SmallIdBitmap, polymorphic cache, source-gen reader/writer registry lookup.
Serialization/Deserialization Bases
SerializationContextBase.cs — Base for serialization contexts.DeserializationContextBase.cs — Base for deserialization contexts.SerializeTypeMetadataBase.cs — Base for format-specific serialize metadata.DeserializeTypeMetadataBase.cs — Base for format-specific deserialize metadata.DeserializeChainBase.cs — Deserialization chain pattern.DeserializeCrossTypeBase.cs — Cross-type deserialization support.
Property Handling
PropertyAccessorBase.cs — Base for reading property values during serialization.PropertySetterBase.cs — Base for writing property values during deserialization.PropertyMetadataBase.cs — Base property metadata shared across formats.
Utilities
AcSerializerCommon.cs — Expression type checking, queryable type refs, ThreadLocal cache helpers, compiled constructor creation.IdentityMap.cs — High-perf hash table optimized for small int keys (bitmap) + chaining for large keys. Used for reference tracking.FnvHash.cs — Deterministic FNV-1a property name hashing (used in Binary UseMetadata mode).ReferenceTracker.cs — ReferenceEqualityComparer for object identity-based tracking dictionaries.IIdCollectionMergeHelper.cs — Collection merge operations during PopulateMerge (handles orphaned item removal).
Architecture
Generic Specialization Pattern
AcSerializerContextBase<TMetadata, TOptions>
├─ BinarySerializationContext <BinarySerializeTypeMetadata, AcBinarySerializerOptions>
├─ JsonSerializationContext <JsonSerializeTypeMetadata, AcJsonSerializerOptions>
└─ ToonSerializationContext <ToonSerializeTypeMetadata, AcToonSerializerOptions>
Key Design Decisions
- Sealed derived classes — All context implementations are sealed for JIT direct calling (no virtual dispatch on hot paths).
- Context pooling — Contexts are reused across serializations via thread-safe pools.
ResetTracking() clears reference maps on pool return.
- Property ordering — Hierarchy-aware (base→derived) then alphabetical. Ensures stable property indices across type versions.
- Typed reference access — No boxing for common ID types. Pre-cast delegates:
RefIdGetterInt32, RefIdGetterInt64, RefIdGetterGuid.
- Zero-allocation hot paths — Buffer owned by context,
Span-based operations, ArrayPool for large allocations.
- Global metadata cache — Thread-safe per
TMetadata type, shared across all contexts of that serializer type.
Reference Handling Modes
| Mode |
Description |
None |
No tracking, fastest path |
OnlyId |
Only IId<T> types tracked (Binary only) |
All |
All reference types tracked (required for JSON $ref) |
Loretta
4a6e101410