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 a60f2b8fdec5893ac9540bd3704acb0d0e8684ef Author: chaokunyang <[email protected]> AuthorDate: Tue Jul 28 02:11:09 2026 +0000 🔄 synced local 'docs/specification/' with remote 'docs/specification/' --- docs/specification/xlang_implementation_guide.md | 192 ++++++++++++++--------- 1 file changed, 118 insertions(+), 74 deletions(-) diff --git a/docs/specification/xlang_implementation_guide.md b/docs/specification/xlang_implementation_guide.md index 85d2fd8f86..311f69a657 100644 --- a/docs/specification/xlang_implementation_guide.md +++ b/docs/specification/xlang_implementation_guide.md @@ -219,19 +219,75 @@ 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. +#### C# generated structural serializers + +C# uses one target-keyed source-generation path for ordinary and external +structural serializers. `ForyStructAttribute` is non-inherited: every +first-party class that participates in a serializable hierarchy carries a +direct annotation. An external declaration supplies the equivalent contract +for an unmodifiable target. + +For one concrete ordinary class, compilation-level hierarchy discovery +produces two independent immutable outputs: + +- one flattened wire-member set, used by field ordering, schema hashes, + `TypeMeta`, and generated reads and writes; and +- one shallow-storage model, used only by graph-memory accounting. + +The wire set is assembled base-first from declaration-owned generated +descriptors. Property override chains collapse to one logical slot before the +complete set is validated and sorted by the protocol comparator. Hidden +members retain their exact declaring type. A generated child never calls a +parent serializer body and never encodes a base object as a nested value. + +Each inheritable ordinary class publishes a target-keyed compiler contract +containing: + +- its exact target; +- its exact directly declared wire-member count; +- one descriptor on each deterministic accessor for a directly declared wire + member: fields use a writable `ref` accessor, while properties use a getter + plus a matching setter; and +- a public static readonly cumulative `HierarchyShallowBytes` value. + +The provider's shallow value is the immediate parent provider value plus only +the current class's directly declared physical instance fields. A sealed +concrete serializer uses the same cumulative expression privately and does not +publish a provider marker, descriptors, or hierarchy value. The concrete +serializer adds object self storage once. Properties never directly add +storage, while private, readonly, compiler-generated, and non-wire instance +fields do. Referenced child compilations consume only an accessible provider +contract; they do not import, enumerate, or reconstruct private parent fields. +Provider-only targets emit a static provider; a concrete non-sealed +serializer carries the same contract without a second type or forwarding path. +An internal provider is available only to assemblies granted normal C# +accessibility, such as through `InternalsVisibleTo`; an inaccessible or +extern-alias-only contract does not own another compilation's hierarchy. + +The generator emits ordinary direct member access whenever C# accessibility +allows it. A provider publishes an accessor when a referenced child must reach +declaration-owned state. The accessor signature preserves the member's CLR +type and nullability metadata. Missing or ambiguous providers fail generation. + +An abstract ordinary class emits only its generated hierarchy provider and does not +create a serializer instance or registration. Its property descriptors may +publish unresolved abstract override slots; a concrete descendant must supply +the callable implementation. Concrete classes require legal parameterless +construction and retain the existing allocate-before-children and reference +publication order. `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: +A local non-generic abstract class supplies an external structural declaration, +while an empty non-generic static class selects an external enum target: ```csharp [ForyStruct(Target = typeof(ThirdParty.User))] internal abstract class UserSerializer { - [ForyField(1)] + [ForyField( + 1, + TargetDeclaringType = typeof(ThirdParty.User), + TargetMemberName = "<Name>k__BackingField")] public abstract string Name { get; } } @@ -241,80 +297,68 @@ internal static class StatusSerializer } ``` -These declarations are compile-time generator input only. They are never +External 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 for wire fields. An ignored declaration field -supplies only graph-memory storage and has no wire metadata or target access. -For external classes, the shallow graph estimate includes declared wire -fields, ignored declaration fields, and discoverable public instance target -fields. An ignored declaration does not require its target storage to be -visible to the generator. When it resolves to the same public field, the field -symbol is used only to avoid counting that storage twice. +or used as wire identities. Runtime type positions, construction, `TypeInfo`, +metadata, reference publication, generated factory keys, roots, fields, +dynamic values, and carriers use the target type. + +An external member may bind a visible same-name field or property. For external +class targets, setting `TargetDeclaringType` and `TargetMemberName` instead +declares one exact field on the target or a non-`object` ancestor. An exact wire mapping +also supplies physical storage; `Ignore = true` supplies only shallow storage. +External struct targets support visible member mappings only. Unmapped visible +public instance fields are added to external class shallow storage once. The +generator never discovers private fields from a referenced assembly. + +`BaseOnly = true` makes an external class declaration the terminal provider for +a complete third-party hierarchy prefix. It may list exact target and +target-ancestor fields and publishes no standalone factory or registration. An +ordinary child consumes this provider exactly as it consumes an ordinary +parent provider. A `BaseOnly` target may be abstract or nonconstructible +because only the concrete ordinary child is materialized. + +Exact private mappings are version-pinned package ABI declarations. Wire +accessors fail with the CLR missing-field error if the target ABI changes; +there is no reflection or alternate-member fallback. On .NET 8, the generator +rejects private wire access whose declaring owner or signature is generic. +Visible closed-generic members and explicit storage-only field mappings remain +supported for class targets. An inaccessible pointer field cannot be +distinguished from fixed-buffer storage without importing private layout, so an +exact private pointer mapping is rejected. + +Standalone external structural targets require an accessible concrete class +or struct, legal parameterless construction, and writable declared wire state. +Constructor-only, factory-only, readonly, init-only, converted, and +custom-wire shapes use a manual `Serializer<T>`. Explicit nullability must +match when target metadata is annotated; otherwise the declaration supplies +schema nullability. 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 -wire 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. Ignored properties are declaration-owned budget hints and -do not bind or access target members. Immutable, constructor-only, -factory-only, init-only, readonly, renamed, converted, or inaccessible wire -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. +generator-owned `Evolving` into target `TypeInfo`. Generated enums and unions +use `TypeResolver.RegisterGenerated<T, TSerializer>()`. Abstract ordinary and +`BaseOnly` providers do not register. Multiple generated owners for one target +are rejected during generation or deterministically on the cold +cross-assembly factory-registration path. Manual serializer replacement keeps +the resolver's normal target rules. + +C# carrier composition remains 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, external, and manual +serializers use the same carrier bodies. There is no hierarchy runtime lookup, +provider object, callback, schema tree, per-element dispatch, or additional +value allocation. 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. +`TypeResolver`. Arbitrary statically typed interface or base-class +polymorphism remains unsupported. Flat ordinary and external generated hot +bodies retain the same work and allocation shape apart from target/member +metadata tokens; hierarchy composition is static initialization and +compile-time metadata work. Rust names these serializer operation boundaries explicitly: --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
