Crate fory_core 

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
• Trait objects (Box, Rc, Arc)

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

Trait Object Serialization

Fory supports polymorphic serialization through trait objects:

Box-Based Trait Objects

Define custom traits and register implementations:

use fory_core::{Fory, register_trait_type, Serializer};
use fory_derive::ForyObject;

trait Animal: Serializer {
    fn speak(&self) -> String;
}

#[derive(ForyObject, Debug)]
struct Dog { name: String }

#[derive(ForyObject, Debug)]
struct Cat { name: String }

impl Animal for Dog {
    fn speak(&self) -> String { "Woof!".to_string() }
}

impl Animal for Cat {
    fn speak(&self) -> String { "Meow!".to_string() }
}

register_trait_type!(Animal, Dog, Cat);

#[derive(ForyObject)]
struct Zoo {
    star_animal: Box<dyn Animal>,
}

let mut fory = Fory::default().compatible(true);
fory.register::<Dog>(100);
fory.register::<Cat>(101);
fory.register::<Zoo>(102);

let zoo = Zoo {
    star_animal: Box::new(Dog { name: "Buddy".to_string() }),
};

let bytes = fory.serialize(&zoo);
let decoded: Zoo = fory.deserialize(&bytes).unwrap();
assert_eq!(decoded.star_animal.speak(), "Woof!");

Rc/Arc-Based Trait Objects

For reference-counted trait objects, use them directly in struct fields:

#[derive(ForyObject)]
struct Shelter {
    animals_rc: Vec<Rc<dyn Animal>>,
    animals_arc: Vec<Arc<dyn Animal>>,
}

For standalone serialization, use auto-generated wrapper types (e.g., AnimalRc, AnimalArc) created by register_trait_type! due to Rust’s orphan rule limitations.

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.

use fory_core::fory::Fory;
use fory_core::error::Error;
use fory_core::row::{to_row, from_row};
use std::collections::HashMap;

// Create a Fory instance
let mut fory = Fory::default().compatible(true);

// Serialize String
let text = String::from("Hello, Fory!");
let serialized_str = fory.serialize(&text).unwrap();
let deserialized_str: String = fory.deserialize(&serialized_str).unwrap();
assert_eq!(text, deserialized_str);

// Serialize Vec
let vec_data = vec![1, 2, 3, 4, 5];
let serialized_vec = fory.serialize(&vec_data).unwrap();
let deserialized_vec: Vec<i32> = fory.deserialize(&serialized_vec).unwrap();
assert_eq!(vec_data, deserialized_vec);

// Serialize HashMap
let mut map = HashMap::new();
map.insert("key1".to_string(), 100);
map.insert("key2".to_string(), 200);
let serialized_map = fory.serialize(&map).unwrap();
let deserialized_map: HashMap<String, i32> = fory.deserialize(&serialized_map).unwrap();
assert_eq!(map, deserialized_map);
// 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);

Re-exports

pub use crate::buffer::Reader;

pub use crate::buffer::Writer;

pub use crate::config::Config;

pub use crate::error::Error;

pub use crate::fory::Fory;

pub use crate::resolver::context::ReadContext;

pub use crate::resolver::context::WriteContext;

pub use crate::resolver::type_resolver::TypeInfo;

pub use crate::resolver::type_resolver::TypeResolver;

pub use crate::serializer::weak::ArcWeak;

pub use crate::serializer::weak::RcWeak;

pub use crate::serializer::read_data;

pub use crate::serializer::write_data;

pub use crate::serializer::ForyDefault;

pub use crate::serializer::Serializer;

pub use crate::serializer::StructSerializer;

pub use crate::types::RefFlag;

pub use crate::types::RefMode;

pub use crate::types::TypeId;

pub use paste;

Modules

buffer

config

error

PERFORMANCE CRITICAL MODULE

fory

meta

resolver

row

serializer

types

util

Macros

bail

Returns early with an Error.

downcast_and_serialize

Helper macro for common type resolution and downcasting pattern

ensure

Ensures a condition is true; otherwise returns an Error.

generate_smart_pointer_wrapper

Unified macro to generate smart pointer wrapper types for traits Supports both Rc and Arc pointer types

impl_smart_pointer_serializer

Shared serializer implementation for smart pointer wrappers

impl_tuple_serializer

Macro to implement Serializer for tuples of various sizes. Fory supports tuples up to 22 elements, longer tuples are not allowed.

not_allowed

Returns early with a Error::NotAllowed.

read_ptr_trait_object

Macro to read smart pointer trait objects (Rc<dyn Trait>, Arc<dyn Trait>) This macro handles ref tracking and directly constructs the trait object from concrete types

register_trait_type

Macro to register trait object conversions for custom traits.

unwrap_rc

Convert wrapper back to Rc<dyn Trait> for deserialization

wrap_arc

Convert Arc<dyn Trait> to wrapper for serialization

wrap_rc

Helper macros for automatic conversions in derive code These are used by fory-derive to generate transparent conversions

wrap_vec_rc

Convert Vec<Rc<dyn Trait>> to Vec<wrapper> for serialization