This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit b8d7caff502ed172e6dab2f86d6a445034b0506f Author: chaokunyang <[email protected]> AuthorDate: Mon Jul 27 09:27:58 2026 +0000 🔄 synced local 'docs/specification/' with remote 'docs/specification/' --- docs/specification/xlang_implementation_guide.md | 90 ++++++++++++++++++++++++ docs/specification/xlang_type_mapping.md | 6 ++ 2 files changed, 96 insertions(+) diff --git a/docs/specification/xlang_implementation_guide.md b/docs/specification/xlang_implementation_guide.md index 1f7be2a828..7a71637346 100644 --- a/docs/specification/xlang_implementation_guide.md +++ b/docs/specification/xlang_implementation_guide.md @@ -219,6 +219,96 @@ The ownership split is: - `Fory` owns root framing and operation setup/reset - `TypeResolver` owns registration and dynamic lookup +#### C# target-keyed external serializers + +C# external-type serialization uses the target-keyed serializer resolver. + +`ForyStructAttribute` and `ForyEnumAttribute` carry an optional `Target` type. +A local non-generic abstract class supplies an external struct schema, while an +empty non-generic static class selects an external enum target: + +```csharp +[ForyStruct(Target = typeof(ThirdParty.User))] +internal abstract class UserSerializer +{ + [ForyField(1)] + public abstract string Name { get; } +} + +[ForyEnum(Target = typeof(ThirdParty.Status))] +internal static class StatusSerializer +{ +} +``` + +These declarations are compile-time generator input only. They are never +instantiated, reflected over by the runtime, registered, reference-published, +or used as wire identities. The generator emits the canonical +`Serializer<ThirdParty.User>` structural form and registers its generated +factory under `ThirdParty.User`. External enums reuse +`EnumSerializer<ThirdParty.Status>`. Application registration uses the target +APIs: + +```csharp +fory.Register<ThirdParty.User>(100); +fory.Register<ThirdParty.Status>("example.Status"); +``` + +The C# generator model must separate declaration identity from target identity, +then reuse one structural serializer emitter for both ordinary and external +targets. Runtime type positions, construction, member access, `TypeInfo`, +compatible metadata, graph-memory ownership, reference publication, generated +factory keys, root lookup, and dynamic lookup use the target. The declaration +supplies only field names, IDs, schema descriptors, nullability, and the +structural `Evolving` setting. + +Every generated ordinary or external struct uses +`TypeResolver.RegisterGeneratedStruct<T, TSerializer>(bool evolving)` to carry +generator-owned `Evolving` into the target `TypeInfo`. Generated enums and +unions use `TypeResolver.RegisterGenerated<T, TSerializer>()`. `TypeInfo` does +not recover structural metadata by reflecting a target attribute. The runtime +must not reflect the external declaration, add a serializer capability +interface, or create a second metadata registry. Multiple generated +declarations for one target are rejected during generation when visible in one +compilation and fail deterministically on the cold generated-factory +registration path across assemblies. Explicit manual serializer registration +uses the resolver's target replacement rules. + +External structural targets require an accessible concrete class or struct, +legal parameterless construction, and directly readable and assignable +members. Schema properties match target fields or properties by case-sensitive +name and exact CLR/generic type. Explicit nullability must match; when target +metadata is nullable-oblivious, the declaration supplies schema nullability. +Immutable, constructor-only, factory-only, init-only, readonly, renamed, +converted, or inaccessible shapes use a manual `Serializer<T>`. Generated +class reads allocate and publish the final target before recursive children; +target structs are inline values. The declaration is never a temporary graph +owner. + +C# carrier composition is target-based. The resolver recursively +binds `Nullable<T>`, one-dimensional `T[]`, `List<T>`, `LinkedList<T>`, +`Queue<T>`, `Stack<T>`, `HashSet<T>`, `SortedSet<T>`, +`ImmutableHashSet<T>`, `Dictionary<TKey, TValue>`, +`SortedDictionary<TKey, TValue>`, `SortedList<TKey, TValue>`, +`ConcurrentDictionary<TKey, TValue>`, and +`NullableKeyDictionary<TKey, TValue>`. Ordinary generated targets, external +structural serializers, manual serializers, fields, and roots use the same +carrier bodies. External-type serialization has no carrier-provider family, +field selector, root selector, callback, schema tree, per-element external +dispatch, or additional allocation. Collection-interface, tuple, fixed-array, +multidimensional-array, memory, and reference-wrapper families are unsupported. + +Dynamic `object` values and unions resolve concrete target types through +`TypeResolver`. Arbitrary statically typed interface or base-class polymorphism +is unsupported. + +External and equivalent ordinary generated hot bodies must be +instruction-shape equivalent apart from target/member metadata tokens. Target +selection is compile-time only. Cold duplicate-target error construction must +stay out of successful hot-path inlining, and any dedicated cold error entrance +must be marked no-inline. Successful serializer dispatch must not be marked +cold. + Rust names these serializer operation boundaries explicitly: - `Serializer::write` and `Serializer::read` process a complete value, diff --git a/docs/specification/xlang_type_mapping.md b/docs/specification/xlang_type_mapping.md index a3e877710a..800360f215 100644 --- a/docs/specification/xlang_type_mapping.md +++ b/docs/specification/xlang_type_mapping.md @@ -112,6 +112,12 @@ FDL spells them as an encoding modifier plus a semantic integer type. Notes: +- C# external-type serialization maps a third-party class/struct or enum + through a local + `ForyStruct(Target = typeof(...))` or + `ForyEnum(Target = typeof(...))` serializer declaration. The runtime target + still uses the C# mapping shown above; declaration ownership is not a wire + distinction. - Python `pyfory.Float16` and `pyfory.BFloat16` are reserved annotation markers; scalar values deserialize as native Python `float`. - Python `BoolArray`, `Int8Array`, `Int16Array`, `Int32Array`, `Int64Array`, `UInt8Array`, `UInt16Array`, `UInt32Array`, `UInt64Array`, `Float16Array`, `BFloat16Array`, `Float32Array`, and `Float64Array` are public dense-array wrappers with list-like sequence behavior. - JavaScript `BoolArray`, fallback `Float16Array`, and `BFloat16Array` are public dense-array wrappers backed by `Uint8Array` or `Uint16Array`. Scalar `float16` and `bfloat16` values use `number`. A JavaScript environment with native `Float16Array` may return that native carrier for `array<float16>`. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
