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 fd2a35a0ac8e2516aafe182d27db0bb54dc4d5e6 Author: chaokunyang <[email protected]> AuthorDate: Tue Apr 28 17:10:38 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/rust/basic-serialization.md | 10 +-- docs/guide/rust/cross-language.md | 4 +- docs/guide/rust/custom-serializers.md | 6 +- docs/guide/rust/field-configuration.md | 97 ++++++++++++++-------------- docs/guide/rust/index.md | 10 +-- docs/guide/rust/polymorphism.md | 10 +-- docs/guide/rust/references.md | 8 +-- docs/guide/rust/row-format.md | 4 +- docs/guide/rust/schema-evolution.md | 20 +++--- docs/guide/rust/troubleshooting.md | 4 +- docs/guide/rust/type-registration.md | 4 +- docs/guide/xlang/field-nullability.md | 4 +- docs/guide/xlang/field-reference-tracking.md | 4 +- docs/guide/xlang/getting-started.md | 4 +- docs/guide/xlang/serialization.md | 6 +- 15 files changed, 97 insertions(+), 98 deletions(-) diff --git a/docs/guide/rust/basic-serialization.md b/docs/guide/rust/basic-serialization.md index 9ac5e5d5a..6298ed426 100644 --- a/docs/guide/rust/basic-serialization.md +++ b/docs/guide/rust/basic-serialization.md @@ -23,7 +23,7 @@ This page covers basic object graph serialization and supported types. ## Object Graph Serialization -Apache Fory™ provides automatic serialization of complex object graphs, preserving the structure and relationships between objects. The `#[derive(ForyObject)]` macro generates efficient serialization code at compile time, eliminating runtime overhead. +Apache Fory™ provides automatic serialization of complex object graphs, preserving the structure and relationships between objects. The `#[derive(ForyStruct)]` macro generates efficient serialization code at compile time, eliminating runtime overhead. **Key capabilities:** @@ -35,10 +35,10 @@ Apache Fory™ provides automatic serialization of complex object graphs, preser ```rust use fory::{Fory, Error}; -use fory::ForyObject; +use fory::ForyStruct; use std::collections::HashMap; -#[derive(ForyObject, Debug, PartialEq)] +#[derive(ForyStruct, Debug, PartialEq)] struct Person { name: String, age: i32, @@ -47,7 +47,7 @@ struct Person { metadata: HashMap<String, String>, } -#[derive(ForyObject, Debug, PartialEq)] +#[derive(ForyStruct, Debug, PartialEq)] struct Address { street: String, city: String, @@ -128,7 +128,7 @@ assert_eq!(person, decoded); | Macro | Description | | ----------------------- | -------------------------- | -| `#[derive(ForyObject)]` | Object graph serialization | +| `#[derive(ForyStruct)]` | Object graph serialization | | `#[derive(ForyRow)]` | Row-based serialization | ## Serialization APIs diff --git a/docs/guide/rust/cross-language.md b/docs/guide/rust/cross-language.md index 245f17542..3c80e2c9e 100644 --- a/docs/guide/rust/cross-language.md +++ b/docs/guide/rust/cross-language.md @@ -66,9 +66,9 @@ fory.register_by_namespace::<User>("com.example", "User"); ```rust use fory::Fory; -use fory::ForyObject; +use fory::ForyStruct; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Person { name: String, age: i32, diff --git a/docs/guide/rust/custom-serializers.md b/docs/guide/rust/custom-serializers.md index 87c552367..508e37e57 100644 --- a/docs/guide/rust/custom-serializers.md +++ b/docs/guide/rust/custom-serializers.md @@ -19,7 +19,7 @@ license: | limitations under the License. --- -For types that don't support `#[derive(ForyObject)]`, implement the `Serializer` trait manually. +For types that don't support `#[derive(ForyStruct)]`, implement the `Serializer` trait manually. ## When to Use Custom Serializers @@ -74,7 +74,7 @@ impl ForyDefault for CustomType { > **Note**: When implementing `ForyDefault` manually, ensure your type also > implements `Default` if you use `Self::default()`. > Alternatively, you can construct a default instance directly in > `fory_default()`. > -> **Tip**: If your type supports `#[derive(ForyObject)]`, you can use `#[fory(generate_default)]` to automatically generate both `ForyDefault` and `Default` implementations. +> **Tip**: If your type supports `#[derive(ForyStruct)]`, you can use `#[fory(generate_default)]` to automatically generate both `ForyDefault` and `Default` implementations. ## Registering Custom Serializers @@ -149,5 +149,5 @@ let string = context.reader.read_utf8_string(len); ## Related Topics - [Type Registration](type-registration.md) - Registering serializers -- [Basic Serialization](basic-serialization.md) - Using ForyObject derive +- [Basic Serialization](basic-serialization.md) - Using ForyStruct derive - [Schema Evolution](schema-evolution.md) - Compatible mode diff --git a/docs/guide/rust/field-configuration.md b/docs/guide/rust/field-configuration.md index 0f9e1be2e..ac2a29762 100644 --- a/docs/guide/rust/field-configuration.md +++ b/docs/guide/rust/field-configuration.md @@ -36,9 +36,9 @@ Apache Fory™ provides the `#[fory(...)]` attribute macro to specify optional f The `#[fory(...)]` attribute is placed on individual struct fields: ```rust -use fory::ForyObject; +use fory::ForyStruct; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Person { #[fory(id = 0)] name: String, @@ -60,7 +60,7 @@ Multiple options are separated by commas. Assigns a numeric ID to a field to minimize struct field meta size overhead: ```rust -#[derive(ForyObject)] +#[derive(ForyStruct)] struct User { #[fory(id = 0)] id: i64, @@ -91,7 +91,7 @@ struct User { Excludes a field from serialization: ```rust -#[derive(ForyObject)] +#[derive(ForyStruct)] struct User { #[fory(id = 0)] id: i64, @@ -113,7 +113,7 @@ Controls whether null flags are written for fields: ```rust use fory::{Fory, RcWeak}; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Record { // RcWeak is nullable by default, override to non-nullable #[fory(id = 0, nullable = false)] @@ -143,7 +143,7 @@ Controls per-field reference tracking for shared ownership types: use std::rc::Rc; use std::sync::Arc; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Container { // Enable reference tracking (default for Rc/Arc) #[fory(id = 0, ref = true)] @@ -174,18 +174,18 @@ struct Container { Controls how integer fields are encoded: ```rust -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Metrics { // Variable-length encoding (smaller for small values) - #[fory(id = 0, encoding = "varint")] + #[fory(id = 0, encoding = varint)] count: i64, // Fixed-length encoding (consistent size) - #[fory(id = 1, encoding = "fixed")] + #[fory(id = 1, encoding = fixed)] timestamp: i64, // Tagged encoding (includes type tag, u64 only) - #[fory(id = 2, encoding = "tagged")] + #[fory(id = 2, encoding = tagged)] value: u64, } ``` @@ -203,28 +203,26 @@ struct Metrics { - `fixed`: Best for values that use full range (e.g., timestamps, hashes) - `tagged`: When type information needs to be preserved (u64 only) -### Compress (`compress`) +### Nested Collection Configuration -A convenience shorthand for controlling integer encoding: +Use `list(element(...))` and `map(key(...), value(...))` when an override belongs +to a nested element instead of the outer field: ```rust -#[derive(ForyObject)] +use std::collections::HashMap; + +#[derive(ForyStruct)] struct Data { - // compress = true -> varint encoding (default) - #[fory(id = 0, compress)] - small_value: i32, + #[fory(list(element(encoding = fixed)))] + fixed_values: Vec<i32>, - // compress = false -> fixed encoding - #[fory(id = 1, compress = false)] - fixed_value: u32, + #[fory(map(key(encoding = fixed), value(nullable = true, encoding = tagged)))] + values_by_id: HashMap<Option<i32>, Option<u64>>, } ``` -**Notes**: - -- `compress` or `compress = true` is equivalent to `encoding = "varint"` -- `compress = false` is equivalent to `encoding = "fixed"` -- If both `compress` and `encoding` are specified, they must not conflict +`compress` has been removed. Use `encoding = varint` or `encoding = fixed` +directly. ## Type Classification @@ -245,10 +243,10 @@ Fory classifies field types to determine default behavior: ## Complete Example ```rust -use fory::ForyObject; +use fory::ForyStruct; use std::rc::Rc; -#[derive(ForyObject, Default)] +#[derive(ForyStruct, Default)] struct Document { // Required fields with tag IDs #[fory(id = 0)] @@ -270,11 +268,11 @@ struct Document { related: Option<Rc<Document>>, // Counter with varint encoding (small values) - #[fory(id = 5, encoding = "varint")] + #[fory(id = 5, encoding = varint)] view_count: u64, // Timestamp with fixed encoding (full range values) - #[fory(id = 6, encoding = "fixed")] + #[fory(id = 6, encoding = fixed)] created_at: i64, // Skip sensitive field @@ -307,7 +305,7 @@ Invalid configurations are caught at compile time: ```rust // Error: duplicate field IDs -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Bad { #[fory(id = 0)] field1: String, @@ -317,16 +315,16 @@ struct Bad { } // Error: invalid id value -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Bad2 { #[fory(id = -2)] // Compile error: id must be >= -1 field: String, } -// Error: conflicting encoding attributes -#[derive(ForyObject)] +// Error: removed shorthand +#[derive(ForyStruct)] struct Bad3 { - #[fory(compress = true, encoding = "fixed")] // Compile error: conflict + #[fory(compress = false)] // Compile error: use encoding = fixed field: i32, } ``` @@ -336,18 +334,18 @@ struct Bad3 { When serializing data to be read by other languages (Java, C++, Go, Python), use field configuration to match encoding expectations: ```rust -#[derive(ForyObject)] +#[derive(ForyStruct)] struct CrossLangData { // Matches Java Integer with varint - #[fory(id = 0, encoding = "varint")] + #[fory(id = 0, encoding = varint)] int_var: i32, // Matches Java Integer with fixed - #[fory(id = 1, encoding = "fixed")] + #[fory(id = 1, encoding = fixed)] int_fixed: i32, // Matches Java Long with tagged encoding - #[fory(id = 2, encoding = "tagged")] + #[fory(id = 2, encoding = tagged)] long_tagged: u64, // Nullable pointer matches Java nullable reference @@ -362,7 +360,7 @@ Compatible mode supports schema evolution. It is recommended to configure field ```rust // Version 1 -#[derive(ForyObject)] +#[derive(ForyStruct)] struct DataV1 { #[fory(id = 0)] id: i64, @@ -372,7 +370,7 @@ struct DataV1 { } // Version 2: Added new field -#[derive(ForyObject)] +#[derive(ForyStruct)] struct DataV2 { #[fory(id = 0)] id: i64, @@ -390,7 +388,7 @@ Data serialized with V1 can be deserialized with V2 (new field will be `None`). Alternatively, field IDs can be omitted (field names will be used in metadata with larger overhead): ```rust -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Data { id: i64, name: String, @@ -411,7 +409,7 @@ You **need to configure fields** when: ```rust // Xlang mode: explicit configuration required -#[derive(ForyObject)] +#[derive(ForyStruct)] struct User { #[fory(id = 0)] name: String, // Non-nullable by default @@ -444,14 +442,15 @@ struct User { ## Options Reference -| Option | Syntax | Description | Valid For | -| ---------- | ---------------------------------- | ------------------------------------ | -------------------------- | -| `id` | `id = N` | Field tag ID to reduce metadata size | All fields | -| `skip` | `skip` | Exclude field from serialization | All fields | -| `nullable` | `nullable` or `nullable = bool` | Control null flag writing | All fields | -| `ref` | `ref` or `ref = bool` | Control reference tracking | `Rc`, `Arc`, weak types | -| `encoding` | `encoding = "varint/fixed/tagged"` | Integer encoding method | `i32`, `u32`, `i64`, `u64` | -| `compress` | `compress` or `compress = bool` | Shorthand for varint/fixed | `i32`, `u32` | +| Option | Syntax | Description | Valid For | +| ---------- | -------------------------------- | ------------------------------------ | -------------------------- | +| `id` | `id = N` | Field tag ID to reduce metadata size | All fields | +| `skip` | `skip` | Exclude field from serialization | All fields | +| `nullable` | `nullable` or `nullable = bool` | Control null flag writing | All fields | +| `ref` | `ref` or `ref = bool` | Control reference tracking | `Rc`, `Arc`, weak types | +| `encoding` | `encoding = varint/fixed/tagged` | Integer encoding method | `i32`, `u32`, `i64`, `u64` | +| `list` | `list(element(...))` | Element field configuration | `Vec<T>` | +| `map` | `map(key(...), value(...))` | Key/value field configuration | `HashMap<K, V>` | ## Related Topics diff --git a/docs/guide/rust/index.md b/docs/guide/rust/index.md index d52a45d52..3b32eac6d 100644 --- a/docs/guide/rust/index.md +++ b/docs/guide/rust/index.md @@ -54,9 +54,9 @@ fory = "0.13" ```rust use fory::{Fory, Error, Reader}; -use fory::ForyObject; +use fory::ForyStruct; -#[derive(ForyObject, Debug, PartialEq)] +#[derive(ForyStruct, Debug, PartialEq)] struct User { name: String, age: i32, @@ -96,11 +96,11 @@ Apache Fory™ Rust is fully thread-safe: `Fory` implements both `Send` and `Syn ```rust use fory::{Fory, Error}; -use fory::ForyObject; +use fory::ForyStruct; use std::sync::Arc; use std::thread; -#[derive(ForyObject, Clone, Copy, Debug, PartialEq)] +#[derive(ForyStruct, Clone, Copy, Debug, PartialEq)] struct Item { value: i32, } @@ -152,7 +152,7 @@ fory-core/ # Core serialization engine fory-derive/ # Procedural macros ├── src/ -│ ├── object/ # ForyObject macro +│ ├── object/ # ForyStruct macro │ └── fory_row.rs # ForyRow macro ``` diff --git a/docs/guide/rust/polymorphism.md b/docs/guide/rust/polymorphism.md index 2afff965d..f3b7bbbb1 100644 --- a/docs/guide/rust/polymorphism.md +++ b/docs/guide/rust/polymorphism.md @@ -33,14 +33,14 @@ Apache Fory™ supports polymorphic serialization through trait objects, enablin ```rust use fory::{Fory, register_trait_type}; use fory::Serializer; -use fory::ForyObject; +use fory::ForyStruct; trait Animal: Serializer { fn speak(&self) -> String; fn name(&self) -> &str; } -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Dog { name: String, breed: String } impl Animal for Dog { @@ -48,7 +48,7 @@ impl Animal for Dog { fn name(&self) -> &str { &self.name } } -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Cat { name: String, color: String } impl Animal for Cat { @@ -59,7 +59,7 @@ impl Animal for Cat { // Register trait implementations register_trait_type!(Animal, Dog, Cat); -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Zoo { star_animal: Box<dyn Animal>, } @@ -146,7 +146,7 @@ use std::sync::Arc; use std::rc::Rc; use std::collections::HashMap; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct AnimalShelter { animals_rc: Vec<Rc<dyn Animal>>, animals_arc: Vec<Arc<dyn Animal>>, diff --git a/docs/guide/rust/references.md b/docs/guide/rust/references.md index e2dcb49da..f18d11cd1 100644 --- a/docs/guide/rust/references.md +++ b/docs/guide/rust/references.md @@ -90,12 +90,12 @@ To serialize circular references like parent-child relationships or doubly-linke ```rust use fory::{Fory, Error}; -use fory::ForyObject; +use fory::ForyStruct; use fory::RcWeak; use std::rc::Rc; use std::cell::RefCell; -#[derive(ForyObject, Debug)] +#[derive(ForyStruct, Debug)] struct Node { value: i32, parent: RcWeak<RefCell<Node>>, @@ -143,11 +143,11 @@ for child in &decoded.borrow().children { ```rust use fory::{Fory, Error}; -use fory::ForyObject; +use fory::ForyStruct; use fory::ArcWeak; use std::sync::{Arc, Mutex}; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Node { val: i32, parent: ArcWeak<Mutex<Node>>, diff --git a/docs/guide/rust/row-format.md b/docs/guide/rust/row-format.md index 1728d4551..c0728f746 100644 --- a/docs/guide/rust/row-format.md +++ b/docs/guide/rust/row-format.md @@ -110,9 +110,9 @@ assert_eq!(prefs.values().get(0), "en"); | Memory usage | Full object graph in memory | Only accessed fields in memory | | Suitable for | Small objects, full access | Large objects, selective access | -## ForyRow vs ForyObject +## ForyRow vs ForyStruct -| Feature | `#[derive(ForyRow)]` | `#[derive(ForyObject)]` | +| Feature | `#[derive(ForyRow)]` | `#[derive(ForyStruct)]` | | --------------- | --------------------- | -------------------------- | | Deserialization | Zero-copy, lazy | Full object reconstruction | | Field access | Direct from binary | Normal struct access | diff --git a/docs/guide/rust/schema-evolution.md b/docs/guide/rust/schema-evolution.md index 6b51ba1ac..e6dbfced1 100644 --- a/docs/guide/rust/schema-evolution.md +++ b/docs/guide/rust/schema-evolution.md @@ -27,17 +27,17 @@ Enable schema evolution with `compatible(true)`: ```rust use fory::Fory; -use fory::ForyObject; +use fory::ForyStruct; use std::collections::HashMap; -#[derive(ForyObject, Debug)] +#[derive(ForyStruct, Debug)] struct PersonV1 { name: String, age: i32, address: String, } -#[derive(ForyObject, Debug)] +#[derive(ForyStruct, Debug)] struct PersonV2 { name: String, age: i32, @@ -74,9 +74,9 @@ assert_eq!(person_v2.phone, None); If a struct schema is stable and will not change, you can disable evolution for that struct to avoid compatible metadata overhead. Use `#[fory(evolving = false)]`: ```rust -use fory::ForyObject; +use fory::ForyStruct; -#[derive(ForyObject)] +#[derive(ForyStruct)] #[fory(evolving = false)] struct StableMessage { id: i32, @@ -108,9 +108,9 @@ Apache Fory™ supports three types of enum variants with full schema evolution - **Named**: Struct-like variants (`Event::Click { x: i32, y: i32 }`) ```rust -use fory::{Fory, ForyObject}; +use fory::{Fory, ForyStruct}; -#[derive(Default, ForyObject, Debug, PartialEq)] +#[derive(Default, ForyStruct, Debug, PartialEq)] enum Value { #[default] Null, @@ -136,17 +136,17 @@ Compatible mode enables robust schema evolution with variant type encoding (2 bi - `0b0` = Unit, `0b1` = Unnamed, `0b10` = Named ```rust -use fory::{Fory, ForyObject}; +use fory::{Fory, ForyStruct}; // Old version -#[derive(ForyObject)] +#[derive(ForyStruct)] enum OldEvent { Click { x: i32, y: i32 }, Scroll { delta: f64 }, } // New version - added field and variant -#[derive(Default, ForyObject)] +#[derive(Default, ForyStruct)] enum NewEvent { #[default] Unknown, diff --git a/docs/guide/rust/troubleshooting.md b/docs/guide/rust/troubleshooting.md index 6d99c551b..90afa1369 100644 --- a/docs/guide/rust/troubleshooting.md +++ b/docs/guide/rust/troubleshooting.md @@ -68,10 +68,10 @@ Reset the variable afterwards to avoid aborting user-facing code paths. ### Struct Field Tracing -Add the `#[fory(debug)]` attribute alongside `#[derive(ForyObject)]` to emit hook invocations: +Add the `#[fory(debug)]` attribute alongside `#[derive(ForyStruct)]` to emit hook invocations: ```rust -#[derive(ForyObject)] +#[derive(ForyStruct)] #[fory(debug)] struct MyStruct { field1: i32, diff --git a/docs/guide/rust/type-registration.md b/docs/guide/rust/type-registration.md index d44d0094a..d2849ac88 100644 --- a/docs/guide/rust/type-registration.md +++ b/docs/guide/rust/type-registration.md @@ -27,9 +27,9 @@ Register types with a numeric ID for fast, compact serialization: ```rust use fory::Fory; -use fory::ForyObject; +use fory::ForyStruct; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct User { name: String, age: i32, diff --git a/docs/guide/xlang/field-nullability.md b/docs/guide/xlang/field-nullability.md index 5bd3494e0..516039f3f 100644 --- a/docs/guide/xlang/field-nullability.md +++ b/docs/guide/xlang/field-nullability.md @@ -137,9 +137,9 @@ fory.register_type(Person, typename="example.Person") ### Rust ```rust -use fory::{Fory, ForyObject}; +use fory::{Fory, ForyStruct}; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Person { // Non-nullable by default name: String, diff --git a/docs/guide/xlang/field-reference-tracking.md b/docs/guide/xlang/field-reference-tracking.md index d7729c240..6b5b28698 100644 --- a/docs/guide/xlang/field-reference-tracking.md +++ b/docs/guide/xlang/field-reference-tracking.md @@ -163,10 +163,10 @@ To disable reference tracking for C++ entirely, set #### Rust: Field Attributes ```rust -use fory::ForyObject; +use fory::ForyStruct; use std::rc::Rc; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Document { title: String, diff --git a/docs/guide/xlang/getting-started.md b/docs/guide/xlang/getting-started.md index 9cc41d5fe..9ebb01f6c 100644 --- a/docs/guide/xlang/getting-started.md +++ b/docs/guide/xlang/getting-started.md @@ -165,9 +165,9 @@ fory.RegisterNamedStruct(Person{}, "example.Person") **Rust:** ```rust -use fory::{Fory, ForyObject}; +use fory::{Fory, ForyStruct}; -#[derive(ForyObject)] +#[derive(ForyStruct)] struct Person { name: String, age: i32, diff --git a/docs/guide/xlang/serialization.md b/docs/guide/xlang/serialization.md index 17fbd5c5c..1257307db 100644 --- a/docs/guide/xlang/serialization.md +++ b/docs/guide/xlang/serialization.md @@ -359,17 +359,17 @@ console.log(result); ```rust use chrono::{NaiveDate, NaiveDateTime}; -use fory::{Fory, ForyObject}; +use fory::{Fory, ForyStruct}; use std::collections::HashMap; #[test] fn complex_struct() { - #[derive(ForyObject, Debug, PartialEq)] + #[derive(ForyStruct, Debug, PartialEq)] struct Animal { category: String, } - #[derive(ForyObject, Debug, PartialEq)] + #[derive(ForyStruct, Debug, PartialEq)] struct Person { c1: Vec<u8>, // binary c2: Vec<i16>, // primitive array --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
