Skip to content

Conversation

@chaokunyang
Copy link
Collaborator

@chaokunyang chaokunyang commented Dec 25, 2025

Why?

This PR implements field-level optimization attributes for Rust, enabling users to control serialization behavior at the field level. This reduces serialization overhead by:

  1. Using compact field ID encoding instead of field name encoding
  2. Allowing explicit control over nullable and reference tracking flags
  3. Supporting field skipping for transient data

What does this PR do?

New Field Attributes

Adds support for #[fory(...)] field attributes with the following options:

Attribute Description Default
id = N Field tag ID for compact encoding (N >= 0) Uses field name
nullable Whether field can be null true for Option<T>, RcWeak<T>, ArcWeak<T>; false otherwise
ref Enable reference tracking true for Rc<T>, Arc<T>, RcWeak<T>, ArcWeak<T>; false otherwise
skip Skip field during serialization false

Usage Examples

#[derive(ForyObject)]
struct User {
    #[fory(id = 0)]  // Use compact field ID encoding
    name: String,
    
    #[fory(id = 1, nullable)]
    email: Option<String>,
    
    #[fory(ref = false)]  // Disable ref tracking for this Rc
    data: Rc<Data>,
    
    #[fory(skip)]  // Exclude from serialization
    cache: HashMap<String, String>,
}

Compact Field ID Encoding

Per xlang_serialization_spec.md, field IDs use TAG_ID encoding:

| 2 bits encoding (0b11) | 4 bits field_id | 1 bit nullable | 1 bit ref_tracking |

This provides ~28% smaller payload compared to field name encoding for structs with explicit field IDs.

Implementation Details

  • field_meta.rs: New module for parsing #[fory(...)] attributes
  • type_meta.rs: Updated FieldInfo with new_with_id() constructor and compact encoding
  • misc.rs: Generates field metadata with nullable/ref_tracking/field_id
  • util.rs: Updated fingerprint computation to include field metadata
  • Merged with tuple struct support from main branch

Related issues

Closes #3004
#1017

Does this PR introduce any user-facing change?

  • Does this PR introduce any public API change?
    • Adds optional #[fory(...)] field attributes
    • Fully backward compatible (no attributes = existing behavior)
  • Does this PR introduce any binary protocol compatibility change?
    • Uses existing TAG_ID encoding from xlang spec

Benchmark

Field ID encoding produces ~28% smaller payloads:

  • With field IDs: 98 bytes
  • With field names: 137 bytes

@chaokunyang chaokunyang requested review from pandalee99, theweipeng and urlyy and removed request for theweipeng December 25, 2025 02:08
- Run cargo fmt to fix formatting issues
- Wrap generic type parameters in doc comments with backticks
  to avoid being interpreted as HTML tags
- Fix misleading comment: compact field ID encoding IS implemented
- Add assertion verifying field ID encoding produces smaller payloads
- Field IDs use TAG_ID encoding (0b11 marker) per xlang spec
Wrap generic type parameters in FieldTypeClass enum doc comments
with backticks to avoid rustdoc HTML tag warnings.
Resolved conflicts combining tuple struct support with field metadata:
- misc.rs: Use enumerate + get_field_name for tuple structs with field ID metadata
- read.rs: Keep tuple struct index parameter with sorted index matching comment
- util.rs: Use get_field_name(field, idx) in fingerprint computation
@chaokunyang chaokunyang changed the title feat(rust): add rust field meta configuration support feat(rust): support configure rust field meta to reduce extra cost Dec 25, 2025
@chaokunyang chaokunyang mentioned this pull request Dec 25, 2025
17 tasks
@chaokunyang chaokunyang changed the title feat(rust): support configure rust field meta to reduce extra cost feat(rust): support configure rust field meta to reduce cost Dec 25, 2025
@chaokunyang chaokunyang merged commit 9a795f9 into apache:main Dec 25, 2025
55 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Rust] Add #[fory()] field attributes for optimization metadata

2 participants