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 ffae5a429282e3253a03c6be4524761d24c5a679 Author: chaokunyang <[email protected]> AuthorDate: Tue Jul 28 12:18:16 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/csharp/basic-serialization.md | 2 +- ...manual-serializers.md => custom-serializers.md} | 12 +++---- docs/guide/csharp/external-types.md | 8 ++--- docs/guide/csharp/grpc-support.md | 2 +- docs/guide/csharp/index.md | 6 ++-- docs/guide/csharp/supported-types.md | 2 +- docs/guide/csharp/type-registration.md | 6 ++-- docs/guide/dart/code-generation.md | 4 +-- docs/guide/dart/custom-serializers.md | 6 ++-- docs/guide/dart/external-types.md | 8 ++--- docs/guide/dart/index.md | 4 +-- docs/guide/dart/inheritance.md | 2 +- docs/guide/dart/troubleshooting.md | 10 +++--- docs/guide/dart/type-registration.md | 6 ++-- docs/guide/dart/web-platform-support.md | 6 ++-- docs/guide/java/grpc-support.md | 2 +- docs/guide/kotlin/grpc-support.md | 2 +- docs/guide/python/xlang-serialization.md | 2 +- docs/guide/rust/basic-serialization.md | 4 +-- ...manual-serializers.md => custom-serializers.md} | 14 ++++---- docs/guide/rust/external-types.md | 38 +++++++++++----------- docs/guide/rust/index.md | 4 +-- docs/guide/rust/native-serialization.md | 4 +-- docs/guide/rust/polymorphism.md | 6 ++-- docs/guide/rust/schema-evolution.md | 4 +-- docs/guide/rust/schema-metadata.md | 2 +- docs/guide/rust/troubleshooting.md | 4 +-- docs/guide/rust/type-registration.md | 6 ++-- docs/guide/scala/grpc-support.md | 2 +- docs/guide/swift/basic-serialization.md | 4 +-- ...manual-serializers.md => custom-serializers.md} | 16 ++++----- docs/guide/swift/external-types.md | 12 +++---- docs/guide/swift/index.md | 4 +-- docs/guide/swift/troubleshooting.md | 2 +- docs/guide/swift/type-registration.md | 2 +- docs/guide/swift/xlang-serialization.md | 2 +- 36 files changed, 110 insertions(+), 110 deletions(-) diff --git a/docs/guide/csharp/basic-serialization.md b/docs/guide/csharp/basic-serialization.md index 6c8e0660c0..b6bf5a7cbb 100644 --- a/docs/guide/csharp/basic-serialization.md +++ b/docs/guide/csharp/basic-serialization.md @@ -167,7 +167,7 @@ fory.Serialize<object?>(dynamicWriter, value); - Reuse the same `Fory` or `ThreadSafeFory` instance for better performance. - Primitive types and collections do not require user registration. - Register user types handled by `[ForyStruct]`, `[ForyEnum]`, `[ForyUnion]`, - external structural serializers, or manual serializers explicitly. + external structural serializers, or custom serializers explicitly. ## Related Topics diff --git a/docs/guide/csharp/manual-serializers.md b/docs/guide/csharp/custom-serializers.md similarity index 90% rename from docs/guide/csharp/manual-serializers.md rename to docs/guide/csharp/custom-serializers.md index cc05c6a95f..9cf9277606 100644 --- a/docs/guide/csharp/manual-serializers.md +++ b/docs/guide/csharp/custom-serializers.md @@ -1,7 +1,7 @@ --- -title: Manual Serializers +title: Custom Serializers sidebar_position: 11 -id: manual_serializers +id: custom_serializers license: | Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with @@ -19,15 +19,15 @@ license: | limitations under the License. --- -Use a manual serializer when a type is not generated with `[ForyStruct]` or +Use a custom serializer when a type is not generated with `[ForyStruct]` or requires specialized encoding. [External-type serialization](external-types.md) generates serializers for mutable third-party targets, including exact private or renamed fields. Use a -manual serializer for immutable, constructor-only, factory-only, readonly, +custom serializer for immutable, constructor-only, factory-only, readonly, init-only, converted, or custom-wire targets. On .NET 8, a private external wire field whose declaring type or accessor signature is generic also requires -a manual serializer. Exact storage-only mappings do not emit private accessors. +a custom serializer. Exact storage-only mappings do not emit private accessors. ## Implement `Serializer<T>` @@ -88,7 +88,7 @@ fory.Register<Point, PointSerializer>("com.example.Point"); 1. Keep serializers deterministic and symmetric. 2. Use varint/fixed/tagged encoding intentionally for integer-heavy payloads. -3. Register manual serializers on all reader/writer peers. +3. Register custom serializers on all reader/writer peers. 4. Prefer generated `[ForyStruct]` serializers for normal domain models. ## Related Topics diff --git a/docs/guide/csharp/external-types.md b/docs/guide/csharp/external-types.md index 8ee486f246..c16c7460f2 100644 --- a/docs/guide/csharp/external-types.md +++ b/docs/guide/csharp/external-types.md @@ -138,7 +138,7 @@ External struct targets support visible field and property mappings only. Exact mappings and `Ignore` are class-only because value storage belongs to the holder that materializes the struct. An inaccessible pointer field is also rejected: without reading private package layout, the generator cannot -distinguish pointer storage from a fixed buffer. Use a manual serializer for +distinguish pointer storage from a fixed buffer. Use a custom serializer for these shapes. ## Third-Party Base Classes @@ -239,11 +239,11 @@ derived behavior after deserialization. A standalone external target must be an accessible concrete class or struct with a legal parameterless construction path and writable declared wire state. Constructor-bound, factory-only, readonly, init-only, converted, or -custom-wire targets require a [manual serializer](manual-serializers.md). +custom-wire targets require a [custom serializer](custom-serializers.md). Closed generic targets such as `ThirdParty.Box<string>` are supported. On .NET 8, a private wire member whose declaring type or signature is generic -requires a manual serializer. Visible generic members and exact ignored class +requires a custom serializer. Visible generic members and exact ignored class field mappings remain supported. Open generic targets are not supported. ## Enum Targets @@ -359,6 +359,6 @@ This feature does not add arbitrary interface or base-class polymorphism. - [Schema Metadata](schema-metadata.md) - [Type Registration](type-registration.md) -- [Manual Serializers](manual-serializers.md) +- [Custom Serializers](custom-serializers.md) - [References](references.md) - [Schema Evolution](schema-evolution.md) diff --git a/docs/guide/csharp/grpc-support.md b/docs/guide/csharp/grpc-support.md index e02273b710..ecb5e5b288 100644 --- a/docs/guide/csharp/grpc-support.md +++ b/docs/guide/csharp/grpc-support.md @@ -128,7 +128,7 @@ public sealed class GreeterService : Greeter.GreeterBase Generated request and response types are registered by the generated schema module used by the service companion, so service implementations do not perform -manual serializer registration. +custom serializer registration. ## Create a Client diff --git a/docs/guide/csharp/index.md b/docs/guide/csharp/index.md index 5623e26987..97c8cec38b 100644 --- a/docs/guide/csharp/index.md +++ b/docs/guide/csharp/index.md @@ -82,7 +82,7 @@ User decoded = fory.Deserialize<User>(payload); - `Serialize<T>(in T value)` / `Deserialize<T>(...)` - `Serialize<object?>(...)` / `Deserialize<object?>(...)` for dynamic payloads - `Register<T>(uint typeId)` and name registration APIs -- `Register<T, TSerializer>(...)` for manual serializers +- `Register<T, TSerializer>(...)` for custom serializers ## Documentation @@ -92,9 +92,9 @@ User decoded = fory.Deserialize<User>(payload); | [Basic Serialization](basic-serialization.md) | Typed and dynamic serialization APIs | | [Xlang Serialization](xlang-serialization.md) | Interoperability guidance | | [Schema Metadata](schema-metadata.md) | `[ForyField]` ids and schema type descriptors | -| [Type Registration](type-registration.md) | Registering user types and manual serializers | +| [Type Registration](type-registration.md) | Registering user types and custom serializers | | [External Types](external-types.md) | Serializers for third-party types | -| [Manual Serializers](manual-serializers.md) | Implementing `Serializer<T>` | +| [Custom Serializers](custom-serializers.md) | Implementing `Serializer<T>` | | [References](references.md) | Shared/circular reference handling | | [Schema Evolution](schema-evolution.md) | Compatible mode behavior | | [Supported Types](supported-types.md) | Built-in and generated type support | diff --git a/docs/guide/csharp/supported-types.md b/docs/guide/csharp/supported-types.md index e6c6250a72..31d4f4ed1e 100644 --- a/docs/guide/csharp/supported-types.md +++ b/docs/guide/csharp/supported-types.md @@ -84,7 +84,7 @@ This page summarizes built-in and generated type support in Apache Fory™ C#. declaration - `[ForyEnum]` enums and `[ForyUnion]` ADT records - External class, struct, and enum targets through serializer declarations -- Manual serializer types registered through `Register<T, TSerializer>(...)` +- Custom serializer types registered through `Register<T, TSerializer>(...)` - `Union` / `Union2<...>` typed union support `[ForyEnum]` numeric values are unsigned 32-bit wire tags and must be in the diff --git a/docs/guide/csharp/type-registration.md b/docs/guide/csharp/type-registration.md index 6496348dc8..5dc5eebb3f 100644 --- a/docs/guide/csharp/type-registration.md +++ b/docs/guide/csharp/type-registration.md @@ -54,14 +54,14 @@ separately: fory.Register<User>("com.example", "User"); ``` -## Register a Manual Serializer +## Register a Custom Serializer ```csharp Fory fory = Fory.Builder().Build(); fory.Register<MyType, MyTypeSerializer>(200); ``` -Name-based manual serializer registration is also supported: +Name-based custom serializer registration is also supported: ```csharp fory.Register<MyType, MyTypeSerializer>("com.example.MyType"); @@ -96,5 +96,5 @@ fory.Register<Order>(101); - [Basic Serialization](basic-serialization.md) - [External Types](external-types.md) -- [Manual Serializers](manual-serializers.md) +- [Custom Serializers](custom-serializers.md) - [Xlang Serialization](xlang-serialization.md) diff --git a/docs/guide/dart/code-generation.md b/docs/guide/dart/code-generation.md index a3a06745e2..36a6af8298 100644 --- a/docs/guide/dart/code-generation.md +++ b/docs/guide/dart/code-generation.md @@ -122,11 +122,11 @@ When using evolving structs, also assign stable field IDs with `@ForyField(id: . Included inherited and direct fields share this one ID namespace. Do not reuse an ID among fields included in the same child schema. -## Choosing Generated or Manual Serialization +## Choosing Generated or Custom Serialization Use an [external structural serializer](external-types.md) when another package's class exposes matching public getters and a safe public construction -path. Use a [manual serializer](custom-serializers.md) when the wire body, +path. Use a [custom serializer](custom-serializers.md) when the wire body, field names, values, or construction need custom logic. ## Related Topics diff --git a/docs/guide/dart/custom-serializers.md b/docs/guide/dart/custom-serializers.md index c9714f60fa..4becea078b 100644 --- a/docs/guide/dart/custom-serializers.md +++ b/docs/guide/dart/custom-serializers.md @@ -1,5 +1,5 @@ --- -title: Manual Serializers +title: Custom Serializers sidebar_position: 11 id: custom_serializers license: | @@ -19,7 +19,7 @@ license: | limitations under the License. --- -A manual serializer lets you control exactly how a type is encoded and decoded. +A custom serializer lets you control exactly how a type is encoded and decoded. Use one when: - you need a completely custom binary layout @@ -118,7 +118,7 @@ final class ShapeSerializer extends UnionSerializer<Shape> { } ``` -## Circular References in Manual Serializers +## Circular References in Custom Serializers If your serializer can encounter circular object graphs, bind the object to the reference tracker **before** reading its nested fields: diff --git a/docs/guide/dart/external-types.md b/docs/guide/dart/external-types.md index 20540fad76..7f62e24b29 100644 --- a/docs/guide/dart/external-types.md +++ b/docs/guide/dart/external-types.md @@ -184,7 +184,7 @@ A constructor-based target cannot decode a statically known reference-tracked path back to itself because the target does not exist until its constructor arguments have been read. This includes the target nested as a `List` or `Set` element or as a `Map` key or value. Generation rejects these schemas. Use a -mutable two-phase target or a manual serializer when cycles are required. +mutable two-phase target or a custom serializer when cycles are required. Indirect cycles that cannot be determined from the declaration are also unsupported for constructor-based targets. @@ -305,9 +305,9 @@ abstract final class UserSerializer { Keep field IDs and the registered type identity stable across peers. A field name must still match the corresponding property on the local target class. -## When to Use a Manual Serializer +## When to Use a Custom Serializer -Use a [manual serializer](custom-serializers.md) when the target needs a custom +Use a [custom serializer](custom-serializers.md) when the target needs a custom wire body, field-name translation, value conversion, factory-only construction, private state, or any reconstruction rule that cannot be expressed through matching public getters, constructor parameters, and @@ -320,4 +320,4 @@ setters. - [Type Registration](type-registration.md) - [Schema Metadata](schema-metadata.md) - [Schema Evolution](schema-evolution.md) -- [Manual Serializers](custom-serializers.md) +- [Custom Serializers](custom-serializers.md) diff --git a/docs/guide/dart/index.md b/docs/guide/dart/index.md index 2317e5acaa..035bc8f063 100644 --- a/docs/guide/dart/index.md +++ b/docs/guide/dart/index.md @@ -32,7 +32,7 @@ languages. - **Inheritance**: ordinary structs flatten concrete superclass and mixin storage into one schema - **Schema evolution**: add or remove fields without breaking existing messages - **Circular references**: optional reference tracking handles shared or recursive object graphs -- **Escape hatch**: write a manual serializer for any type that cannot be annotated +- **Escape hatch**: write a custom serializer for any type that cannot be annotated ## Quick Start @@ -147,7 +147,7 @@ constructors, mixins, and field inclusion options. | [Xlang Serialization](xlang-serialization.md) | Interoperability rules and field alignment | | [Schema Metadata](schema-metadata.md) | `@ForyField`, field IDs, nullability, references, polymorphism | | [Type Registration](type-registration.md) | ID-based vs name-based registration and registration rules | -| [Manual Serializers](custom-serializers.md) | Manual `Serializer<T>` implementations and unions | +| [Custom Serializers](custom-serializers.md) | Custom `Serializer<T>` implementations and unions | | [Supported Types](supported-types.md) | Built-in xlang values, wrappers, collections, and structs | | [Schema Evolution](schema-evolution.md) | Compatible structs and evolving schemas | | [Web Platform Support](web-platform-support.md) | Dart VM/AOT, Flutter, and web support, limits, and validation | diff --git a/docs/guide/dart/inheritance.md b/docs/guide/dart/inheritance.md index 4ca58612d0..da126573ae 100644 --- a/docs/guide/dart/inheritance.md +++ b/docs/guide/dart/inheritance.md @@ -160,7 +160,7 @@ value is ignored or transformed. Filtering a private field does not let Fory invent constructor inputs. If a required child constructor parameter no longer has a serialized field source, generation fails. Use a reconstructing constructor, declaration-owned -`@ForyField(ignore: true)` where appropriate, or a manual serializer. +`@ForyField(ignore: true)` where appropriate, or a custom serializer. ## Mixins, Generics, and Field IDs diff --git a/docs/guide/dart/troubleshooting.md b/docs/guide/dart/troubleshooting.md index c99fee9b69..696cba7b3d 100644 --- a/docs/guide/dart/troubleshooting.md +++ b/docs/guide/dart/troubleshooting.md @@ -77,7 +77,7 @@ and direct constructor initializers across the hierarchy. A parameter with the same name and type is insufficient if it is unused or its value is cast, transformed, or passed through a function. Forward the decoded value directly to the exact field, mark the field declaration with -`@ForyField(ignore: true)`, or use a manual serializer. If +`@ForyField(ignore: true)`, or use a custom serializer. If `ignoreInheritedPrivateFields` removes the only serialized source for a required constructor parameter, Fory still reports this error rather than inventing a value. See @@ -88,7 +88,7 @@ inventing a value. See A subclass field or accessor can hide an included ancestor storage slot while both physical slots remain on the object. Fory rejects this shape instead of choosing one slot and losing the other. Rename or remove the hiding member, -ignore the ancestor field at its declaration, or use a manual serializer. For +ignore the ancestor field at its declaration, or use a custom serializer. For private ancestor state, setting `ignoreInheritedPrivateFields: true` omits all private ancestor storage from that child schema. @@ -105,7 +105,7 @@ An external structural serializer requires: Select a public named constructor with `@ForyStruct(target: Type, constructor: 'name')`. Use a -[manual serializer](custom-serializers.md) when the target requires a factory, +[custom serializer](custom-serializers.md) when the target requires a factory, private state, field conversion, or name translation. ## `Deserialized value has type ..., expected ...` @@ -124,7 +124,7 @@ To preserve identity: - For fields inside a `@ForyStruct`, add `@ForyField(ref: true)` to those fields. - For a top-level collection, pass `trackRef: true` to `fory.serialize(...)`. -- In a manual serializer, use `context.writeRef` / `context.readRef` and call `context.reference(obj)` before reading nested fields. +- In a custom serializer, use `context.writeRef` / `context.readRef` and call `context.reference(obj)` before reading nested fields. ## Cross-language field mismatch (missing data or wrong values) @@ -219,6 +219,6 @@ separate protobuf service endpoint for generic protobuf clients. - [Struct Inheritance](inheritance.md) - [Xlang Serialization](xlang-serialization.md) - [Code Generation](code-generation.md) -- [Manual Serializers](custom-serializers.md) +- [Custom Serializers](custom-serializers.md) - [Web Platform Support](web-platform-support.md) - [gRPC Support](grpc-support.md) diff --git a/docs/guide/dart/type-registration.md b/docs/guide/dart/type-registration.md index 938f0a046e..743c0ec2e0 100644 --- a/docs/guide/dart/type-registration.md +++ b/docs/guide/dart/type-registration.md @@ -89,7 +89,7 @@ ExternalSerializersForyModule.register( See [External-Type Serialization](external-types.md) for the declaration. -## Registering a Manual Serializer +## Registering a Custom Serializer Pass a serializer instance directly when a type needs custom wire or construction logic: @@ -102,7 +102,7 @@ fory.registerSerializer( ); ``` -See [Manual Serializers](custom-serializers.md) for how to implement a serializer. +See [Custom Serializers](custom-serializers.md) for how to implement a serializer. ## Rules to Follow @@ -123,4 +123,4 @@ The same numeric ID or name must be used in every peer that reads or writes the - [Code Generation](code-generation.md) - [External-Type Serialization](external-types.md) - [Xlang Serialization](xlang-serialization.md) -- [Manual Serializers](custom-serializers.md) +- [Custom Serializers](custom-serializers.md) diff --git a/docs/guide/dart/web-platform-support.md b/docs/guide/dart/web-platform-support.md index ece2829216..a28e68d67d 100644 --- a/docs/guide/dart/web-platform-support.md +++ b/docs/guide/dart/web-platform-support.md @@ -80,7 +80,7 @@ cd dart/packages/fory dart run build_runner build ``` -The registration call is the same on VM/AOT, Flutter, and web. Manual +The registration call is the same on VM/AOT, Flutter, and web. Custom serializers use `registerSerializer(...)`; generated structs use the generated `register` wrapper. @@ -143,9 +143,9 @@ class StorageExtent { } ``` -## Manual Serializers +## Custom Serializers -Manual serializers can use the same `Buffer`, `WriteContext`, and `ReadContext` +Custom serializers can use the same `Buffer`, `WriteContext`, and `ReadContext` APIs on VM/AOT, Flutter, and web. For 64-bit values: - Use `buffer.writeInt64(Int64(...))` and `buffer.readInt64()` for full-range diff --git a/docs/guide/java/grpc-support.md b/docs/guide/java/grpc-support.md index 2239444fa1..3e1c608a9e 100644 --- a/docs/guide/java/grpc-support.md +++ b/docs/guide/java/grpc-support.md @@ -150,7 +150,7 @@ public final class GreeterServer { ``` Generated request and response types are registered by the generated code, so -service implementations do not perform manual serializer registration. +service implementations do not perform custom serializer registration. ## Create a Client diff --git a/docs/guide/kotlin/grpc-support.md b/docs/guide/kotlin/grpc-support.md index c18eabebfa..79c32848b1 100644 --- a/docs/guide/kotlin/grpc-support.md +++ b/docs/guide/kotlin/grpc-support.md @@ -96,7 +96,7 @@ For this schema, the Kotlin generator emits: Run KSP when compiling the generated model files so the schema serializers are available at runtime. Generated request and response types are registered by the generated schema module used by the service companion, so service -implementations do not perform manual serializer registration. +implementations do not perform custom serializer registration. ## Implement a Server diff --git a/docs/guide/python/xlang-serialization.md b/docs/guide/python/xlang-serialization.md index 34cec4048d..1c300d894e 100644 --- a/docs/guide/python/xlang-serialization.md +++ b/docs/guide/python/xlang-serialization.md @@ -199,7 +199,7 @@ Fory row-format schemas. ## Differences from Python Native Mode -The binary protocol and API are similar to `pyfory`'s Python native mode, but Python native mode can serialize any Python object—including global functions, local functions, lambdas, local classes, and types with customized serialization using `__getstate__/__reduce__/__reduce_ex__`, which are **not allowed** in xlang mode. +The binary protocol and API are similar to `pyfory`'s Python native mode, but Python native mode can serialize any Python object—including global functions, local functions, lambdas, local classes, and types with custom serialization using `__getstate__/__reduce__/__reduce_ex__`, which are **not allowed** in xlang mode. ## See Also diff --git a/docs/guide/rust/basic-serialization.md b/docs/guide/rust/basic-serialization.md index a0253dce93..d3e92ed9a2 100644 --- a/docs/guide/rust/basic-serialization.md +++ b/docs/guide/rust/basic-serialization.md @@ -180,7 +180,7 @@ let mut reader = Reader::new(&buf); let decoded: MyStruct = fory.deserialize_from(&mut reader)?; ``` -When the Rust value type uses an external structural serializer or manual +When the Rust value type uses an external structural serializer or custom serializer, select it explicitly at the root: ```rust @@ -215,5 +215,5 @@ all supported carriers, and registration. - [Type Registration](type-registration.md) - Registering types - [References](references.md) - Shared and circular references -- [Manual Serializers](manual-serializers.md) - Customized serialization +- [Custom Serializers](custom-serializers.md) - Custom serialization - [External-Type Serialization](external-types.md) - Third-party values and carrier roots diff --git a/docs/guide/rust/manual-serializers.md b/docs/guide/rust/custom-serializers.md similarity index 94% rename from docs/guide/rust/manual-serializers.md rename to docs/guide/rust/custom-serializers.md index c68071f954..82d5291821 100644 --- a/docs/guide/rust/manual-serializers.md +++ b/docs/guide/rust/custom-serializers.md @@ -1,7 +1,7 @@ --- -title: Manual Serializers +title: Custom Serializers sidebar_position: 10 -id: manual_serializers +id: custom_serializers license: | Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with @@ -19,14 +19,14 @@ license: | limitations under the License. --- -Use a manual serializer when derive cannot express the type's serialized +Use a custom serializer when derive cannot express the type's serialized representation or when an opaque encoding is intentional. A serializer is a type-level implementation and names the value it handles through `Target`. For a public third-party struct or enum whose schema should remain structural, prefer [External-Type Serialization](external-types.md). -## Implement a Manual Serializer +## Implement a Custom Serializer This example uses a local type as its own serializer: @@ -127,12 +127,12 @@ struct Request { } ``` -Manual serializer bodies are opaque. Compatible mode does not map fields +Custom serializer bodies are opaque. Compatible mode does not map fields inside them. ## Support `Arc<dyn Any + Send + Sync>` -If a manual serializer's target must be materialized behind +If a custom serializer's target must be materialized behind `Arc<dyn Any + Send + Sync>` or a synchronized application trait, implement `read_arc_any`: @@ -188,7 +188,7 @@ let value = context.reader.read_f64()?; For variable-size bodies, validate readable bytes and graph-memory limits before allocating from an encoded length. -When a manual serializer is selected as a child of a variable-size carrier, +When a custom serializer is selected as a child of a variable-size carrier, the carrier must emit at least one aggregate byte per declared element or map entry after its count. Fory rejects serialization when the carrier's complete header, metadata, framing, and child bodies are shorter than that count, so it diff --git a/docs/guide/rust/external-types.md b/docs/guide/rust/external-types.md index 354c37123d..9ff79e3c3e 100644 --- a/docs/guide/rust/external-types.md +++ b/docs/guide/rust/external-types.md @@ -21,7 +21,7 @@ license: | Rust external-type serialization lets an application serialize a type owned by another crate without a wrapper value. Use a derived external structural -serializer for an accessible public schema, or a manual serializer for an +serializer for an accessible public schema, or a custom serializer for an opaque or invariant-bearing type. ## One serializer model @@ -150,9 +150,9 @@ for such an enum while `xlang = true` returns an error before registration is published. Fory does not discard fields, synthesize hidden variant structs, or silently encode the type as EXT. -## Manual serializers +## Custom serializers -Use a manual serializer for opaque types such as UUID or Jiff values: +Use a custom serializer for opaque types such as UUID or Jiff values: ```rust use fory::{Error, ReadContext, Serializer, WriteContext}; @@ -194,12 +194,12 @@ impl Serializer for UuidSerializer { } ``` -Manual serializers use the existing EXT or NAMED_EXT wire kinds. Their internal +Custom serializers use the existing EXT or NAMED_EXT wire kinds. Their internal body evolution is application-owned. If a body length controls an allocation, -the manual serializer must use the read context's byte-availability and graph-memory +the custom serializer must use the read context's byte-availability and graph-memory checks before reserving or allocating that storage. -When a manual serializer is composed under a variable-size carrier, the +When a custom serializer is composed under a variable-size carrier, the carrier's complete bytes after its count must average at least one byte per declared element or map entry. Fory checks this once after writing the carrier and returns an error for a body that is too compact for the paired @@ -209,7 +209,7 @@ exempt. Fory invokes the optional `read_arc_any` method only after reserving the final Arc owner; the method shown above performs that allocation once and must not -reserve the same outer owner again. A manual serializer that does not need sync +reserve the same outer owner again. A custom serializer that does not need sync Arc dynamic carriers omits it and remains valid for typed, Box, and Rc uses; attempting sync Arc materialization then returns an unsupported error. @@ -309,7 +309,7 @@ annotation applies only to its declared node; it never silently propagates through a composite. A node-local `#[fory(with = PackedUsersSerializer)]` may instead select one -manual serializer whose exact target is the whole `Vec`, map, set, array, or +custom serializer whose exact target is the whole `Vec`, map, set, array, or tuple. That field uses opaque EXT/NAMED_EXT encoding and has no child schema. It cannot also use `list`, `map`, `tuple`, `array`, `bytes`, or `encoding`. Recursive list/map/tuple annotations are the distinct choice when the composite @@ -317,7 +317,7 @@ should retain its structural wire kind and only its children need selected serializers. This opaque customization is not a user-declared carrier serializer and cannot compose child serializers. -If that exact whole-container manual serializer is registered, erased polymorphic values +If that exact whole-container custom serializer is registered, erased polymorphic values of the exact target use it. Ordinary unannotated typed fields and roots whose children self-provide keep using the built-in structural container format; explicit carrier serializer roots also keep their declared structural format. @@ -416,14 +416,14 @@ carrier. Standard-library `Weak<T>` is also not an alias for Fory's `RcWeak<T>` or `ArcWeak<T>`. Every child argument is another serializer type. It can be an ordinary serializer targeting itself, -an external structural serializer, a manual leaf serializer, or another Fory-owned carrier +an external structural serializer, a custom leaf serializer, or another Fory-owned carrier serializer. All four forms preserve the carrier's built-in encoding. An ordinary local type is its own serializer, so `HashMapSerializer<String, UserSerializer>` targets `HashMap<String, third_party::User>`. `ArraySerializer<S, N>` uses the same carrier selection as the chosen child serializer. A canonical primitive serializer such as `i32` retains its -dense-array format, while an external structural or manual child serializer +dense-array format, while an external structural or custom child serializer uses LIST even if its target is a primitive Rust type. `VecSerializer<S>` also preserves the ordinary Vec format selected by its @@ -449,7 +449,7 @@ type. A field can select an exact carrier serializer with `with`, such as `tuple(element(...))` grammar, when serializers are selected at recursive child nodes. -An exact whole-container or whole-tuple manual serializer remains a valid opaque +An exact whole-container or whole-tuple custom serializer remains a valid opaque root, but it uses EXT/NAMED_EXT instead of the built-in structural representation and does not select child serializers. @@ -458,7 +458,7 @@ matching `#[fory(with = UserSerializer)]`. ## Registration -Structural and manual serializers use the existing registration categories. +Structural and custom serializers use the existing registration categories. Choose one identity style for each serializer. Numeric registration: @@ -483,12 +483,12 @@ Registration associates the wire identity with the serializer's target. One `Fory` instance accepts only one registered dynamic serializer for a given target. Registering it does not replace an ordinary static serializer or implicitly select it for an unannotated field or root. Complete registration -before the first serialization operation. Register each structural or manual +before the first serialization operation. Register each structural or custom external child; never register a carrier serializer. Carrier composition does not make the entire container a dynamic `Any` target. If the exact whole container must participate in erased dynamic dispatch, -register a manual exact-target serializer and use its EXT/NAMED_EXT +register a custom exact-target serializer and use its EXT/NAMED_EXT representation. ## Polymorphism @@ -496,7 +496,7 @@ representation. Registered external targets participate in `Box<dyn Any>` and `Rc<dyn Any>` through their target identity. A `Send + Sync` target also participates in `Arc<dyn Any + Send + Sync>` when its structural derive generated the Arc -materializer or its manual serializer implemented `read_arc_any`. +materializer or its custom serializer implemented `read_arc_any`. These erased carriers work in native and xlang modes when the selected concrete serializer supports that mode. The Rust carrier and application trait name are @@ -517,7 +517,7 @@ register_trait_type!(Animal, Dog, third_party::Cat); ``` The concrete target list is closed and explicit. Each target can use an -ordinary serializer, an external structural serializer, or a manual serializer. +ordinary serializer, an external structural serializer, or a custom serializer. For `Arc<dyn Trait>`, the sync form requires the trait and listed targets to implement `Send + Sync`: @@ -548,11 +548,11 @@ wrapper conversions. The trait carrier serializers are not registered by ID or name. Applications register each allowed concrete target through its ordinary serializer, -external structural serializer, or manual serializer. +external structural serializer, or custom serializer. ## Related Topics -- [Manual Serializers](manual-serializers.md) +- [Custom Serializers](custom-serializers.md) - [Polymorphism](polymorphism.md) - [Type Registration](type-registration.md) - [Schema Evolution](schema-evolution.md) diff --git a/docs/guide/rust/index.md b/docs/guide/rust/index.md index e519a95fec..638b3ef47d 100644 --- a/docs/guide/rust/index.md +++ b/docs/guide/rust/index.md @@ -196,8 +196,8 @@ fory-derive/ # Procedural macros - [Native Serialization](native-serialization.md) - Rust-only serialization - [References](references.md) - Shared and circular references - [Polymorphism](polymorphism.md) - Trait object serialization -- [Manual Serializers](manual-serializers.md) - Implement customized serialization behavior -- [External-Type Serialization](external-types.md) - External structural and manual serializers +- [Custom Serializers](custom-serializers.md) - Implement custom serialization behavior +- [External-Type Serialization](external-types.md) - External structural and custom serializers plus carrier composition - [Row Format](row-format.md) - Zero-copy row-based format - [gRPC Support](grpc-support.md) - Fory payloads over tonic diff --git a/docs/guide/rust/native-serialization.md b/docs/guide/rust/native-serialization.md index 40a164ac25..8e3cdcae04 100644 --- a/docs/guide/rust/native-serialization.md +++ b/docs/guide/rust/native-serialization.md @@ -111,7 +111,7 @@ Native serialization owns the Rust-specific object surface: - Runtime type dispatch with `Box<dyn Any>`, `Rc<dyn Any>`, and `Arc<dyn Any + Send + Sync>` for registered non-container payloads. Wrap containers in registered structs, enums, or unions, or register an - exact-target manual serializer when an opaque EXT/NAMED_EXT representation + exact-target custom serializer when an opaque EXT/NAMED_EXT representation is appropriate. - Date and time carriers, including optional `chrono` support. @@ -214,7 +214,7 @@ The same serializer works with `compatible(false)` when both peers use the same schema. Multi-field tuple and named variants have no xlang union mapping, so registering this serializer with `xlang(true)` returns an error. See [External-Type Serialization](external-types.md) for field, carrier, root, and -manual serializer composition. +custom serializer composition. ## Performance Guidelines diff --git a/docs/guide/rust/polymorphism.md b/docs/guide/rust/polymorphism.md index 49251da3d5..8e45fa63e2 100644 --- a/docs/guide/rust/polymorphism.md +++ b/docs/guide/rust/polymorphism.md @@ -71,7 +71,7 @@ fory.register::<Cat>(101)?; ``` A listed third-party target can be registered through an external structural -serializer or manual serializer. The list still names the target, not that +serializer or custom serializer. The list still names the target, not that serializer. The generated names are private to the macro's module by default. A library @@ -224,12 +224,12 @@ assert_eq!(dog.name, "Buddy"); ``` Derived serializers support synchronized `Arc` materialization when their -targets satisfy `Send + Sync`. A manual serializer that needs this path +targets satisfy `Send + Sync`. A custom serializer that needs this path implements `read_arc_any`. Generic LIST, SET, and MAP identities do not identify one exact Rust generic target behind `Any`. Put such a container in a registered struct, or register an -exact whole-container manual serializer when an opaque EXT representation is +exact whole-container custom serializer when an opaque EXT representation is intentional. ## Related Topics diff --git a/docs/guide/rust/schema-evolution.md b/docs/guide/rust/schema-evolution.md index f48f58782a..46f86970d3 100644 --- a/docs/guide/rust/schema-evolution.md +++ b/docs/guide/rust/schema-evolution.md @@ -139,7 +139,7 @@ let decoded: third_party::User = ``` Peers must use the same numeric ID or registered name for the logical type. -Adding or removing fields follows the normal compatible-mode rules. A manual +Adding or removing fields follows the normal compatible-mode rules. A custom serializer owns an opaque EXT body instead, so its implementation must define any versioning inside that body. @@ -185,7 +185,7 @@ locally before deserializing unknown cases you need to preserve. payload types must satisfy `Send + Sync`. Direct generic containers are not supported as erased `Any` payloads by their structural carrier registration. Wrap the container in a registered derived type, or register an exact-target -manual serializer when an opaque EXT/NAMED_EXT body is intentional. +custom serializer when an opaque EXT/NAMED_EXT body is intentional. ### Enum Schema Evolution diff --git a/docs/guide/rust/schema-metadata.md b/docs/guide/rust/schema-metadata.md index 1b81d3717b..9c6fa99bdf 100644 --- a/docs/guide/rust/schema-metadata.md +++ b/docs/guide/rust/schema-metadata.md @@ -233,7 +233,7 @@ directly. ### External-Type Field Selection Use `with` to select a serializer whose target is the exact field type. The -serializer can be external structural, manual, or a carrier composition: +serializer can be external structural, custom, or a carrier composition: ```rust use fory::{ForyStruct, VecSerializer}; diff --git a/docs/guide/rust/troubleshooting.md b/docs/guide/rust/troubleshooting.md index 75a55d9667..f6f93a321e 100644 --- a/docs/guide/rust/troubleshooting.md +++ b/docs/guide/rust/troubleshooting.md @@ -39,11 +39,11 @@ fory.register::<MyStruct>(100)?; // Register before use Confirm that: - Every concrete dynamic target is registered through the matching structural, - union, or manual serializer API. + union, or custom serializer API. - The same ID or name mapping is reused on the deserialize side. For external-type serialization, register the selected external structural or -manual serializer, not its third-party target: +custom serializer, not its third-party target: ```rust fory.register::<UserSerializer>(100)?; diff --git a/docs/guide/rust/type-registration.md b/docs/guide/rust/type-registration.md index 0bb260ea4c..1bc148afa1 100644 --- a/docs/guide/rust/type-registration.md +++ b/docs/guide/rust/type-registration.md @@ -59,9 +59,9 @@ let mut fory = Fory::builder().xlang(true).build(); fory.register_by_name::<MyStruct>("com.example.MyStruct")?; ``` -## Register a Manual Serializer +## Register a Custom Serializer -For types that need customized serialization logic, register the manual +For types that need custom serialization logic, register the custom serializer: ```rust @@ -137,5 +137,5 @@ let handles: Vec<_> = (0..4) - [Configuration](configuration.md) - Fory builder options - [Xlang Serialization](xlang-serialization.md) - xlang mode registration -- [Manual Serializers](manual-serializers.md) - Customized serialization +- [Custom Serializers](custom-serializers.md) - Custom serialization - [External-Type Serialization](external-types.md) - Third-party targets and carrier roots diff --git a/docs/guide/scala/grpc-support.md b/docs/guide/scala/grpc-support.md index f89f47d689..9d207c4c26 100644 --- a/docs/guide/scala/grpc-support.md +++ b/docs/guide/scala/grpc-support.md @@ -114,7 +114,7 @@ final class GreeterService extends GreeterGrpc.GreeterImplBase { ``` Generated request and response types are registered by the generated code, so -service implementations do not perform manual serializer registration. +service implementations do not perform custom serializer registration. ## Create a Client diff --git a/docs/guide/swift/basic-serialization.md b/docs/guide/swift/basic-serialization.md index 8446f977b4..13544b61d0 100644 --- a/docs/guide/swift/basic-serialization.md +++ b/docs/guide/swift/basic-serialization.md @@ -125,8 +125,8 @@ let decoded = try fory.deserialize( See [External-Type Serialization](external-types.md) for structural serializers and recursive carrier roots. See -[Manual Serializers](manual-serializers.md) for serializers implemented -directly by a type, retroactive conformances, and separate manual serializers. +[Custom Serializers](custom-serializers.md) for serializers implemented +directly by a type, retroactive conformances, and separate custom serializers. ## Built-in Supported Types diff --git a/docs/guide/swift/manual-serializers.md b/docs/guide/swift/custom-serializers.md similarity index 96% rename from docs/guide/swift/manual-serializers.md rename to docs/guide/swift/custom-serializers.md index 0af5960fdc..c294a939ed 100644 --- a/docs/guide/swift/manual-serializers.md +++ b/docs/guide/swift/custom-serializers.md @@ -1,7 +1,7 @@ --- -title: Manual Serializers +title: Custom Serializers sidebar_position: 10 -id: manual_serializers +id: custom_serializers license: | Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with @@ -19,11 +19,11 @@ license: | limitations under the License. --- -Use a manual serializer when a target needs a custom encoding or cannot meet +Use a custom serializer when a target needs a custom encoding or cannot meet the direct-access requirements of an [external structural serializer](external-types.md). -A manual serializer is not limited to external types: +A custom serializer is not limited to external types: - A target that itself conforms to `Serializer` with `Target == Self` selects that implementation implicitly everywhere. @@ -34,7 +34,7 @@ The same selection rules apply to roots, generated fields, optionals, arrays, sets, and dictionaries. Register a separate serializer and select it explicitly where it is used. -## When to Use a Manual Serializer +## When to Use a Custom Serializer - The target has private or immutable state. - The target must enforce construction invariants. @@ -284,9 +284,9 @@ let data = try fory.serialize( ) ``` -## Manual Serializer Rules +## Custom Serializer Rules -A manual serializer must return `.ext` from `staticTypeId`. The +A custom serializer must return `.ext` from `staticTypeId`. The `.structType`, `.enumType`, and `.typedUnion` values are reserved for `@ForyStruct`, `@ForyEnum`, and `@ForyUnion`. @@ -302,7 +302,7 @@ or missing field. Reject invalid input with an appropriate `ForyError`. -## Manual Class Serializers +## Custom Class Serializers For a cyclic class, override the complete-value `read` operation and use Fory's reference APIs so repeated references resolve to the same object. diff --git a/docs/guide/swift/external-types.md b/docs/guide/swift/external-types.md index c1e8b80863..7ce1e10202 100644 --- a/docs/guide/swift/external-types.md +++ b/docs/guide/swift/external-types.md @@ -24,7 +24,7 @@ another Swift module without modifying that type. Use an external structural serializer when the target exposes a schema that Fory can access and construct directly. Use a -[manual serializer](manual-serializers.md) when the target needs a customized +[custom serializer](custom-serializers.md) when the target needs a custom encoding or has private construction invariants. An external structural serializer is a separate declaration. Register it, then @@ -33,7 +33,7 @@ select it explicitly at roots, fields, and carrier children. For one application-owned global implementation, Swift also permits an external type to conform retroactively to `Serializer` with `Target == Self`. That form uses ordinary implicit selection everywhere and has process-global -conformance risks. See [Manual Serializers](manual-serializers.md). +conformance risks. See [Custom Serializers](custom-serializers.md). ## External Structs @@ -88,7 +88,7 @@ Swift budgets only fields listed in this declaration. Add `@ForyField(ignore: true)` fields for substantial omitted storage; they count toward the graph budget but are not serialized. -Use a manual serializer if the class is immutable, requires constructor +Use a custom serializer if the class is immutable, requires constructor arguments, or cannot be safely observed before all fields are assigned. ## External Enums @@ -104,7 +104,7 @@ enum StatusSerializer { ``` An enum from another module must be exhaustively switchable. A resilient -non-frozen public enum requires a manual serializer. +non-frozen public enum requires a custom serializer. ## External Unions @@ -127,7 +127,7 @@ enum CommandSerializer { The target must expose matching cases and a lossless `unknown(UnknownCase)` case. A dependency-free third-party module can declare a generic unknown payload, such as `Command<UnknownPayload>`, and the serializer -can target its `Command<UnknownCase>` specialization. Use a manual serializer +can target its `Command<UnknownCase>` specialization. Use a custom serializer when a third-party union has a different unknown-case representation or cannot preserve unknown payloads. @@ -266,7 +266,7 @@ let decoded = try fory.deserialize( ``` Register each concrete target through its ordinary, external structural, or -manual serializer. +custom serializer. For a root carrier containing protocol values, compose `DynamicSerializer` explicitly: diff --git a/docs/guide/swift/index.md b/docs/guide/swift/index.md index 721864fc64..6caa1a5798 100644 --- a/docs/guide/swift/index.md +++ b/docs/guide/swift/index.md @@ -27,7 +27,7 @@ Apache Fory Swift provides high-performance object graph serialization with stro - `@ForyStruct`, `@ForyEnum`, and `@ForyUnion` macros for zero-boilerplate model serialization - Xlang protocol compatibility with Java, Rust, Go, Python, and more - Compatible mode for schema evolution across versions -- External structural, manual, and recursively composed carrier serializers +- External structural, custom, and recursively composed carrier serializers - Built-in support for dynamic values and arbitrary application protocol existentials - Reference tracking for shared/circular graphs, including weak references on classes @@ -57,7 +57,7 @@ targets: [ - [Schema Metadata](schema-metadata.md) - [Type Registration](type-registration.md) - [External-Type Serialization](external-types.md) -- [Manual Serializers](manual-serializers.md) +- [Custom Serializers](custom-serializers.md) - [Shared and Circular References](references.md) - [Polymorphism and Dynamic Types](polymorphism.md) - [Schema Evolution](schema-evolution.md) diff --git a/docs/guide/swift/troubleshooting.md b/docs/guide/swift/troubleshooting.md index 990b52cb6c..45a3f907a7 100644 --- a/docs/guide/swift/troubleshooting.md +++ b/docs/guide/swift/troubleshooting.md @@ -92,7 +92,7 @@ An external struct needs readable matching properties and an accessible matching initializer. An external class needs an accessible zero-argument initializer and writable matching properties. -Use a [manual serializer](manual-serializers.md) when the target does not expose +Use a [custom serializer](custom-serializers.md) when the target does not expose that construction surface. ### Union case has multiple associated values diff --git a/docs/guide/swift/type-registration.md b/docs/guide/swift/type-registration.md index 2246b38e14..dc85320f28 100644 --- a/docs/guide/swift/type-registration.md +++ b/docs/guide/swift/type-registration.md @@ -98,6 +98,6 @@ Complete all registrations before the first root operation. ## Dynamic Types and Registration When serializing `Any`, `AnyObject`, or application protocol values, register -each concrete target through its ordinary, external structural, or manual +each concrete target through its ordinary, external structural, or custom serializer. `Any` and `AnyObject` use direct root APIs; application protocols select `DynamicSerializer<T>` explicitly. diff --git a/docs/guide/swift/xlang-serialization.md b/docs/guide/swift/xlang-serialization.md index f2e20a6dd1..c0bf3a4d3a 100644 --- a/docs/guide/swift/xlang-serialization.md +++ b/docs/guide/swift/xlang-serialization.md @@ -54,7 +54,7 @@ try fory.register(Order.self, name: "com.example.Order") - Keep compatible mode enabled when independently evolving schemas. Swift enables it by default. - Register all user-defined concrete targets used by dynamic fields and application protocol values -- Use an external structural serializer, a separate manual serializer, or one +- Use an external structural serializer, a separate custom serializer, or one intentional retroactive self-target conformance for a type owned by another module --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
