Skip to main content

StructSerializer

fory_core::serializer

Trait StructSerializer 

Source 
pub trait StructSerializer: Serializer + 'static {
    // Required method
    fn fory_read_compatible(
        context: &mut ReadContext<'_>,
        type_info: Rc<TypeInfo>,
    ) -> Result<Self, Error>
       where Self: Sized;

    // Provided methods
    fn fory_fields_info(
        type_resolver: &TypeResolver,
    ) -> Result<Vec<FieldInfo>, Error> { ... }
    fn fory_variants_fields_info(
        type_resolver: &TypeResolver,
    ) -> Result<Vec<(String, TypeId, Vec<FieldInfo>)>, Error> { ... }
    fn fory_type_index() -> u32 { ... }
    fn fory_actual_type_id(
        type_id: u32,
        register_by_name: bool,
        compatible: bool,
        xlang: bool,
    ) -> u32 { ... }
    fn fory_get_sorted_field_names() -> &'static [&'static str] { ... }
}
Expand description

Extended trait for struct and enum serialization.

StructSerializer extends Serializer with capabilities specific to struct and enum types, including field metadata, schema evolution, and compatibility features. This trait is used internally by Fory and automatically implemented by the derive macro.

§⚠️ Important: Do NOT Implement This for Custom User Types

User types with custom serialization should NOT implement this trait. This trait is:

  • Only for derive-based types: Automatically implemented by #[derive(ForyObject)]
  • Internal infrastructure: Used by Fory’s struct/enum deserialization engine
  • Not for manual implementation: Unless you’re extending Fory’s core functionality

For user types that need custom serialization logic (EXT types), implement only the Serializer trait.

§Purpose

This trait enables Fory’s advanced struct/enum features:

  • Field introspection: Access to struct field metadata for serialization
  • Schema evolution: Forward and backward compatibility for struct/enum changes
  • Compatible deserialization: Read structs with different field sets (added/removed fields)
  • Type indexing: Efficient type lookup for struct/enum types
  • Hash-based identification: Support for versioned struct schemas

§Automatic Implementation

The #[derive(ForyObject)] macro automatically implements this trait for structs and enums:

ⓘ
#[derive(ForyObject)]
struct Point {
    x: f64,
    y: f64,
}
// StructSerializer is automatically implemented
// Users should never implement this manually for custom serialization

§Usage by Fory

Fory uses this trait internally for:

  • Struct serialization: Writing field metadata and data
  • Enum serialization: Writing variant information
  • Compatible reads: Handling schema evolution scenarios
  • Type registration: Managing struct/enum type metadata

§Implementation Notes

  • Do not implement manually for user types with custom serialization (EXT types)
  • Only via derive macro: #[derive(ForyObject)] is the only supported way
  • Internal use only: Methods are called by Fory’s serialization engine
  • Schema evolution: Enables adding/removing fields without breaking compatibility

§See Also

  • Serializer: Base trait that user types with custom serialization should implement
  • FieldInfo: Metadata about struct fields

Required Methods§

Source

fn fory_read_compatible( context: &mut ReadContext<'_>, type_info: Rc<TypeInfo>, ) -> Result<Self, Error>
where Self: Sized,

Deserialize a struct with schema compatibility support.

This method enables reading structs even when the reader’s schema differs from the writer’s schema. It handles:

  • Missing fields (uses defaults)
  • Extra fields (skips them)
  • Reordered fields
  • Type changes (within compatibility rules)
§Parameters
  • context - Read context with buffer and resolvers
  • type_info - Type metadata from the serialized data
§Returns

A deserialized instance with compatible field mapping.

§Errors

Returns an error if:

  • Required fields are missing without defaults
  • Field types are incompatible
  • Data is corrupted
§Implementation Notes
  • Implemented automatically by #[derive(ForyObject)] macro
  • Enables forward and backward compatibility
  • Uses field names for matching when possible
  • Falls back to field order for unnamed fields
  • Do not implement for user types with custom serialization (EXT types)

Provided Methods§

Source

fn fory_fields_info( type_resolver: &TypeResolver, ) -> Result<Vec<FieldInfo>, Error>

Get metadata about this struct’s fields.

Returns information about each field in the struct, including names, types, and offsets. This is used for schema evolution and compatibility.

§Parameters
  • type_resolver - The type registry for looking up field types
§Returns

A vector of FieldInfo describing each field, or an empty vector by default.

§Implementation Notes
  • Implemented automatically by #[derive(ForyObject)] macro
  • Default returns empty vector (no fields)
  • Do not implement for user types with custom serialization (EXT types)
Source

fn fory_variants_fields_info( type_resolver: &TypeResolver, ) -> Result<Vec<(String, TypeId, Vec<FieldInfo>)>, Error>

Source

fn fory_type_index() -> u32

Get the type index for fast struct type lookup.

Type index provides O(1) lookup for struct types in the type registry.

§Returns

A unique index assigned to this struct type.

§Implementation Notes
  • Implemented automatically by #[derive(ForyObject)] macro
  • Used for efficient type resolution
  • Do not implement for user types with custom serialization (EXT types)
Source

fn fory_actual_type_id( type_id: u32, register_by_name: bool, compatible: bool, xlang: bool, ) -> u32

Get the actual type ID considering registration and compatibility modes.

This method computes the effective type ID based on how the type was registered and whether compatibility mode is enabled.

§Parameters
  • type_id - The base type ID
  • register_by_name - Whether type was registered by name (vs by hash)
  • compatible - Whether compatibility mode is enabled
  • xlang - Whether cross-language mode is enabled
§Returns

The actual type ID to use for serialization/deserialization.

§Implementation Notes
  • Default delegates to struct_::actual_type_id
  • Handles type ID transformations for compatibility
  • Do not override for user types with custom serialization (EXT types)
Source

fn fory_get_sorted_field_names() -> &'static [&'static str]

Get sorted field names for consistent serialization order.

Returns field names in sorted order to ensure deterministic serialization and enable schema evolution.

§Returns

A static slice of field names in sorted order, or empty slice by default.

§Implementation Notes
  • Implemented automatically by #[derive(ForyObject)] macro
  • Used for field ordering and compatibility
  • Field order affects wire format
  • Do not implement for user types with custom serialization (EXT types)

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors§