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.git
The following commit(s) were added to refs/heads/main by this push:
new 3f829a9dd docs(rust): add rust document (#2582)
3f829a9dd is described below
commit 3f829a9ddd5411f010cccc3b5d69171a2517957f
Author: Shawn Yang <[email protected]>
AuthorDate: Fri Sep 5 15:05:54 2025 +0800
docs(rust): add rust document (#2582)
<!--
**Thanks for contributing to Fory.**
**If this is your first time opening a PR on fory, you can refer to
[CONTRIBUTING.md](https://github.com/apache/fory/blob/main/CONTRIBUTING.md).**
Contribution Checklist
- The **Apache Fory** community has requirements on the naming of pr
titles. You can also find instructions in
[CONTRIBUTING.md](https://github.com/apache/fory/blob/main/CONTRIBUTING.md).
- Fory has a strong focus on performance. If the PR you submit will have
an impact on performance, please benchmark it first and provide the
benchmark result here.
-->
## Why?
<!-- Describe the purpose of this PR. -->
## What does this PR do?
<!-- Describe the details of this PR. -->
## Related issues
Closes #2558
## Does this PR introduce any user-facing change?
<!--
If any user-facing interface changes, please [open an
issue](https://github.com/apache/fory/issues/new/choose) describing the
need to do so and update the document if necessary.
Delete section if not applicable.
-->
- [ ] Does this PR introduce any public API change?
- [ ] Does this PR introduce any binary protocol compatibility change?
## Benchmark
<!--
When the PR has an impact on performance (if you don't know whether the
PR will have an impact on performance, you can submit the PR first, and
if it will have impact on performance, the code reviewer will explain
it), be sure to attach a benchmark data here.
Delete section if not applicable.
-->
---
rust/README.md | 241 ++++++++++++++++++++++++++++++++++++++++++--
rust/fory-core/src/lib.rs | 66 ++++++++++++
rust/fory-derive/src/lib.rs | 193 +++++++++++++++++++++++++++++++++++
rust/fory/src/lib.rs | 241 ++++++++++++++++++++++++++++++++++++++++++++
4 files changed, 735 insertions(+), 6 deletions(-)
diff --git a/rust/README.md b/rust/README.md
index de0c5c316..b69bf6cea 100644
--- a/rust/README.md
+++ b/rust/README.md
@@ -1,11 +1,240 @@
# Apache Foryβ’ Rust
+[](https://crates.io/crates/fory)
+[](https://docs.rs/fory)
+[](LICENSE)
+
Fory is a blazingly fast multi-language serialization framework powered by
-just-in-time compilation and zero-copy.
+codegen and zero-copy techniques. It provides high-performance
+serialization and deserialization for Rust applications with cross-language
+compatibility.
+
+## π Key Features
+
+- **High Performance**: Optimized for speed with zero-copy deserialization
+- **Cross-Language**: Designed for multi-language environments and
microservices
+- **Two Serialization Modes**: Object serialization with highly-optimized
protocol and row-based lazy on-demand serialization
+- **Type Safety**: Compile-time type checking with derive macros
+- **Schema Evolution**: Support for compatible mode with field
additions/deletions
+- **Zero Dependencies**: Minimal runtime dependencies for maximum performance
+
+## π¦ Crates
+
+This repository contains three main crates:
+
+- **[`fory`](fory/)**: Main crate with high-level API and derive macros
+- **[`fory-core`](fory-core/)**: Core serialization engine and low-level APIs
+- **[`fory-derive`](fory-derive/)**: Procedural macros for code generation
+
+## πββοΈ Quick Start
+
+Add Fory to your `Cargo.toml`:
+
+```toml
+[dependencies]
+fory = "0.1"
+fory-derive = "0.1"
+chrono = "0.4"
+```
+
+### Object Serialization
+
+For complex data structures with full object graph serialization:
+
+```rust
+use fory::{Fory, Error};
+use fory_derive::Fory;
+use std::collections::HashMap;
+
+#[derive(Fory, Debug, PartialEq, Default)]
+struct Person {
+ name: String,
+ age: i32,
+ address: Address,
+ hobbies: Vec<String>,
+ metadata: HashMap<String, String>,
+}
+
+#[derive(Fory, Debug, PartialEq, Default)]
+struct Address {
+ street: String,
+ city: String,
+ country: String,
+}
+
+// Create a Fory instance and register types
+let mut fory = Fory::default();
+fory.register::<Address>(100);
+fory.register::<Person>(200);
+
+let person = Person {
+ name: "John Doe".to_string(),
+ age: 30,
+ address: Address {
+ street: "123 Main St".to_string(),
+ city: "New York".to_string(),
+ country: "USA".to_string(),
+ },
+ hobbies: vec!["reading".to_string(), "coding".to_string()],
+ metadata: HashMap::from([
+ ("department".to_string(), "engineering".to_string()),
+ ("level".to_string(), "senior".to_string()),
+ ]),
+};
+
+// Serialize the object
+let serialized = fory.serialize(&person);
+
+// Deserialize back to the original type
+let deserialized: Person = fory.deserialize(&serialized)?;
+
+assert_eq!(person, deserialized);
+```
+
+### Row-Based Serialization
+
+For high-performance, zero-copy scenarios:
+
+```rust
+use fory::{to_row, from_row};
+use fory_derive::ForyRow;
+use std::collections::BTreeMap;
+
+#[derive(ForyRow)]
+struct UserProfile {
+ id: i64,
+ username: String,
+ email: String,
+ scores: Vec<i32>,
+ preferences: BTreeMap<String, String>,
+ is_active: bool,
+}
+
+let profile = UserProfile {
+ id: 12345,
+ username: "alice".to_string(),
+ email: "[email protected]".to_string(),
+ scores: vec![95, 87, 92, 88],
+ preferences: BTreeMap::from([
+ ("theme".to_string(), "dark".to_string()),
+ ("language".to_string(), "en".to_string()),
+ ]),
+ is_active: true,
+};
+
+// Serialize to row format
+let row_data = to_row(&profile);
+
+// Deserialize with zero-copy access
+let row = from_row::<UserProfile>(&row_data);
+
+// Access fields directly from the row data
+assert_eq!(row.id(), 12345);
+assert_eq!(row.username(), "alice");
+assert_eq!(row.email(), "[email protected]");
+assert_eq!(row.is_active(), true);
+
+// Access collections efficiently
+let scores = row.scores();
+assert_eq!(scores.size(), 4);
+assert_eq!(scores.get(0), 95);
+assert_eq!(scores.get(1), 87);
+
+let prefs = row.preferences();
+assert_eq!(prefs.keys().size(), 2);
+assert_eq!(prefs.keys().get(0), "language");
+assert_eq!(prefs.values().get(0), "en");
+```
+
+## π Documentation
+
+- **[API Documentation](https://docs.rs/fory)** - Complete API reference
+- **[Performance Guide](docs/performance.md)** - Optimization tips and
benchmarks
+
+## π― Use Cases
+
+### Object Serialization
+
+- **Complex data structures** with nested objects and references
+- **Cross-language communication** in microservices architectures
+- **General-purpose serialization** with full type safety
+- **Schema evolution** with compatible mode
+
+### Row-Based Serialization
+
+- **High-throughput data processing** with zero-copy access
+- **Analytics workloads** requiring fast field access
+- **Memory-constrained environments** with minimal allocations
+- **Real-time data streaming** applications
+
+## π§ Supported Types
+
+### Primitive Types
+
+- `bool`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64`
+- `String`, `&str` (in row format)
+- `Vec<u8>` for binary data
+
+### Collections
+
+- `Vec<T>` for arrays/lists
+- `HashMap<K, V>` and `BTreeMap<K, V>` for maps
+- `Option<T>` for nullable values
+
+### Date and Time
+
+- `chrono::NaiveDate` for dates (requires chrono dependency)
+- `chrono::NaiveDateTime` for timestamps (requires chrono dependency)
+
+### Custom Types
+
+- Structs with `#[derive(Fory)]` or `#[derive(ForyRow)]`
+- Enums with `#[derive(Fory)]`
+
+## β‘ Performance
+
+Fory is designed for maximum performance:
+
+- **Zero-copy deserialization** in row mode
+- **Buffer pre-allocation** to minimize allocations
+- **Variable-length encoding** for compact representation
+- **Little-endian byte order** for cross-platform compatibility
+- **Optimized code generation** with derive macros
+
+## π Cross-Language Compatibility
+
+Fory is designed to work across multiple programming languages, making it
ideal for:
+
+- **Microservices architectures** with polyglot services
+- **Distributed systems** with heterogeneous components
+- **Data pipelines** spanning multiple language ecosystems
+- **API communication** between different technology stacks
+
+## π οΈ Development Status
+
+Fory Rust implementation roadmap:
+
+- [x] Static codegen based on rust macro
+- [x] Row format serialization
+- [x] Cross-language object graph serialization
+- [x] Static codegen based on fory-derive macro processor
+- [ ] Advanced schema evolution features
+- [ ] Performance optimizations and benchmarks
+
+## π License
+
+Licensed under the Apache License, Version 2.0. See [LICENSE](../LICENSE) for
details.
+
+## π€ Contributing
+
+We welcome contributions! Please see our [Contributing
Guide](../CONTRIBUTING.md) for details.
+
+## π Support
+
+- **Documentation**: [docs.rs/fory](https://docs.rs/fory)
+- **Issues**: [GitHub Issues](https://github.com/apache/fury/issues)
+- **Discussions**: [GitHub
Discussions](https://github.com/apache/fury/discussions)
-Fory Rust can be implemented by steps:
+---
-- [ ] Static codegen based on fory code generator
-- [ ] Static codegen based on rust macro
-- [ ] Cross-language object graph serialization
-- [ ] Row format
+**Apache Foryβ’** - Blazingly fast serialization.
diff --git a/rust/fory-core/src/lib.rs b/rust/fory-core/src/lib.rs
index b50d94a31..199022419 100644
--- a/rust/fory-core/src/lib.rs
+++ b/rust/fory-core/src/lib.rs
@@ -15,6 +15,72 @@
// specific language governing permissions and limitations
// under the License.
+//! # Fory Core
+//!
+//! This is the core implementation of the Fory serialization framework.
+//! It provides the fundamental building blocks for high-performance
serialization
+//! and deserialization in Rust.
+//!
+//! ## Architecture
+//!
+//! The core library is organized into several key modules:
+//!
+//! - **`fory`**: Main serialization engine and public API
+//! - **`buffer`**: Efficient binary buffer management with Reader/Writer
+//! - **`row`**: Row-based serialization for zero-copy operations
+//! - **`serializer`**: Type-specific serialization implementations
+//! - **`resolver`**: Type resolution and metadata management
+//! - **`meta`**: Metadata handling for schema evolution
+//! - **`types`**: Core type definitions and constants
+//! - **`error`**: Error handling and result types
+//! - **`util`**: Utility functions and helpers
+//!
+//! ## Key Concepts
+//!
+//! ### Serialization Modes
+//!
+//! Fory supports two serialization modes:
+//!
+//! - **SchemaConsistent**: Requires exact type matching between peers
+//! - **Compatible**: Allows schema evolution with field additions/deletions
+//!
+//! ### Type System
+//!
+//! The framework uses a comprehensive type system that supports:
+//! - Primitive types (bool, integers, floats, strings)
+//! - Collections (Vec, HashMap, BTreeMap)
+//! - Optional types (`Option<T>`)
+//! - Date/time types (chrono integration)
+//! - Custom structs and enums
+//!
+//! ### Performance Optimizations
+//!
+//! - **Zero-copy deserialization** in row mode
+//! - **Buffer pre-allocation** to minimize allocations
+//! - **Variable-length encoding** for compact representation
+//! - **Little-endian byte order** for cross-platform compatibility
+//!
+//! ## Usage
+//!
+//! This crate is typically used through the higher-level `fory` crate,
+//! which provides derive macros and a more convenient API. However,
+//! you can use the core types directly for advanced use cases.
+//!
+//! ```rust
+//! use fory_core::{fory::Fory, error::Error, types::Mode};
+//! use fory_core::row::{to_row, from_row};
+//!
+//! // Create a Fory instance
+//! let mut fory = Fory::default().mode(Mode::Compatible);
+//!
+//! // Register types for object serialization
+//! // fory.register::<MyStruct>(type_id);
+//!
+//! // Use row-based serialization for zero-copy operations
+//! // let row_data = to_row(&my_data);
+//! // let row = from_row::<MyStruct>(&row_data);
+//! ```
+
pub mod buffer;
pub mod error;
pub mod fory;
diff --git a/rust/fory-derive/src/lib.rs b/rust/fory-derive/src/lib.rs
index 9fcf2baa9..90ae17510 100644
--- a/rust/fory-derive/src/lib.rs
+++ b/rust/fory-derive/src/lib.rs
@@ -15,6 +15,156 @@
// specific language governing permissions and limitations
// under the License.
+//! # Fory Derive Macros
+//!
+//! This crate provides procedural macros for the Fory serialization framework.
+//! It generates serialization and deserialization code for Rust types.
+//!
+//! ## Available Macros
+//!
+//! ### `#[derive(Fory)]`
+//!
+//! Generates object serialization code for structs and enums. This macro
+//! implements the `Serializer` trait, enabling full object graph serialization
+//! with reference handling.
+//!
+//! **Supported Types:**
+//! - Structs with named fields
+//! - Structs with unnamed fields (tuple structs)
+//! - Unit structs
+//! - Enums with variants
+//!
+//! **Example:**
+//! ```rust
+//! use fory_derive::Fory;
+//! use std::collections::HashMap;
+//!
+//! #[derive(Fory, Debug, PartialEq, Default)]
+//! struct Person {
+//! name: String,
+//! age: i32,
+//! address: Address,
+//! hobbies: Vec<String>,
+//! metadata: HashMap<String, String>,
+//! }
+//!
+//! #[derive(Fory, Debug, PartialEq, Default)]
+//! struct Address {
+//! street: String,
+//! city: String,
+//! }
+//!
+//! #[derive(Fory, Debug, PartialEq)]
+//! enum Status {
+//! Active,
+//! Inactive,
+//! Suspended,
+//! }
+//! ```
+//!
+//! ### `#[derive(ForyRow)]`
+//!
+//! Generates row-based serialization code for structs. This macro implements
+//! the `Row` trait, enabling zero-copy deserialization for maximum
performance.
+//!
+//! **Supported Types:**
+//! - Structs with named fields only
+//! - All field types must implement the `Row` trait
+//!
+//! **Example:**
+//! ```rust
+//! use fory_derive::ForyRow;
+//! use std::collections::BTreeMap;
+//!
+//! #[derive(ForyRow)]
+//! struct UserProfile {
+//! id: i64,
+//! username: String,
+//! email: String,
+//! scores: Vec<i32>,
+//! preferences: BTreeMap<String, String>,
+//! is_active: bool,
+//! }
+//! ```
+//!
+//! ## Generated Code
+//!
+//! ### For `#[derive(Fory)]`
+//!
+//! The macro generates:
+//! - `Serializer` trait implementation
+//! - Serialization methods for writing data to buffers
+//! - Deserialization methods for reading data from buffers
+//! - Type ID management for cross-language compatibility
+//!
+//! ### For `#[derive(ForyRow)]`
+//!
+//! The macro generates:
+//! - `Row` trait implementation
+//! - A getter struct for zero-copy field access
+//! - Field accessor methods that return references to the underlying data
+//! - Efficient serialization without object allocation
+//!
+//! ## Field Types
+//!
+//! Both macros support a wide range of field types:
+//!
+//! **Primitive Types:**
+//! - `bool`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64`
+//! - `String`, `&str` (in row format)
+//! - `Vec<u8>` for binary data
+//!
+//! **Collections:**
+//! - `Vec<T>` where `T` implements the appropriate trait
+//! - `HashMap<K, V>` and `BTreeMap<K, V>` where keys and values implement the
trait
+//! - `Option<T>` for nullable values
+//!
+//! **Date/Time:**
+//! - `chrono::NaiveDate`
+//! - `chrono::NaiveDateTime`
+//!
+//! **Custom Types:**
+//! - Any type that implements `Serializer` (for `Fory`) or `Row` (for
`ForyRow`)
+//!
+//! ## Usage with Fory
+//!
+//! After deriving the macros, you can use the types with the Fory
serialization
+//! framework:
+//!
+//! ```rust
+//! use fory_core::{fory::Fory, error::Error};
+//! use fory_derive::Fory;
+//!
+//! #[derive(Fory, Debug, PartialEq, Default)]
+//! struct MyData {
+//! value: i32,
+//! text: String,
+//! }
+//!
+//! fn main() -> Result<(), Error> {
+//! let mut fory = Fory::default();
+//! fory.register::<MyData>(100);
+//!
+//! let data = MyData {
+//! value: 42,
+//! text: "Hello, Fory!".to_string(),
+//! };
+//!
+//! let serialized = fory.serialize(&data);
+//! let deserialized: MyData = fory.deserialize(&serialized)?;
+//!
+//! assert_eq!(data, deserialized);
+//! Ok(())
+//! }
+//! ```
+//!
+//! ## Performance Considerations
+//!
+//! - **`Fory`**: Best for complex object graphs with references and nested
structures
+//! - **`ForyRow`**: Best for high-throughput scenarios requiring zero-copy
access
+//! - Both macros generate optimized code with minimal runtime overhead
+//! - Field access in row format is extremely fast as it involves no
allocations
+
use fory_row::derive_row;
use proc_macro::TokenStream;
use syn::{parse_macro_input, DeriveInput};
@@ -23,12 +173,55 @@ mod fory_row;
mod object;
mod util;
+/// Derive macro for object serialization.
+///
+/// This macro generates code to implement the `Serializer` trait for the
+/// annotated type, enabling full object graph serialization with reference
+/// handling and cross-language compatibility.
+///
+/// # Example
+///
+/// ```rust
+/// use fory_derive::Fory;
+///
+/// #[derive(Fory, Debug, PartialEq, Default)]
+/// struct Person {
+/// name: String,
+/// age: i32,
+/// address: Address,
+/// }
+///
+/// #[derive(Fory, Debug, PartialEq, Default)]
+/// struct Address {
+/// street: String,
+/// city: String,
+/// }
+/// ```
#[proc_macro_derive(Fory)]
pub fn proc_macro_derive_fory_object(input: proc_macro::TokenStream) ->
TokenStream {
let input = parse_macro_input!(input as DeriveInput);
object::derive_serializer(&input)
}
+/// Derive macro for row-based serialization.
+///
+/// This macro generates code to implement the `Row` trait for the annotated
+/// type, enabling zero-copy deserialization for maximum performance in
+/// high-throughput scenarios.
+///
+/// # Example
+///
+/// ```rust
+/// use fory_derive::ForyRow;
+///
+/// #[derive(ForyRow)]
+/// struct UserProfile {
+/// id: i64,
+/// username: String,
+/// email: String,
+/// is_active: bool,
+/// }
+/// ```
#[proc_macro_derive(ForyRow)]
pub fn proc_macro_derive_fory_row(input: proc_macro::TokenStream) ->
TokenStream {
let input = parse_macro_input!(input as DeriveInput);
diff --git a/rust/fory/src/lib.rs b/rust/fory/src/lib.rs
index 23674bac5..c240c6783 100644
--- a/rust/fory/src/lib.rs
+++ b/rust/fory/src/lib.rs
@@ -15,4 +15,245 @@
// specific language governing permissions and limitations
// under the License.
+//! # Fory
+//!
+//! Fory is a blazingly fast multi-language serialization framework powered by
+//! just-in-time compilation and zero-copy techniques. It provides two main
+//! serialization approaches: object serialization for complex data structures
+//! and row-based serialization for high-performance scenarios.
+//!
+//! ## Key Features
+//!
+//! - **High Performance**: Optimized for speed with zero-copy deserialization
+//! - **Cross-Language**: Designed for multi-language environments
+//! - **Two Serialization Modes**: Object serialization and row-based
serialization
+//! - **Type Safety**: Compile-time type checking with derive macros
+//! - **Schema Evolution**: Support for compatible mode with field
additions/deletions
+//!
+//! ## Serialization Modes
+//!
+//! Fory provides two distinct serialization approaches:
+//!
+//! ### 1. Object Serialization
+//!
+//! Object serialization is designed for complex data structures and provides
+//! full object graph serialization with reference handling. This mode is
+//! ideal for general-purpose serialization needs.
+//!
+//! ```rust
+//! use fory::{Fory, Error};
+//! use fory_derive::Fory;
+//! use std::collections::HashMap;
+//! #[derive(Fory, Debug, PartialEq, Default)]
+//! struct Person {
+//! name: String,
+//! age: i32,
+//! address: Address,
+//! hobbies: Vec<String>,
+//! metadata: HashMap<String, String>,
+//! }
+//!
+//! #[derive(Fory, Debug, PartialEq, Default)]
+//! struct Address {
+//! street: String,
+//! city: String,
+//! country: String,
+//! }
+//!
+//! # fn main() -> Result<(), Error> {
+//! let person = Person {
+//! name: "John Doe".to_string(),
+//! age: 30,
+//! address: Address {
+//! street: "123 Main St".to_string(),
+//! city: "New York".to_string(),
+//! country: "USA".to_string(),
+//! },
+//! hobbies: vec!["reading".to_string(), "coding".to_string()],
+//! metadata: HashMap::from([
+//! ("department".to_string(), "engineering".to_string()),
+//! ("level".to_string(), "senior".to_string()),
+//! ]),
+//! };
+//!
+//! // Create a Fory instance and register types
+//! let mut fory = Fory::default();
+//! fory.register::<Address>(100);
+//! fory.register::<Person>(200);
+//!
+//! // Serialize the object
+//! let serialized = fory.serialize(&person);
+//!
+//! // Deserialize back to the original type
+//! let deserialized: Person = fory.deserialize(&serialized)?;
+//!
+//! assert_eq!(person, deserialized);
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! ### 2. Row-Based Serialization
+//!
+//! Row-based serialization provides zero-copy deserialization for maximum
+//! performance. This mode is ideal for high-throughput scenarios where you
+//! need to process large amounts of data efficiently.
+//!
+//! ```rust
+//! use fory::{to_row, from_row};
+//! use fory_derive::ForyRow;
+//! use std::collections::BTreeMap;
+//!
+//! #[derive(ForyRow)]
+//! struct UserProfile {
+//! id: i64,
+//! username: String,
+//! email: String,
+//! scores: Vec<i32>,
+//! preferences: BTreeMap<String, String>,
+//! is_active: bool,
+//! }
+//!
+//! let profile = UserProfile {
+//! id: 12345,
+//! username: "alice".to_string(),
+//! email: "[email protected]".to_string(),
+//! scores: vec![95, 87, 92, 88],
+//! preferences: BTreeMap::from([
+//! ("theme".to_string(), "dark".to_string()),
+//! ("language".to_string(), "en".to_string()),
+//! ]),
+//! is_active: true,
+//! };
+//!
+//! // Serialize to row format
+//! let row_data = to_row(&profile);
+//!
+//! // Deserialize with zero-copy access
+//! let row = from_row::<UserProfile>(&row_data);
+//!
+//! // Access fields directly from the row data
+//! assert_eq!(row.id(), 12345);
+//! assert_eq!(row.username(), "alice");
+//! assert_eq!(row.email(), "[email protected]");
+//! assert_eq!(row.is_active(), true);
+//!
+//! // Access collections efficiently
+//! let scores = row.scores();
+//! assert_eq!(scores.size(), 4);
+//! assert_eq!(scores.get(0), 95);
+//! assert_eq!(scores.get(1), 87);
+//!
+//! let prefs = row.preferences();
+//! assert_eq!(prefs.keys().size(), 2);
+//! assert_eq!(prefs.keys().get(0), "language");
+//! assert_eq!(prefs.values().get(0), "en");
+//! ```
+//!
+//! ## Supported Types
+//!
+//! Fory supports a wide range of Rust types:
+//!
+//! ### Primitive Types
+//! - `bool`, `i8`, `i16`, `i32`, `i64`, `f32`, `f64`
+//! - `String`, `&str` (in row format)
+//! - `Vec<u8>` for binary data
+//!
+//! ### Collections
+//! - `Vec<T>` for arrays/lists
+//! - `HashMap<K, V>` and `BTreeMap<K, V>` for maps
+//! - `Option<T>` for nullable values
+//!
+//! ### Date and Time
+//! - `chrono::NaiveDate` for dates
+//! - `chrono::NaiveDateTime` for timestamps
+//!
+//! ### Custom Types
+//! - Structs with `#[derive(Fory)]` or `#[derive(ForyRow)]`
+//! - Enums with `#[derive(Fory)]`
+//!
+//! ## Serialization Modes
+//!
+//! Fory supports two serialization modes:
+//!
+//! - **SchemaConsistent**: Type declarations must be consistent between
+//! serialization and deserialization peers (default)
+//! - **Compatible**: Type declarations can differ between peers, allowing
+//! independent field additions/deletions
+//!
+//! ```rust
+//! use fory::Fory;
+//! use fory_core::types::Mode;
+//! use fory_derive::Fory;
+//!
+//! #[derive(Fory, Debug, Default)]
+//! struct Config {
+//! name: String,
+//! value: i32,
+//! }
+//!
+//! let mut fory = Fory::default().mode(Mode::Compatible);
+//! fory.register::<Config>(100);
+//! // ... use fory for serialization
+//! ```
+//!
+//! ## Error Handling
+//!
+//! Fory provides comprehensive error handling through the `Error` type:
+//!
+//! ```rust
+//! use fory::{Fory, Error};
+//! use fory_derive::Fory;
+//!
+//! #[derive(Fory, Default)]
+//! struct Data {
+//! value: i32,
+//! }
+//!
+//! fn process_data(bytes: &[u8]) -> Result<Data, Error> {
+//! let mut fory = Fory::default();
+//! fory.register::<Data>(100);
+//!
+//! // This can fail if the data is corrupted or type mismatches
+//! let data: Data = fory.deserialize(bytes)?;
+//! Ok(data)
+//! }
+//! ```
+//!
+//! ## Performance Considerations
+//!
+//! - **Object Serialization**: Best for complex object graphs with references
+//! - **Row Serialization**: Best for high-throughput, zero-copy scenarios
+//! - **Type Registration**: Register all types before serialization for
optimal performance
+//! - **Buffer Pre-allocation**: Fory automatically reserves space to minimize
allocations
+//!
+//! ## Cross-Language Compatibility
+//!
+//! Fory is designed to work across multiple programming languages, making it
+//! ideal for microservices architectures and distributed systems where
different
+//! services may be implemented in different languages.
+//!
+//! ## Getting Started
+//!
+//! Add Fory to your `Cargo.toml`:
+//!
+//! ```toml
+//! [dependencies]
+//! fory = "0.1"
+//! fory-derive = "0.1"
+//! chrono = "0.4"
+//! ```
+//!
+//! Then use the derive macros to make your types serializable:
+//!
+//! ```rust
+//! use fory_derive::{Fory, ForyRow};
+//!
+//! #[derive(Fory, Default)] // For object serialization
+//! #[derive(ForyRow)] // For row-based serialization
+//! struct MyData {
+//! field1: String,
+//! field2: i32,
+//! }
+//! ```
+
pub use fory_core::{error::Error, fory::Fory, row::from_row, row::to_row};
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
