<![CDATA[Stories by Shawn.Yang on Medium]]> https://medium.com/@shawn.ck.yang?source=rss-c54c340fa1bb------2 https://cdn-images-1.medium.com/fit/c/150/150/1*j1iKBEf-fYVFr46Xp9jPsw.jpeg Stories by Shawn.Yang on Medium https://medium.com/@shawn.ck.yang?source=rss-c54c340fa1bb------2 Medium Tue, 23 Jun 2026 17:27:05 GMT <![CDATA[Apache Fory Serialization 1.0 Released Now]]> https://medium.com/@shawn.ck.yang/apache-fory-serialization-1-0-released-now-b1c4a76f397d?source=rss-c54c340fa1bb------2 https://medium.com/p/b1c4a76f397d Thu, 28 May 2026 13:02:20 GMT 2026-05-28T13:04:56.860Z I’m excited to announce the Apache Fory Serialization Framework 1.0.0 release. This milestone release includes 84 PRs from 11 distinct contributors and turns the cross-language runtime into the default path across supported languages. See the Install page to get the libraries for your platform.

Highlights

Apache Fory 1.0.0 standardizes the cross-language serialization model. The unified xlang type system is now the default mode across languages, with compatible-mode reads, simplified field ordering, and better list/array compatibility. The release also adds decimal and bfloat16 support for xlang serialization.

The language runtimes continue to converge around the same schema and metadata model. Nested container and field codec support landed across Rust, C++, C#, Go, Dart, Python, and Swift. Kotlin gains xlang, KSP, and schema IDL support, while Scala adds schema IDL support and updated generated annotations.

This release also expands deployment coverage and performance work. Java gains Android serialization support, annotation processor support, schema typed row field accessors, and nested type-use serialization metadata. Dart typed-container fast paths and generated struct optimizations improve throughput, alongside refreshed benchmark plots.

Key Features:

Features

Bug Fixes

Other Improvements

New Contributors

Full Changelog: https://github.com/apache/fory/compare/v0.17.0...v1.0.0

]]> <![CDATA[Extend Protobuf/FlatBuffers Schema IDL with Shared/Circular Reference Support]]> https://medium.com/@shawn.ck.yang/extend-protobuf-flatbuffers-schema-idl-with-shared-circular-reference-support-af4ec3637231?source=rss-c54c340fa1bb------2 https://medium.com/p/af4ec3637231 Tue, 17 Mar 2026 02:58:59 GMT 2026-03-17T02:58:59.027Z TL;DR: If you already have .proto or .fbs schemas and you want shared/circular reference support, with the Fory compiler you can keep those schemas, add a small set of Fory options, then foryc generates idiomatic native models across Fory-supported languages, so you can serialize object graphs without manual *_id link reconstruction or rewriting your entire schema into Fory Schema.

The Gap in Protobuf and FlatBuffers Schemas

Many production models are object graphs, not pure value trees:

  • Parent pointers (child.parent)
  • Shared nodes (two edges pointing to the same object)
  • Cycles (A -> B -> A)

In plain protobuf or FlatBuffers schema design, these relationships are usually represented indirectly with manual ID links (parent_id, child_ids) and rebuilt in application code after decode.

Apache Fory adds schema-level reference tracking so these graph semantics can be declared directly in protobuf/FlatBuffers source via Fory options.

Keep .proto and .fbs, Add Graph Semantics

You do not need to rewrite everything into .fdl first.

  • For protobuf input, use (fory).ref, (fory).weak_ref, and related options.
  • For FlatBuffers input, use fory_ref:true, fory_weak_ref:true, and related attributes.
  • Compile with foryc.
  • Get Fory-generated models and Fory wire format.

Important: this path reuses schema syntax and structure, but serialization output is Fory binary protocol, not protobuf/FlatBuffers wire compatibility.

Protobuf: From ID Workarounds to ref

Protobuf-style workaround (value-tree oriented)

message TreeNode {
  string id = 1;
  string parent_id = 2;
  repeated string child_ids = 3;
}

Protobuf + Fory options (graph semantics)

syntax = "proto3";
message TreeNode {
  TreeNode parent = 1 [(fory).weak_ref = true];
  repeated TreeNode children = 2 [(fory).ref = true];
}

What this means:

  • weak_ref = true implies ref tracking and generates weak-pointer semantics where relevant (for example C++/Rust).
  • For repeated fields, (fory).ref = true applies to list elements.
  • For map<K, V>, (fory).ref = true applies to map values.

You can also tune Rust pointer flavor:

message Graph {
  Node root = 1 [(fory).ref = true, (fory).thread_safe_pointer = false];
}

FlatBuffers: Add fory_ref Attributes

FlatBuffers schema with Fory reference attributes

namespace demo;
table Node {
  parent: Node (fory_weak_ref: true);
  children: [Node] (fory_ref: true);
  cached: Node (fory_ref: true, fory_thread_safe_pointer: false);
}

Semantics:

  • fory_weak_ref:true implies reference tracking.
  • fory_thread_safe_pointer affects pointer flavor on ref-tracked fields.
  • For list fields, fory_ref:true applies to elements.

FlatBuffers input is translated into Fory IR, then normal Fory codegen runs. The generated API surface is native objects (not FlatBuffers ByteBuffer-wrapper APIs).

Inspect Before You Commit

You can inspect how .proto or .fbs is translated:

# Protobuf to translated Fory schema
foryc schema.proto --emit-fdl
# FlatBuffers to translated Fory schema
foryc schema.fbs --emit-fdl --emit-fdl-path ./translated

Then generate code:

foryc schema.proto \
  --java_out=./java/gen \
  --python_out=./python/gen \
  --go_out=./go/gen \
  --rust_out=./rust/gen \
  --cpp_out=./cpp/gen

This is the migration-friendly loop:

  1. Keep existing schema files.
  2. Add only Fory reference options where graph semantics are required.
  3. Inspect translated .fdl.
  4. Generate and run roundtrip tests.

What You Get After Generation

With Fory codegen, you get native language models and reference-aware serialization behavior:

  • Java: POJOs/records with Fory metadata
  • Python: dataclasses + registration helpers
  • Go: structs with tags
  • Rust: native structs with ref-pointer mapping
  • C++: native classes/structs with shared/weak pointer mapping
  • C#, Swift, and more: idiomatic generated models

For object-graph-heavy workflows, this removes a common layer of manual ID-link hydration code.

Behavioral Boundaries to Keep in Mind

  1. This is not protobuf or FlatBuffers wire compatibility. The schema frontend is reused, but bytes on the wire are Fory protocol.
  2. Protobuf unknown-field behavior is different. Protobuf preserves unknown fields; Fory does not preserve protobuf unknown-field payloads.
  3. Reference tracking should be explicit and minimal. Use ref/weak_ref for true shared/cyclic parts of the graph, not for all fields.

Practical Migration Pattern

If you already run protobuf or FlatBuffers in production:

  1. Keep package/namespace names stable.
  2. Add Fory reference options only to graph-shaped fields.
  3. Generate code with foryc and run roundtrip tests.
  4. Migrate internal object-heavy paths first.
  5. Keep external protobuf/gRPC boundaries as-is when needed.

This lets you adopt graph semantics incrementally without a full schema rewrite.

Conclusion

Protobuf and FlatBuffers schema files can be a starting point for Fory graph-aware serialization, not a blocker.

By adding a small set of Fory extension options (ref, weak_ref, pointer-style hints), you can express shared identity and circular links directly in existing .proto/.fbs sources, generate native models, and remove manual object-link reconstruction code in object-graph-heavy systems.

If your data model is a graph, make that graph explicit in the schema.

Get started:

pip install fory-compiler
foryc --help

References:

]]> <![CDATA[Apache Fory™ Schema IDL: Serialization IDL for Object Graphs and Generated API Ergonomics]]> https://medium.com/@shawn.ck.yang/apache-fory-schema-idl-serialization-idl-for-object-graphs-and-generated-api-ergonomics-00b8ffbd30d3?source=rss-c54c340fa1bb------2 https://medium.com/p/00b8ffbd30d3 Thu, 12 Mar 2026 06:04:10 GMT 2026-03-12T06:04:10.791Z TL;DR: Apache Fory Schema IDL is the first cross-language serialization IDL for object graphs serialization. Define your types once in a .fdl file, and the compiler generates idiomatic domain objects for Java, Python, Go, Rust, C++, C#, Swift, and more — with shared refs, cycles, polymorphism, schema evolution, and optional types built into the schema model.

The Object Graph Gap

Most existing serialization IDLs model data as value trees: flat messages with no schema-level notion of shared identity, cycles, or reusable standalone polymorphic types. When the actual data is a graph, that gap usually shows up in three places:

  1. Shared and Circular References: If two fields refer to the same logical object, Protocol Buffers and FlatBuffers do not preserve that shared identity in the schema or on the wire. Parent pointers, DAGs, and cycles have no schema-level representation, so they fall back to manual ID fields and application-side reconstruction.
  2. Polymorphism: Protobuf oneof and FlatBuffers union are inline alternatives embedded in an enclosing message, not reusable standalone schema types. Protobuf Any supports open-ended polymorphism, but only for messages and via a type URL. FlatBuffers has no equivalent.
  3. Generated Types as Domain Models: FlatBuffers APIs are primarily buffer-access wrappers. Protobuf generates transport-first types in many languages, so users often add a conversion layer to get back to idiomatic domain objects. The schema defines the wire format, but not the application model.

Apache Fory Schema IDL closes that gap.

What Makes Fory IDL Different?

Apache Fory Schema IDL is built around object graphs as a first-class concept. You define your types once — including shared references, circular structures, standalone unions, and polymorphic fields — run the compiler, and get idiomatic code in every supported language on top of the same Fory wire format.

In this article, “serialization IDL for object graphs” means the schema itself can describe shared identity, cycles, and reusable polymorphic types directly, instead of forcing users to flatten everything into value trees and rebuild links with manual IDs or application-side conventions later.

That shows up in three places:

  • ref makes shared references and cycles part of the schema contract.
  • union and any make polymorphism a reusable schema feature rather than only an inline transport detail.
  • The generated code stays usable as host-language application models instead of wrapper types that require another conversion layer.

The sections below show how that works in practice.

First-Class Shared References

Fory IDL has a ref modifier that makes shared and circular reference tracking explicit in the schema:

message TreeNode {
    string value = 1;
    ref TreeNode parent = 2;          // Shared reference — can point back
    list<ref TreeNode> children = 3;  // Each child is reference-tracked
}

When you serialize a tree where children point back to their parent, Fory encodes each object exactly once and uses back-references for duplicates. No manual ID-link fields. No application-level reconstruction logic. The object graph contract lives in the schema itself.

For parent pointers where you want to break ownership cycles, ref(weak=true) generates weak pointer types (e.g., ArcWeak<Node> in Rust, std::weak_ptr in C++).

Idiomatic Domain Objects, Not Wrappers

A key difference from Protocol Buffers and FlatBuffers is that compiling a Fory .fdl schema produces host-language models you can use directly:

  • Java: Plain POJOs with @ForyField annotations — usable directly in Spring, Hibernate, or any framework
  • Python: @dataclass types with standard type hints
  • Go: Structs with fory:"id=..." struct tags
  • Rust: Structs with #[derive(ForyObject)]
  • C++: final classes with FORY_STRUCT macros — zero runtime reflection
  • C#: Classes with [ForyObject] attributes
  • Swift: @ForyObject models with @ForyField metadata

In many applications, no adapter layer is needed. The generated types can be used directly as your domain objects.

Built-In Unions (Sum Types)

Fory IDL has a first-class union construct that maps to the most idiomatic sum type in each language:

message Dog {
    string name = 1;
    int32 bark_volume = 2;
}
message Cat {
    string name = 1;
    int32 lives = 2;
}
union Animal {
    Dog dog = 1;
    Cat cat = 2;
}

This generates:

  • Rust: enum Animal { Dog(Dog), Cat(Cat) }
  • C++: std::variant-based wrapper with is_dog(), as_dog(), visit() APIs
  • Swift: Tagged enum with associated values
  • Java: Union subclass with typed case accessors
  • Python: Union subclass with is_dog() / dog_value() helpers
  • Go: Typed case struct with AsDog() / visitor pattern
  • C#: Union subclass with IsDog / DogValue() helpers

Every language gets the same semantics, but expressed in each language’s idiom.

Polymorphic Fields with any

Sometimes you don’t know the concrete type of a field at schema-definition time. An event bus carries heterogeneous payloads. A plugin system accepts user-defined message types. Fory IDL’s any type handles this — it writes the runtime type identity into the binary stream and resolves it on the other side:

message Envelope {
    string event_type = 1;
    any payload = 2;          // Carries dynamic values supported by Fory
}

At runtime, payload can hold dynamic values supported by Fory — other generated messages, built-in scalars, or collection types. The serialized bytes include runtime type metadata, so the deserializer can reconstruct the concrete value on the other side:

LanguageGenerated Field TypeJavaObject payloadPythonpayload: AnyGoPayload anyRustpayload: Box<dyn Any>C++std::any payloadC#object PayloadSwiftvar payload: Any

This gives you protobuf Any-like flexibility, but in the generated Fory model and without requiring protobuf-style type URLs in the schema surface.

The three features above — ref, union/any, and idiomatic generated code — make Fory IDL an object-graph-first schema language. Schema evolution is a separate concern, but it completes the production story:

Schema Evolution Out of the Box

Add fields, remove fields, deploy independently. In compatible mode, fields are matched by field id, missing fields get defaults, and unknown fields are skipped:

// Version 1 — deployed to production
message User {
    string name = 1;
    int32 age = 2;
}
// Version 2 - new field added by another team
message User {
    string name = 1;
    int32 age = 2;
    optional string email = 3;  // New: safely ignored by V1 consumers
}

This still follows compatibility rules; it is not a license for arbitrary schema changes. But for normal additive and removal changes, you do not need coordinated big-bang deployments or a separate version-negotiation layer.

A Complete Walkthrough

Let’s build a realistic e-commerce schema, see it work across current Fory-supported languages, and then make the object-graph part explicit with a shared-customer round trip.

1. Define the Schema

Create ecommerce.fdl:

package ecommerce;
enum OrderStatus {
    PENDING = 0;
    CONFIRMED = 1;
    SHIPPED = 2;
    DELIVERED = 3;
}
message Address {
    string street = 1;
    string city = 2;
    string country = 3;
}
message Customer {
    string id = 1;
    string name = 2;
    optional string email = 3;
    optional Address address = 4;
}
message OrderItem {
    string sku = 1;
    int32 quantity = 2;
    float64 unit_price = 3;
}
message Order {
    string order_id = 1;
    ref Customer customer = 2;
    list<OrderItem> items = 3;
    OrderStatus status = 4;
    float64 total = 5;
    optional string notes = 6;
    timestamp created_at = 7;
}
message OrderBatch {
    list<Order> orders = 1;
}

2. Install the Compiler and Generate Code

pip install fory-compiler
# Generate code for all currently supported Fory IDL languages in one command
foryc ecommerce.fdl \
  --java_out=./java/src/main/java \
  --python_out=./python/gen \
  --go_out=./go/gen \
  --rust_out=./rust/gen \
  --cpp_out=./cpp/gen \
  --csharp_out=./csharp/gen \
  --swift_out=./swift/gen

A single command can generate code for multiple languages. Registration helpers, byte helpers, and type IDs are generated automatically.

3. Use the Generated Code

Java — serialize an order:

import ecommerce.*;
Order order = new Order();
order.setOrderId("ORD-2026-001");
Customer customer = new Customer();
customer.setName("Alice");
customer.setEmail("alice@example.com");
order.setCustomer(customer);
order.setStatus(OrderStatus.CONFIRMED);
order.setTotal(259.98);
// toBytes() / fromBytes() are generated - no Fory boilerplate
byte[] bytes = order.toBytes();
Order restored = Order.fromBytes(bytes);

Python — deserialize the same bytes:

from ecommerce import Order
# from_bytes() handles registration and deserialization
order = Order.from_bytes(bytes_from_java)
print(f"{order.order_id}: {order.customer.name} - ${order.total}")
# ORD-2026-001: Alice - $259.98

Go — process the order:

import "gen/ecommerce"
var order ecommerce.Order
if err := order.FromBytes(bytesFromJava); err != nil {
    panic(err)
}
fmt.Printf("%s: %s - $%.2f\n", order.OrderId, order.Customer.Name, order.Total)

Rust — type-safe deserialization:

use gen::ecommerce::Order;
let order = Order::from_bytes(&bytes_from_java)?;
println!("{}: {} - ${:.2}", order.order_id, order.customer.name, order.total);

C++ — zero-overhead access:

#include "gen/ecommerce.h"
auto order = ecommerce::Order::from_bytes(bytes_from_java).value();
std::cout << order.order_id() << ": " << order.customer().name()
          << " - $" << order.total() << std::endl;

C# — strongly-typed deserialization:

using Ecommerce;
var order = Order.FromBytes(bytesFromJava);
Console.WriteLine($"{order.OrderId}: {order.Customer.Name} - ${order.Total}");

Swift — idiomatic model access:

import Ecommerce
let order = try Order.fromBytes(bytesFromJava)
print("\(order.orderId): \(order.customer.name) - $\(order.total)")

The same schema and generated code produce compatible bytes across supported languages with no hand-written conversion layer.

4. Preserve Shared Identity, Not Just Values

Because Order.customer is declared as ref Customer, shared identity is part of the schema contract:

Customer customer = new Customer();
customer.setName("Alice");
Order first = new Order();
first.setOrderId("ORD-1");
first.setCustomer(customer);
Order second = new Order();
second.setOrderId("ORD-2");
second.setCustomer(customer);
OrderBatch batch = new OrderBatch();
batch.setOrders(java.util.Arrays.asList(first, second));
OrderBatch restored = OrderBatch.fromBytes(batch.toBytes());
assert restored.getOrders().get(0).getCustomer()
    == restored.getOrders().get(1).getCustomer();

With a value-tree serializer, you typically rebuild this identity yourself. With Fory IDL, the ref modifier makes it part of the schema and generated code.

The Full Feature Set

Nullable Fields with optional

message Profile {
    string username = 1;          // Non-optional
    optional string bio = 2;     // Nullable
    optional Address home = 3;   // Nullable struct
}

LanguageNon-optionalOptionalJavaString usernameString bio (nullable)Pythonusername: strbio: Optional[str]GoUsername stringBio *stringRustusername: Stringbio: Option<String>C++std::stringstd::optional<std::string>C#string Usernamestring? BioSwiftvar username: Stringvar bio: String?

Nested Types

message SearchResponse {
    message Result {
        string url = 1;
        string title = 2;
        list<string> snippets = 3;
    }
    list<Result> results = 1;
}

Nested types are rendered naturally in each language: SearchResponse.Result in Java/Python/C#/Swift, SearchResponse::Result in C++, search_response::Result in Rust, SearchResponse_Result in Go.

Imports for Multi-File Schemas

// common/types.fdl
package common;
message Address {
    string street = 1;
    string city = 2;
}
// models/user.fdl
package models;
import "common/types.fdl";
message User {
    string name = 1;
    Address home = 2;  // Uses imported type
}
foryc models/user.fdl -I common/ --java_out=./gen

The compiler resolves imports, catches import cycles, and keeps generated type registration consistent across imported schemas.

Language-Specific Options

Override output paths and naming conventions per language without affecting cross-language compatibility:

package payment;
option java_package = "com.mycorp.payment.v1";
option go_package = "github.com/mycorp/gen/payment;paymentv1";
option csharp_namespace = "MyCorp.Payment.V1";

These options control where code is generated and how host-language names are shaped — not the underlying Fory wire format or cross-language type identity.

Rich Type System

Fory IDL covers the full range of types you need for production schemas:

CategoryTypesIntegersint8, int16, int32, int64, uint8–uint64, fixed_*, tagged_*Floatsfloat32, float64Stringsstring, bytesTemporaldate, timestamp, durationSpecialdecimal, any, boolCollectionslist<T>, map<K, V>Modifiersoptional, ref, ref(weak=true)

Integer types use varint encoding by default for 32/64-bit values, with explicit fixed_* and tagged_* variants when you need specific encodings.

Migrating from Protobuf or FlatBuffers

Protobuf Migratio

Already have .proto schemas? The Fory compiler can read them directly and generate Fory code from them:

foryc existing_schema.proto --java_out=./gen --python_out=./gen

The output uses Fory-generated types and the Fory binary protocol. Reading .proto input does not mean protobuf wire compatibility.

Key mapping:

  • repeated T → list<T>
  • oneof → Fory union + optional field
  • google.protobuf.Timestamp → timestamp
  • google.protobuf.Any → any

You can also add Fory-specific extensions in your .proto files:

message TreeNode {
  TreeNode parent = 1 [(fory).weak_ref = true];
  repeated TreeNode children = 2 [(fory).ref = true];
}

FlatBuffers Migration

FlatBuffers schemas work too:

foryc existing_schema.fbs --lang java,python,go --output ./gen

Tables become evolving messages, structs become non-evolving messages, and unions map directly to Fory unions. As with protobuf input, the generated output uses Fory types and Fory wire format rather than FlatBuffers binary compatibility. Add fory_ref:true or fory_weak_ref:true attributes where graph semantics matter.

Inspect the Translation

See exactly how your protobuf/FlatBuffers schema maps to Fory IDL:

foryc schema.proto --emit-fdl

This prints the translated .fdl to stdout — useful for reviewing the mapping before committing to the migration.

Why Not Just Use Protobuf?

A direct comparison with Protocol Buffers is useful because it is the default reference point for many readers.

AspectProtocol BuffersFory IDLGenerated typesTransport-model-first in many languagesIdiomatic language constructsObject graphsApplication-level IDs / rebuildsFirst-class ref / ref(weak=true)Circular referencesNot built-inBuilt into generated schemasVariant fieldsoneof / Anyunion / any in the generated modelPerformanceMature baselineOften faster on object serialization workloadsgRPC ecosystemNative, matureIn progress (active development)Schema evolutionField numbers + wire typesCompatible mode for generated schemas with field-id matchingTarget languagesMany (via plugins)Java, Python, Go, Rust, C++, C#, Swift (and growing)

Use protobuf when gRPC ecosystem integration is your primary concern. Use Fory IDL when you need idiomatic domain objects, object-graph semantics, reference tracking, or maximum serialization performance.

Benchmark details and methodology live in the repository’s benchmark reports.

Build Integration

The Fory compiler integrates into every major build system. Below are examples for a few common ones — the same pattern (invoke foryc as a pre-build step) applies to Cargo build scripts, Bazel rules, CMake custom commands, Swift Package Manager plugins, and others:

Maven (Java):

<execution>
  <id>generate-fory-types</id>
  <phase>generate-sources</phase>
  <goals><goal>exec</goal></goals>
  <configuration>
    <executable>foryc</executable>
    <arguments>
      <argument>${basedir}/src/main/fdl/schema.fdl</argument>
      <argument>--java_out</argument>
      <argument>${project.build.directory}/generated-sources/fory</argument>
    </arguments>
  </configuration>
</execution>

Gradle (Kotlin/Java):

task generateForyTypes(type: Exec) {
    commandLine 'foryc', "${projectDir}/src/main/fdl/schema.fdl",
        '--java_out', "${buildDir}/generated/sources/fory"
}
compileJava.dependsOn generateForyTypes

Go Generate:

//go:generate foryc ../schema.fdl --lang go --output .
package models

Python (setuptools):

class BuildWithForyIdl(build_py):
    def run(self):
        subprocess.run(['foryc', 'schema.fdl', '--python_out', 'src/generated'], check=True)
        super().run()

Best Practices

  1. Use meaningful package names: com.myapp.models groups types logically and drives namespace generation.
  2. Use optional explicitly: Don't rely on default nullability — make the intent clear in the schema.
  3. Use ref only when needed: Reference tracking has a per-object cost. Use it for shared objects and cycles; skip it for value-type payloads.
  4. Use imports for shared types: Put common types (Address, Timestamp, etc.) in a shared .fdl file and import them.
  5. Use --emit-fdl to review migrations: When consuming .proto or .fbs input, inspect the translated Fory IDL before committing.

Conclusion

Apache Fory Schema IDL puts object-graph semantics into the schema model instead of leaving them to ad-hoc application code. If you need shared refs, circular structures, polymorphic fields, schema evolution, and generated models that still look idiomatic in each language, it gives you one schema and one compiler workflow for all of that.

Define your types once. Generate everywhere. Serialize object graphs without giving up idiomatic models.

Get started:

pip install fory-compiler
foryc --help

Documentation:

Community:

]]> <![CDATA[Introducing Apache Fory™ C++: Blazing-Fast, Type-Safe Serialization for Modern C++]]> https://medium.com/@shawn.ck.yang/introducing-apache-fory-c-blazing-fast-type-safe-serialization-for-modern-c-f688f8e044ba?source=rss-c54c340fa1bb------2 https://medium.com/p/f688f8e044ba Thu, 12 Mar 2026 05:52:52 GMT 2026-03-12T05:52:52.876Z TL;DR: Apache Fory C++ is a blazing-fast, cross-language serialization framework delivering exceptional binary performance with support for polymorphic types, circular references, schema evolution, and seamless interoperability with Java, Python, Go, Rust, and JavaScript — all via modern C++17 with zero runtime reflection overhead.

The C++ Serialization Problem

Every C++ developer working in a polyglot environment eventually hits the same wall. Existing options force a painful choice:

  1. IDL-first frameworks (Protocol Buffers, FlatBuffers): Require upfront schema compilation, lose native C++ type expressiveness, and carry significant integration friction. Every type change means regenerating code across all languages in lock-step.
  2. Reflection-based frameworks (Boost.Serialization, cereal): Limited cross-language support, no circular reference handling, no polymorphism without boilerplate. They work well within a single language but break down at system boundaries.
  3. Hand-rolled binary formats: Fast but brittle — any schema change risks silent corruption, and every new type requires manual encode/decode logic.

Apache Fory C++ eliminates this trade-off. It delivers performance competitive with the fastest C++ serialization libraries while providing first-class support for polymorphism, shared/circular references, schema evolution, and binary compatibility with Java, Python, Go, Rust, and JavaScript — through a clean C++17 API.

What Makes Apache Fory C++ Different?

Compile-Time Code Generation

Most serialization frameworks pay a runtime cost for flexibility — inspecting type information through virtual dispatch or hash maps at every call. Apache Fory takes a different approach: the FORY_STRUCT macro uses C++ template metaprogramming to generate all serialization logic at compile time. The result is inlined, type-specific code with no virtual dispatch, no reflection, and no runtime overhead:

#include "fory/serialization/fory.h"
using namespace fory::serialization;struct Person {
  std::string name;
  int32_t age;
  std::vector<std::string> hobbies;
  std::map<std::string, std::string> metadata;
  std::optional<std::string> nickname;
};
FORY_STRUCT(Person, name, age, hobbies, metadata, nickname);

That single macro generates compile-time field metadata, efficient serialization/deserialization code via ADL (Argument-Dependent Lookup), and type registration hooks. The macro can be placed inside the class body to access private fields, or at namespace scope for third-party types.

Cross-Language Binary Protocol

Apache Fory C++ speaks the same binary wire format as Java, Python, Go, Rust, and JavaScript. Serialize a struct in C++, deserialize it in Python — no adaptation layer, no schema translation, no version negotiation needed. This is especially powerful for microservice architectures where different teams own different services in different languages:

// C++: Serialize
auto fory = Fory::builder().xlang(true).build();
fory.register_struct<Person>(100);
auto bytes = fory.serialize(person).value();
# Python: Deserialize (same binary format, same type ID)
fory = pyfory.Fory(xlang=True)
fory.register(Person, type_id=100)  # Same ID as C++
person = fory.deserialize(data)

The core requirements for cross-language interoperability are consistent type IDs/Names across participating runtimes, matching canonical field names, and compatible field types for those names.

Polymorphism via Smart Pointers

Serializing polymorphic objects is notoriously difficult in C++. Most frameworks require manual type tagging or generate large amounts of boilerplate. Apache Fory handles it automatically: it detects polymorphic types via std::is_polymorphic<T> and preserves the full runtime type identity through std::shared_ptr and std::unique_ptr. When you deserialize a shared_ptr<Animal> that holds a Dog, you get a Dog back — no extra code required:

struct Animal { virtual ~Animal() = default; int32_t age = 0; };
FORY_STRUCT(Animal, age);
struct Dog : Animal { std::string breed; };
FORY_STRUCT(Dog, FORY_BASE(Animal), breed);
struct Cat : Animal { std::string color; };
FORY_STRUCT(Cat, FORY_BASE(Animal), color);
struct Shelter { std::vector<std::shared_ptr<Animal>> animals; };
FORY_STRUCT(Shelter, animals);
auto fory = Fory::builder().track_ref(true).build();
fory.register_struct<Shelter>(10); fory.register_struct<Dog>(11); 
fory.register_struct<Cat>(12);
Shelter s;
s.animals.push_back(std::make_shared<Dog>()); // Dog at runtime
s.animals.push_back(std::make_shared<Cat>()); // Cat at runtime
auto decoded = fory.deserialize<Shelter>(fory.serialize(s).value()).value();
assert(dynamic_cast<Dog*>(decoded.animals[0].get()) != nullptr); // Runtime type preserved!

Fory also supports std::unique_ptr for exclusive-ownership polymorphic fields, and collections of smart pointers (std::vector<std::shared_ptr<Base>>, std::map<K, std::unique_ptr<Base>>).

Shared/Circular Reference Tracking

Many real-world data models contain shared objects or cycles: a parent node pointing to its children, which point back to the parent; an order referencing a customer who appears in multiple orders. Standard serialization frameworks either duplicate the data (wasting space) or crash with a stack overflow when they encounter a cycle.

With track_ref(true), Fory tracks object identity across the entire graph. Shared objects are serialized exactly once; every subsequent reference is encoded as a back-reference. Cycles terminate naturally:

struct Node {
  virtual ~Node() = default;
  int32_t id = 0;
  std::vector<std::shared_ptr<Node>> neighbors;
};
FORY_STRUCT(Node, id, neighbors);
auto fory = Fory::builder().track_ref(true).build();
fory.register_struct<Node>(200);
auto node1 = std::make_shared<Node>(); node1->id = 1;
auto node2 = std::make_shared<Node>(); node2->id = 2;
node1->neighbors.push_back(node2);
node2->neighbors.push_back(node1);  // Cycle - handled correctly!
auto bytes = fory.serialize(node1).value();
// No stack overflow, no duplicate data - the cycle is preserved faithfully
auto decoded = fory.deserialize<std::shared_ptr<Node>>(bytes).value();

This makes Fory a natural fit for graph databases, entity-component systems, and any domain model with bidirectional relationships.

Schema Evolution

In a microservice deployment, services update independently. A new version of the user service may add a phone field while old consumers are still running. Without schema evolution support, this forces a coordinated, big-bang deployment. Apache Fory's compatible mode removes this constraint entirely:

// Version 1
struct UserV1 { std::string name; int32_t age; };
FORY_STRUCT(UserV1, name, age);
// Version 2 - new fields added independently
struct UserV2 { std::string name; int32_t age; std::string email; };
FORY_STRUCT(UserV2, name, age, email);
auto fory_v1 = Fory::builder().compatible(true).xlang(true).build();
auto fory_v2 = Fory::builder().compatible(true).xlang(true).build();
fory_v1.register_struct<UserV1>(100);
fory_v2.register_struct<UserV2>(100);  // Same type ID enables evolution
auto bytes = fory_v1.serialize(UserV1{"Alice", 30}).value();
auto v2 = fory_v2.deserialize<UserV2>(bytes).value();
assert(v2.name == "Alice" && v2.email == "");  // Default for missing field

In compatible mode, fields are matched by name rather than position. New fields receive C++ default values when missing; removed fields are safely skipped. This enables rolling upgrades and independent service deployments without any serialization errors.

Row Format: Zero-Copy Analytics

Beyond object graph serialization, Apache Fory C++ implements a row-based binary format designed for analytics workloads. The row format stores data in a contiguous memory layout with a null bitmap, fixed-size slots for primitives, and a variable-length section for strings and nested objects. This enables O(1) random field access by index — you can read a single field from a large struct without touching the rest of the data.

This is particularly valuable in data pipelines and OLAP workloads where only a small subset of fields are queried per record:

#include "fory/encoder/row_encoder.h"
using namespace fory::row::encoder;
struct SensorReading {
  int32_t sensor_id; double temperature; std::string location;
  FORY_STRUCT(SensorReading, sensor_id, temperature, location);
};
RowEncoder<SensorReading> encoder;
encoder.encode({42, 23.5, "rack-B"});
auto row = encoder.get_writer().to_row();
// Read any field in O(1) - no deserialization of unused fields
int32_t id    = row->get_int32(0);
double  temp  = row->get_double(1);
auto    loc   = row->get_string(2);

For zero-copy access into an existing buffer (e.g., from a memory-mapped file or network receive buffer), Fory can point a Row directly at the memory without copying:

auto src = encoder.get_writer().to_row();
fory::row::Row view(src->schema());
view.point_to(src->buffer(), src->base_offset(), src->size_bytes());  // Zero-copy view
int32_t id = view.get_int32(0);  // Reads directly from the original buffer

Use the row format for analytics, OLAP-style workloads, and partial field access. Use object graph serialization for full object round-trips with references and polymorphism.

Installation

Fory C++ requires a C++17-compatible compiler (GCC 7+, Clang 5+, MSVC 2017+) and supports both CMake and Bazel build systems.

CMake (FetchContent)

The simplest integration is via CMake’s FetchContent module, which fetches and builds Fory as part of your project:

cmake_minimum_required(VERSION 3.16)
project(my_project LANGUAGES CXX)
set(CMAKE_CXX_STANDARD 17)
include(FetchContent)
FetchContent_Declare(fory
    GIT_REPOSITORY https://github.com/apache/fory.git
    GIT_TAG v0.15.0
    SOURCE_SUBDIR cpp)
FetchContent_MakeAvailable(fory)
add_executable(my_app main.cc)
target_link_libraries(my_app PRIVATE fory::serialization)

Bazel

For Bazel-based projects, add Fory as a module dependency:

bazel_dep(name = "fory", version = "0.15.0")
git_override(module_name = "fory",
    remote = "https://github.com/apache/fory.git",
    commit = "v0.15.0")
cc_binary(
    name = "my_app", 
    srcs = ["main.cc"],
    deps = ["@fory//cpp/fory/serialization:fory_serialization"]
)

Native Serialization

For pure C++ applications without cross-language requirements, disabling xlang produces a more compact binary encoding because no cross-language type metadata is emitted. This is the fastest possible path:

auto fory = Fory::builder()
    .xlang(false)      // Native C++ mode — tighter encoding
    .track_ref(false)  // Disable if no shared/circular refs
    .build();

fory.register_struct<Address>(1);
fory.register_struct<Person>(2);
// Serialize
auto result = fory.serialize(person);
if (!result.ok()) { std::cerr << result.error().to_string(); return 1; }
std::vector<uint8_t> bytes = std::move(result).value();
// Deserialize
auto decoded = fory.deserialize<Person>(bytes);
assert(decoded.ok() && person == decoded.value());

FORY_STRUCT handles several important C++ patterns that commonly arise in production codebases:

// Private fields — place macro in public: section
class Secure {
  int32_t secret_; std::string token_;
public:
  FORY_STRUCT(Secure, secret_, token_);
};
// Inheritance - FORY_BASE includes base class fields
struct Derived : Base {
  std::string extra;
  FORY_STRUCT(Derived, FORY_BASE(Base), extra);
};
// External/third-party types - use at namespace scope (public fields only)
namespace ext { struct Coord { double lat, lon; }; }
FORY_STRUCT(ext::Coord, lat, lon);

Error Handling

All Fory operations return Result<T, Error>, making error handling explicit and composable. The FORY_TRY macro provides a concise early-return pattern for functions that propagate errors:

// Option 1: Conditional check
auto r = fory.serialize(obj);
if (r.ok()) { auto bytes = std::move(r).value(); }
else { std::cerr << r.error().to_string(); }
// Option 2: FORY_TRY macro for early return
FORY_TRY(bytes, fory.serialize(obj));
// Use bytes directly - any error propagates automatically

Thread Safety

Fory provides two variants with different threading guarantees. Choose based on whether your serialization is centralized (shared instance) or distributed across threads:

// Single-threaded (fastest) — one instance per thread, no synchronization overhead
auto fory = Fory::builder().build();
// Thread-safe - shared across threads via an internal instance pool
auto fory = Fory::builder().build_thread_safe();
fory.register_struct<MyType>(1);  // Register all types before sharing
std::thread t([&]() { fory.serialize(obj); });  // Safe to call concurrently

Cross-Language Serialization

Without IDL

When you control both sides of the wire and can coordinate type definitions manually, the simplest approach is to register types with matching numeric IDs in each language. This requires no additional tooling and works well for small, stable schemas:

// C++
auto fory = Fory::builder().xlang(true).build();
fory.register_struct<Order>(201);
auto bytes = fory.serialize(order).value();
// Java — same binary format, same type ID
Fory fory = Fory.builder().withLanguage(Language.XLANG).build();
fory.register(Order.class, 201);
Order order = (Order) fory.deserialize(bytes);
# Python — same binary format, same type ID
fory = pyfory.Fory(xlang=True)
fory.register(Order, type_id=201)
order = fory.deserialize(data)

Field matching: In cross-language mode, field names are normalized to snake_case and matched by that canonical name. Ordering follows Fory’s xlang field-order rules (not simple alphabetical ordering), so keep names semantically consistent across languages.

With the Fory Schema IDL Compiler

As schemas grow and span more services and teams, manually maintaining consistent field names, type IDs, and type definitions across five languages becomes error-prone. The Fory Schema IDL Compiler (foryc) solves this by letting you define types once in a .fdl file and generating idiomatic, production-ready code for every target language. The generated code includes typed accessors, serialization macros, registration helpers, and to_bytes()/from_bytes() helpers — so you never write serialization plumbing by hand.

1. Install the compile

pip install fory-compiler
foryc --help

2. Write a schema (ecommerce.fdl)

Fory IDL syntax is concise and deliberately close to protobuf, so it is easy to pick up. Field modifiers like optional, ref, and list map directly to idiomatic C++ types:

package ecommerce;

enum OrderStatus {
    PENDING = 0; CONFIRMED = 1; SHIPPED = 2; DELIVERED = 3;
}
message Address {
    string street = 1; string city = 2; string country = 3;
}
message Customer {
    string           id      = 1;
    string           name    = 2;
    optional string  email   = 3;   // Nullable: maps to std::optional<std::string>
    optional Address address = 4;
}
message OrderItem {
    string  sku        = 1;
    int32   quantity   = 2;
    float64 unit_price = 3;
}
// Discount can be either a fixed amount or a percentage - modelled as a union
message FixedDiscount   { float64 amount     = 1; }
message PercentDiscount { float64 percentage = 1; }
// union maps to std::variant<FixedDiscount, PercentDiscount> in C++
union Discount {
    FixedDiscount   fixed   = 1;
    PercentDiscount percent = 2;
}
message Order {
    string            order_id   = 1;
    ref Customer      customer   = 2;  // ref: std::shared_ptr + reference tracking
    list<OrderItem>   items      = 3;  // list: std::vector<OrderItem>
    OrderStatus       status     = 4;
    float64           total      = 5;
    optional string   notes      = 6;
    timestamp         created_at = 7;
    optional Discount discount   = 8;  // optional union field
}

The IDL type system maps cleanly to native C++ constructs. union is a first-class IDL construct that generates a std::variant-based wrapper class in C++, with typed case accessors (is_fixed(), as_fixed(), etc.) and a visit() method. Here is the full set of field modifiers and their C++ equivalents:

ModifierC++ typePurposeoptional Tstd::optional<T>Nullable fieldref Tstd::shared_ptr<T>Shared / circular referenceref(weak=true) Tfory::serialization::SharedWeak<T>Weak reference (breaks cycles)list<T>std::vector<T>Ordered listmap<K,V>std::map<K,V>Key-value map

3. Generate code

foryc generates a single header file per schema for C++, and equivalent files for every other target language. All generated files use the same type IDs derived from the package and type names, guaranteeing binary compatibility without any manual coordination:

# Generate C++ header directly under ./generated
foryc ecommerce.fdl --cpp_out ./generated
# Generate multiple languages with explicit output directories
foryc ecommerce.fdl --cpp_out ./generated --java_out ./java/src/main/java --python_out ./python/gen --go_out ./go/gen --rust_out ./rust/gen

The output structure for C++ is one header per schema file under the directory passed to --cpp_out. For example, --cpp_out ./generated produces generated/ecommerce.h. The header contains all types under the ecommerce:: namespace, with FORY_STRUCT macros and a register_types() helper already wired up.

4. Use the generated C++ code

The generated header provides final classes with typed accessors and to_bytes()/from_bytes() helpers. There is no manual Fory instance setup required — the helpers manage it internally:

#include "generated/ecommerce.h"
ecommerce::Order order;
order.set_order_id("ORD-2025-001");
order.mutable_customer()->set_name("Alice");
order.set_status(ecommerce::OrderStatus::CONFIRMED);
order.set_total(159.98);
// to_bytes()/from_bytes() are generated - no Fory boilerplate needed
auto bytes = order.to_bytes().value();
auto restored = ecommerce::Order::from_bytes(bytes).value();
assert(restored.order_id() == "ORD-2025-001");

Because the generated Java, Python, and Go code uses the same type IDs, bytes serialized by the C++ to_bytes() helper can be deserialized by the Java fromBytes() or Python from_bytes() helpers out of the box — no extra configuration required.

Supported Types

Apache Fory C++ supports a comprehensive set of types covering all common C++ data structures and cross-language primitives:

CategoryC++ TypesPrimitivesbool, int8_t…int64_t, uint8_t…uint64_t, float, doubleStringsstd::string, std::string_view, std::u16stringCollectionsstd::vector<T>, std::set<T>, std::unordered_set<T>, std::map<K,V>, std::unordered_map<K,V>Optional/Unionstd::optional<T>, std::variant<Ts...>Smart Pointersstd::shared_ptr<T> (ref tracking + polymorphism), std::unique_ptr<T>, fory::serialization::SharedWeak<T>Temporalstd::chrono::nanoseconds, fory::serialization::Timestamp, fory::serialization::DateEnumsScoped/unscoped enums; use FORY_ENUM for non-continuous valuesUser structsAny type annotated with FORY_STRUCT

All collection element and map value types can be arbitrarily nested, including structs, smart pointers, and std::optional.

Configuration Reference

Fory instances are constructed through a fluent builder API. All options have sensible defaults, so most applications only need to set one or two:

auto fory = Fory::builder()
    .xlang(true)                // Cross-language binary protocol (default: true)
    .compatible(true)           // Schema evolution / compatible mode (default: false)
    .track_ref(true)            // Shared/circular reference tracking (default: true)
    .max_dyn_depth(10)          // Max polymorphic nesting depth (default: 5)
    .check_struct_version(true) // Validate struct hash on deserialization (default: false)
    .build();                   // Single-threaded; use build_thread_safe() for multi-thread

Tuning guide: Disable compatible for maximum throughput when schema changes are coordinated (same binary deployed together). Disable track_ref for pure value types with no sharing or cycles — it eliminates per-object reference bookkeeping. Use xlang(false) for C++-only deployments to get a more compact binary encoding.

Benchmarks

Apache Fory delivers exceptional performance across diverse data shapes. The combination of compile-time code generation, variable-length integer encoding, and a carefully designed binary protocol yields major gains versus text formats and strong results versus Protocol Buffers. In the current C++ benchmark report, Fory throughput vs Protobuf ranges from about 1.1x to 12.2x depending on workload and operation:

The C++ implementation achieves similar relative speedups to the Java implementation. Because both share the same binary protocol design, and C++ serialization code is generated at compile time (eliminating the JIT warm-up cost), C++ performance is competitive or superior for latency-sensitive workloads.

Serialized Data Sizes (bytes)

Conclusion

Apache Fory C++ brings together a set of capabilities that no other C++ serialization library delivers as a cohesive package:

  • Performance: Template-based compile-time codegen eliminates all runtime reflection overhead; a highly efficient binary protocol minimizes both serialized size and CPU cycles
  • Cross-language: The same binary format works natively with Java, Python, Go, Rust, and JavaScript
  • Native C++ idioms: std::shared_ptr, std::optional, std::variant, fory::serialization::SharedWeak — all handled naturally
  • Production-ready features: Polymorphism, circular references, schema evolution, thread safety out of the box
  • Schema-first option: The Fory IDL Compiler generates consistent, idiomatic code across all languages from a single .fdl definition — no more manually synchronizing type IDs across codebases

Whether you are building a high-performance game server, a polyglot microservice backend, a real-time analytics pipeline, or an embedded system serializing complex domain models, Apache Fory C++ has you covered.

Get started:

git clone https://github.com/apache/fory.git
cd fory/examples/cpp/hello_world
cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build
./build/hello_world

Documentation:

Community:

]]> <![CDATA[Awex: An Ultra‑Fast Weight Sync Framework Powering Trillion‑Scale Reinforcement Learning]]> https://medium.com/@shawn.ck.yang/awex-an-ultra-fast-weight-sync-framework-powering-trillion-scale-reinforcement-learning-766ebc79f58b?source=rss-c54c340fa1bb------2 https://medium.com/p/766ebc79f58b Thu, 20 Nov 2025 08:46:10 GMT 2025-11-20T09:07:59.488Z Awex: An Ultra‑Fast Weight Sync Framework for Second‑Level Updates in Trillion‑Scale Reinforcement Learning

Over the past few years, Reinforcement Learning (RL) has become a core technology for post-training large language models. From ChatGPT’s RLHF to DeepSeek/Claude/Llama’s post-training systems, all rely on reinforcement learning to align models with human preferences and enhance their reasoning capabilities, further expanding the boundaries of model intelligence.

In October this year, Ant Group open-sourced two industry-leading trillion-parameter models: the non-reasoning Ling-1T and the reasoning model Ring-1T. Ring-1T is built on our high-performance weight exchange framework Awex (Asystem Weight Exchange Framework), achieving trillion-parameter-level weight synchronization within 5–10 seconds across thousands of GPU clusters.

Awex is now officially open source: https://github.com/inclusionAI/asystem-awex

This article provides an in-depth introduction to Awex’s design philosophy, core challenges, solutions, and performance benchmarks.

Problems and Challenges

In large model reinforcement learning training, to improve inference efficiency, the Rollout phase typically uses independent high-performance inference engines (such as SGLang/vLLM). Weight synchronization refers to the process of transferring model weights from the training engine to the inference engine after each training step, ensuring that inference uses the latest parameters to generate samples, forming a complete training loop.

As RL model parameters and training cluster scales expand, along with the evolution and changes in different RL algorithms, weight synchronization faces the following technical challenges:

  • Heterogeneous parallelism strategy adaptation between training and inference engines: Training engines typically adopt DP + PP/VPP + TP + EP + CP (*), while inference engines mostly use DP + TP + EP. Different parallelism strategies lead to inconsistent weight sharding, requiring efficient Resharding mechanisms;
  • Differential weight precision and formats between training and inference engines: Inference engines often use low precision (FP8/INT4) to improve performance, while training engines use high precision (BF16/FP32) to ensure convergence. Different engines have different requirements for weight layout and fusion;
  • Exchange efficiency challenges from growing weight parameters: With the continuous evolution of Scaling Law, large model parameter scales have gradually grown to trillion-level. Transmitting 100TB+ data across thousand-GPU clusters makes transmission time a training bottleneck;
  • Co-located and separated deployment modes: Synchronous RL algorithms mostly adopt co-located mode, where training and inference share GPUs time-divisionally to maximize resource utilization; asynchronous RL algorithms use separated mode, where training and inference use different GPUs and run in parallel;
  • Dynamic scaling of inference instances: During training iterations, model outputs gradually become longer and Rollout time increases, requiring dynamic scaling of inference instances. Weight synchronization needs to support new instance integration.

(*Note: Common heterogeneous parallelism strategies include: Data Parallelism (DP), Pipeline Parallelism (PP), Tensor Parallelism (TP), Expert Parallelism (EP), and Context Parallelism (CP))

Limitations of Existing Systems

Existing weight transfer solutions mainly fall into two categories, both still facing performance bottlenecks in scenarios with large model parameters:

  • Weight exchange via distributed file systems: After completing a single training step, the training engine gathers model weights layer by layer and writes them to a shared file system, after which the inference engine loads the model weights from the shared file system. Limited by the performance of shared file systems, a 10B parameter model requires several minutes, while a trillion-parameter model takes hours or more;
  • Layer-by-layer weight synchronization via NCCL + Full Tensor: This is the weight exchange method adopted by some open-source frameworks. The training engine gathers the full tensor layer by layer on each GPU card, then maps it to the inference engine via CUDA IPC for weight loading. This approach executes serially layer by layer, cannot fully utilize bandwidth, has significant redundant transmission when TP is large, and still requires minutes or more of latency for large model parameters.

Considering these limitations, I began exploring whether a zero‑redundancy, transport‑based weight‑exchange framework could be built — one that avoids full‑tensor gathering and redundant bandwidth consumption.

The idea was simple: instead of collecting complete weights on each training worker, the training side would send only the tensor shards needed by each inference worker. If these shard‑level transfers occurred concurrently — without global synchronization or layer‑wise serialization — redundant communication would be eliminated, bandwidth usage maximized, and weight‑update latency greatly reduced even for very large models.

Those ideas came together and finally became Awex: a zero‑redundancy P2P weight‑exchange framework.

Awex Introduction

Awex is a weight synchronization framework between training and inference engines designed for ultimate performance, solving the core challenge of synchronizing training weight parameters to inference models in the RL workflow. It can complete TB-scale large-scale parameter synchronization within seconds, significantly reducing RL model training latency. Main features include:

  • ⚡ Blazing synchronization performance: Full synchronization of trillion-parameter models across thousand-GPU clusters within 6 seconds, industry-leading performance;
  • 🔄 Unified model adaptation layer: Automatically handles differences in parallelism strategies between training and inference engines and tensor format/layout differences, compatible with multiple model architectures;
  • 💾 Zero-redundancy Resharding transmission and in-place updates: Only transfers necessary shards, updates inference-side memory in place, avoiding reallocation and copy overhead;
  • 🚀 Multi-mode transmission support: Supports multiple transmission modes including NCCL, RDMA, and shared memory, fully leveraging NVLink/NVSwitch/RDMA bandwidth and reducing long-tail latency;
  • 🔌 Heterogeneous deployment compatibility: Adapts to co-located/separated modes, supports both synchronous and asynchronous RL algorithm training scenarios, with RDMA transmission mode supporting dynamic scaling of inference instances;
  • 🧩 Flexible pluggable architecture: Supports customized weight sharing and layout behavior for different models, while supporting integration of new training and inference engines.

GitHub Repo: https://github.com/inclusionAI/asystem-awex

Awex Overall Design

The Awex weight exchange framework consists primarily of three components:

  • WeightWriter: Runs within each training process, responsible for metadata collection and reporting of weight shards for the current training process, weight convert, resharding transfer plan construction, weight transmission, and other functions;
  • WeightReader: Runs on the control process of each inference instance, which starts a WorkerWeightsReader on each GPU managed by the inference instance, corresponding to the WeightWriter of the training process. Responsible for metadata collection and reporting of weight shards for each inference process, weight convert, resharding transfer plan construction, weight reception, and other functions;
  • MetaServer: Job-level global server for service discovery and weight metadata exchange between training and inference engines, as well as event notification functions in co-located scenarios;

The core functional modules of weight exchange consist mainly of 5 parts, which I will introduce one by one:

  • Unified training-inference weight convert: Responsible for converting weights from training and inference engines with different parallelism strategies and tensor layouts into a unified format for subsequent weight metadata calculation and weight transmission;
  • Global weight metadata calculation and exchange: After converting training and inference weights into a unified format, collects all weight shard metadata from each worker and reports to Meta Server for subsequent weight transmission plan construction;
  • P2P weight transmission execution plan: Training and inference engines obtain global weight shard metadata from all workers, then separately construct peer-to-peer deterministic transfer plan for sending and receiving;
  • NCCL weight transmission: Uses NCCL’s send/recv API for peer-to-peer weight transmission based on the constructed transmission plan;
  • RDMA weight transmission: Uses NUMA affinity and RDMA communication for globally load-balanced transfer plan for weight updates;

Awex also supports tensor-level validation of weights, comparing weights loaded through file system mode with those loaded through transmission mode at the tensor level for fine-grained comparison, ensuring the correctness of the transmission mode. Due to space limitations, this will not be expanded here.

(1) Unified Training-Inference Weight Convert

Due to different computational workloads, training and inference engines generally adopt different parallelism strategies. Megatron training engine uses 5D parallelism strategy, DeepSpeed/FSDP uses Zero + DP data parallelism, while SGLang and VLLM inference engines mostly use DP + TP + EP. Additionally, different engines perform fusion, transposition, and quantization optimizations on weights after loading to adapt to high-performance operators.

To eliminate differences between different engines for subsequent weight exchange, Awex constructs a unified weight convert layer that performs the following converts:

  • Weight splitting: Splits merged weights (such as FFN’s gate/up) into independent weights, supporting cross-TP Resharding;
  • Weight name unification: Converts all internal weights from all engines to the same namespace, establishing weight mapping relationships between training and inference engines;
  • Attention weight ReGroup: On the training engine side, regroups and aligns QKV weights along the inference engine’s TP/DPAttention parallelism strategy, avoiding shard explosion from fine-grained splitting;
  • Quantization, precision, and format conversion: Automatically converts weights on the training side according to the precision and format of the inference side, and this low-precision conversion can also reduce the amount of transmitted data.

The entire weight convert adaptation layer is implemented as a pluggable structure that can be fully customized at the engine layer, model weight convert, and sharding layer to meet the customization needs of complex scenarios.

(2) Global Weight Metadata Management

Each training and inference process needs to be aware of the weight metadata of all training and inference processes globally for constructing subsequent weight transfer plan. Awex also performs consistency validation of weight metadata between training and inference at this step. The main workflow is as follows:

  • Each process in the training engine performs weight convert and obtains metadata for the converted shards
  • Through all_gather_object, each rank obtains global training shard metadata
  • Rank0 on the training side serializes global metadata and reports it to Meta Server
  • Inference instance 0 on the inference side performs similar work; other inference instances have identical metadata and don’t need additional computation
  • All training and inference processes obtain global metadata from MetaServer
  • Training and inference engines each perform shard-level metadata consistency and compatibility validation

(3) P2P Weight Transmission Execution Plan

After obtaining global weight metadata, Awex constructs a deterministic point-to-point transmission plan within each training and inference process.

Core Strategy (NCCL mode):

  • For each replica of the same tensor shard, assign training shards to inference shards through Round Robin to ensure uniform pulling;
  • For overlapping shard intervals, if perfectly aligned, directly map; otherwise, use two sends to different shards;
  • Pre-filter shards related to the current process to avoid constructing a global plan (shards can reach tens of millions for trillion-parameter models);
  • Ensure strict order consistency of NCCL send/recv;

RDMA is more flexible and uses a separate transmission plan, which won’t be covered in this article.

(4) NCCL Weight Transmission

Awex supports two transmission modes: NCCL (NVIDIA Collective Communications Library) and RDMA (Remote Direct Memory Access). NCCL mode is more user-friendly, while RDMA mode is more flexible with higher performance.

NCCL transmission mode primarily uses NCCL’s send/recv interface for weight transmission. There are some implementation differences in Awex for separated and co-located modes, which I will detail here.

NCCL Separated Weight Transmission

In separated transmission mode, Awex first constructs a joint training-inference NCCL Process Group for subsequent weight transmission from training to inference. Next, based on the NCCL send and transfer plan created during initialization, P2P peer-to-peer ordered weight sending and receiving is performed on each process of the training and inference engines. The overall workflow is as follows:

CUDA IPC Co-located Zero-Copy Weight Mapping

Since the rank count of a single NCCL communication group can only equal the number of GPU cards, and in the training-inference co-located case, the rank count is twice the number of GPU cards, a joint training-inference communication group cannot be directly established.

In this case, Awex uses CUDA IPC to zero-copy map the training process’s GPU memory to the inference process, establishes a global communication group for all inference processes, then uses this communication group for NCCL send/recv to complete weight exchange from training to inference engines:

In implementation, I also made some performance optimizations:

  • Problem: Each CUDA IPC Handle’s Open/Close has significant overhead; MOE and other models may have thousands to tens of thousands of weight tensors per card requiring IPC serialization;
  • Solution: Before IPC serialization, merge tensors by shape and dtype, reducing the count to dozens, greatly reducing CUDA IPC overhead;

(Note: CUDA IPC does not support CUDA virtual memory. Future plans include allocating additional physical memory space for weight merging and transmission when enabling virtual GPU memory in the training engine)

(5) RDMA Weight Transmission

Although NCCL transmission mode can already significantly improve weight exchange performance, NCCL mode has two main limitations:

  1. NCCL versions on training and inference sides need to remain compatible, otherwise NCCL transmission may hang, preventing independent updates and iterations of training and inference engines;
  2. NCCL’s static topology is not friendly to communication domain scaling, as continued RL training causes inference outputs to gradually grow and workload to increase, requiring scaling of inference instances. NCCL needs to destroy the entire communication group and rebuild;

Considering these two reasons, an RDMA-based transmission implementation has also been added to Awex.

The weights exchange process is similiar to NCCL. The main difference is that RDMA mode will copy gpu tensors to cpu-pinned memory, which is registered for RDMA access:

RDMA Mode Advantages:

  • Removes NCCL version binding, supports independent iteration of training and inference engines
  • More flexible transmission plan optimization space
  • Supports dynamic scaling of inference instances
  • Further performance improvement (1T model from 20 seconds to 6 seconds)

RDMA mode implementation will be open-sourced soon. Stay tuned.

Performance Benchmarks

On thousand-GPU scale clusters, Awex using NCCL transmission can exchange 10B-scale model weights within one second, and 1T-scale model weights within twenty seconds. Using RDMA for transmission, 1T model weight exchange time can be further reduced to 6 seconds.

Quick Start Get Started

Awex is a pure Python library that can be installed and used with one command, supporting Python 3.8 and above.

pip install awex

Megatron training engine weight sending example:

from awex import NCCLWeightsWriter
from awex.engine.mcore import MegatronEngine
# init
train_engine = MegatronEngine(awex_config, hf_config, mcore_model)
writer = NCCLWeightsWriter(train_engine)
writer.initialize()
# write weights
writer.write_weights(step_id=1)

SGLang inference engine weight update example:

from awex import WeightsReader
from awex.engine.sglang import SGLangEngine
import sglang as sgl

sgl_engine = sgl.Engine(model_path="xxx", tp_size=2, random_seed=42)
inference_engine = SGLangEngine(awex_confg, sgl_engine)
reader = WeightsReader(inference_engine)
reader.initialize()
# update weights
reader.update_weights(step_id=1)

Future Roadmap

Awex is one of the core components of our reinforcement learning system, which serves as the solid foundation for training Bailing trillion-parameter models. Ant Group will gradually open-source other core RL components of ASystem in the future to further improve the open-source reinforcement learning training ecosystem. Stay tuned!

The current open-source version of Awex supports Megatron and SGLang engines, with much work remaining to be done. We look forward to collaborating with the community to gradually expand support for more mainstream engines with the power of the community:

  • 🔧 Training engines we hope to support: DeepSpeed, FSDP, etc.
  • 🚀 Inference engines we hope to support: vLLM, TensorRT-LLM, etc.
  • 🤖 Model adaptation: Built-in out-of-the-box support for more mainstream models

We welcome every developer interested in reinforcement learning and large language models to use Awex, provide valuable feedback and suggestions, and work together to drive continuous innovation in reinforcement learning systems!

We also welcome you to follow the latest releases of Ant’s Bailing models:

About Me

Shawn Yang, author of the Awex framework and creator & PMC Chair of the Apache Fory serialization framework, Active open‑source contributor.

Experienced in distributed systems and high‑performance computing across streaming and batch engines, online machine learning systems, the Ray ecosystem, scientific computing, multimedia and multimodal processing, training–inference engines, and reinforcement learning systems. Currently focused on large‑scale LLM training, inference, and reinforcement learning system development.

]]> <![CDATA[Introducing Apache Fory Rust: A Versatile Serialization Framework for the Modern Age]]> https://medium.com/@shawn.ck.yang/introducing-apache-fory-rust-a-versatile-serialization-framework-for-the-modern-age-8cfb701f73bf?source=rss-c54c340fa1bb------2 https://medium.com/p/8cfb701f73bf Thu, 30 Oct 2025 17:03:34 GMT 2025-10-30T17:03:34.466Z TL;DR: Apache Fory Rust is a blazingly-fast, cross-language serialization framework that delivers ultra-fast serialization performance while automatically handling circular references, trait objects, and schema evolution. Built with Rust’s safety guarantees and zero-copy techniques, it’s designed for developers who refuse to compromise between performance and developer experience.

The Serialization Dilemma

Every backend engineer has faced this moment: your application needs to serialize complex data structures such as nested objects, circular references, polymorphic types, and you’re forced to choose between three bad options:

  1. Fast but fragile: Hand-rolled binary formats that break with schema changes
  2. Flexible but slow: JSON/Protocol with 10x performance overhead
  3. Complex and limiting: Existing solutions that don’t support your language’s advanced features

Apache Fory Rust eliminates this false choice. It’s a serialization framework that delivers exceptional performance while automatically handling the complexities of modern applications — no IDL files, no manual schema management, no compromises.

What Makes Apache Fory Rust Different?

1. Truly Cross-Language

Apache Fory Rust speaks the same binary protocol as Java, Python, C++, Go, and other language implementations. Serialize data in Rust, deserialize in Python — it just works. No schema files. No code generation. No version mismatches.

// Rust: Serialize
let user = User {
    name: "Alice".to_string(),
    age: 30,
    metadata: HashMap::from([("role", "admin")]),
};
let bytes = fory.serialize(&user);

// Python: Deserialize (same binary format!)
user = fory.deserialize(bytes)  # Just works!

This isn’t just convenient — it changes how we develop microservices architectures where different teams use different languages.

2. Automatic Shared/Circular Reference Handling

Most serialization frameworks panic when encountering circular references. Apache Fory tracks and preserves reference identity automatically:

Shared Reference:

use fory::Fory;
use std::rc::Rc;

let fory = Fory::default();

// Create a shared value
let shared = Rc::new(String::from("shared_value"));

// Reference it multiple times
let data = vec![shared.clone(), shared.clone(), shared.clone()];

// The shared value is serialized only once
let bytes = fory.serialize(&data);
let decoded: Vec<Rc<String>> = fory.deserialize(&bytes)?;

// Verify reference identity is preserved
assert_eq!(decoded.len(), 3);
assert_eq!(*decoded[0], "shared_value");

// All three Rc pointers point to the same object
assert!(Rc::ptr_eq(&decoded[0], &decoded[1]));
assert!(Rc::ptr_eq(&decoded[1], &decoded[2]));

Circular Reference:

use fory::{ForyObject, RcWeak};

#[derive(ForyObject)]
struct Node {
    value: i32,
    parent: RcWeak<RefCell<Node>>,     // Weak pointer breaks cycles
    children: Vec<Rc<RefCell<Node>>>,  // Strong references tracked
}

// Build a parent-child tree with circular references
let parent = Rc::new(RefCell::new(Node { ... }));
let child = Rc::new(RefCell::new(Node {
    parent: RcWeak::from(&parent),  // Points back to parent
    ...
}));
parent.borrow_mut().children.push(child.clone());

// Serialization handles the cycle automatically
let bytes = fory.serialize(&parent);
let decoded: Rc<RefCell<Node>> = fory.deserialize(&bytes)?;

// Reference relationships preserved!
assert!(Rc::ptr_eq(&decoded, &decoded.borrow().children[0].borrow().parent.upgrade().unwrap()));

This isn’t just a feature — it’s essential for graph databases, object-relational mappers, and domain models.

3. Trait Object Serialization

Rust’s trait system enables powerful abstractions, but serializing Box<dyn Trait> is notoriously difficult. Apache Fory makes it trivial:

use fory::{ForyObject, Serializer, register_trait_type};
trait Animal: Serializer {
    fn speak(&self) -> String;
}
#[derive(ForyObject)]
struct Dog { name: String, breed: String }
#[derive(ForyObject)]
struct Cat { name: String, color: String }
// Register implementations
register_trait_type!(Animal, Dog, Cat);
// Serialize heterogeneous collections
let animals: Vec<Box<dyn Animal>> = vec![
    Box::new(Dog { ... }),
    Box::new(Cat { ... }),
];
let bytes = fory.serialize(&animals);
let decoded: Vec<Box<dyn Animal>> = fory.deserialize(&bytes)?;
// Polymorphism preserved!
decoded[0].speak();  // "Woof!"
decoded[1].speak();  // "Meow!"

Alternative: Using dyn Any without trait registration:

use std::rc::Rc;
use std::any::Any;
// No trait definition or registration needed
let dog: Rc<dyn Any> = Rc::new(Dog { name: "Rex".to_string(), breed: "Labrador".to_string() });
let cat: Rc<dyn Any> = Rc::new(Cat { name: "Whiskers".to_string(), color: "Orange".to_string() });
let bytes = fory.serialize(&dog);
let decoded: Rc<dyn Any> = fory.deserialize(&bytes)?;
// Downcast to concrete type
let unwrapped = decoded.downcast_ref::<Dog>().unwrap();
assert_eq!(unwrapped.name, "Rex");

Supports:

  • Box<dyn Trait> - Owned trait objects
  • Rc<dyn Trait> / Arc<dyn Trait> - Reference-counted trait objects
  • Rc<dyn Any> / Arc<dyn Any> - Runtime type dispatch without traits
  • Auto-generated wrapper types for standalone serialization

This unlocks plugin systems, heterogeneous collections, and extensible architectures that were previously impossible to serialize.

4. Schema Evolution Without Breaking Changes

Microservices evolve independently. Apache Fory’s Compatible mode allows schema changes without coordination:

use fory::{Fory, ForyObject};
// Service A: Version 1
#[derive(ForyObject)]
struct User {
    name: String,
    age: i32,
    address: String,
}
let mut fory_v1 = Fory::default().compatible(true);
fory_v1.register::<User>(1);
// Service B: Version 2 (evolved independently)
#[derive(ForyObject)]
struct User {
    name: String,
    age: i32,
    // address removed
    phone: Option<String>,     // New field
    metadata: HashMap<String, String>,  // Another new field
}
let mut fory_v2 = Fory::default().compatible(true);
fory_v2.register::<User>(1);
// V1 data deserializes into V2 structure
let v1_bytes = fory_v1.serialize(&user_v1);
let user_v2: User = fory_v2.deserialize(&v1_bytes)?;
// Missing fields get default values automatically

Compatibility rules:

  • ✅ Add new fields (default values applied)
  • ✅ Remove fields (skipped during deserialization)
  • ✅ Reorder fields (matched by name)
  • ✅ Change nullability (T ↔ Option<T>)
  • ❌ Type changes (except nullable variants)

This is critical for zero-downtime deployments and polyglot microservices.

The Technical Foundation

Protocol Design

Apache Fory uses a sophisticated binary protocol designed for both performance and flexibility:

| fory header | reference meta | type meta | value data |

Key innovations:

  1. Efficient encoding: Variable-length integers, compact type IDs, bit-packed flags
  2. Reference tracking: Deduplicates shared objects automatically (serialize once, reference thereafter)
  3. Meta compression: Gzip compression for type metadata in meta-sharing mode
  4. Little-endian layout: Optimized for modern CPU architectures

Compile-Time Code Generation

Unlike reflection-based frameworks, Apache Fory generates serialization code at compile time via procedural macros:

use fory::ForyObject;
#[derive(ForyObject)]
struct Person {
    name: String,
    age: i32,
    address: Address,
}
// Macro generates:
// - fory_write_data() for serialization
// - fory_read_data() for deserialization
// - fory_reserved_space() for buffer pre-allocation
// - fory_get_type_id() for type registration

Benefits:

  • ⚡ Zero runtime overhead: No reflection, no vtable lookups
  • 🛡️ Type safety: Compile-time errors instead of runtime panics
  • 📦 Small binary size: Only code for types you actually use
  • 🔍 IDE support: Full autocomplete and error checking

Architecture

Apache Fory Rust consists of three focused crates:

fory/            # High-level API
  └─ Convenience wrappers, derive re-exports
fory-core/       # Core serialization engine
  ├─ fory.rs         # Main entry point
  ├─ buffer.rs       # Zero-copy binary I/O
  ├─ serializer/     # Type-specific serializers
  ├─ resolver/       # Type registration & dispatch
  ├─ meta/           # Meta string compression
  └─ row/            # Row format implementation
fory-derive/     # Procedural macros
  ├─ object/         # ForyObject derive macro
  └─ fory_row.rs    # ForyRow derive macro

This modular design ensures clean separation of concerns and makes the codebase maintainable.

Benchmarks: Real-World Performance

With same compression ratio as Protobuf, but 10x faster:

When to Use Apache Fory Rust

✅ Ideal Use Cases

1. Microservices with polyglot teams

  • Different services in different languages
  • Need seamless data exchange without schema files
  • Schema evolution across independent deployments

2. High-performance data pipelines

  • Processing millions of records per second
  • Memory-constrained environments (use row format)
  • Analytics workloads with selective field access

3. Complex domain models

  • Circular references (parent-child relationships, graphs)
  • Polymorphic types (trait objects, inheritance hierarchies)
  • Rich object graphs with shared references

4. Real-time systems

  • Low-latency requirements (<1ms serialization)
  • Memory-mapped file access
  • Zero-copy deserialization critical

⚠️ Consider Alternatives If

  1. You need human-readable data: Use JSON/YAML for debugging
  2. You need long-term storage format: Use Parquet for data lakes
  3. Your data is trivial: serde + bincode is simpler for basic types

Getting Started in 5 Minutes

Installation

Add to Cargo.toml:

[dependencies]
fory = "0.13"

Basic Object Serialization

use fory::{Fory, Error, ForyObject};
#[derive(ForyObject, Debug, PartialEq)]
struct User {
    name: String,
    age: i32,
    email: String,
}
fn main() -> Result<(), Error> {
    let mut fory = Fory::default();
    fory.register::<User>(1);  // Register with unique ID
    let user = User {
        name: "Alice".to_string(),
        age: 30,
        email: "alice@example.com".to_string(),
    };
    // Serialize
    let bytes = fory.serialize(&user);
    // Deserialize
    let decoded: User = fory.deserialize(&bytes)?;
    assert_eq!(user, decoded);
    Ok(())
}

Cross-Language Serialization

use fory::Fory;
// Enable cross-language mode
let mut fory = Fory::default().compatible(true).xlang(true);
// Register with id/namespace for cross-language compatibility
fory.register_by_namespace::<User>(1);
// fory.register_by_namespace::<User>("example", "User");
let bytes = fory.serialize(&user);
// This can now be deserialized in Java, Python, Go, etc.

Register types with consistent IDs or names across all languages:

  • By ID (fory.register::<User>(1)): Faster serialization, more compact encoding, but requires coordination to avoid ID conflicts
  • By name (fory.register_by_name::<User>("example.User")): More flexible, less prone to conflicts, easier to manage across teams, but slightly larger encoding

Supported Types

Apache Fory Rust supports a comprehensive type system:

Primitives: bool, i8, i16, i32, i64, f32, f64, String

Collections: Vec<T>, HashMap<K,V>, BTreeMap<K,V>, HashSet<T>, Option<T>

Smart Pointers: Box<T>, Rc<T>, Arc<T>, RcWeak<T>, ArcWeak<T>, RefCell<T>, Mutex<T>

Date/Time: chrono::NaiveDate, chrono::NaiveDateTime

Custom Types: Derive ForyObject for object graphs, ForyRow for row format

Trait Objects: Box<dyn T>, Rc<dyn T>, Arc<dyn T>, Rc<dyn Any>, Arc<dyn Any>

Roadmap: What’s Next

Apache Fory Rust is production-ready today, but we’re just getting started and continuing active development:

✅ Shipped in v0.13

  • ✅ Static codegen via procedural macros
  • ✅ Row format serialization with zero-copy
  • ✅ Cross-language object graph serialization
  • ✅ Shared and circular reference tracking
  • ✅ Weak pointer support (RcWeak, ArcWeak)
  • ✅ Trait object serialization (Box/Rc/Arc)
  • ✅ Schema evolution in compatible mode

🚧 Coming Soon

  • Cross-language reference serialization: serialize Rc/Arc to/from other languages.
  • Partial row updates: Mutate row format in-place

🎯 Help Wanted

We’re actively seeking contributors for:

  • Performance tuning: Profile and optimize hot paths
  • Documentation: More examples, tutorials, and guides
  • Testing: Fuzzing, property tests, edge case coverage

Production Considerations

Thread Safety

Fory becomes fully thread-safe after registration is complete. Once every type is registered (which requires &mut Fory), wrap the instance in an Arc and freely share it across worker threads for concurrent serialization and deserialization.

use fory::Fory;
use std::{sync::Arc, thread};
let mut fory = Fory::default();
fory.register::<Item>(1)?;
let fory = Arc::new(fory); // `Fory` is Send + Sync once registration is done
let item = Item::default();
let handles: Vec<_> = (0..4)
    .map(|_| {
        let fory = Arc::clone(&fory);
        let input = item.clone();
        thread::spawn(move || {
            let bytes = fory.serialize(&input);
            let decoded: Item = fory.deserialize(&bytes).expect("valid data");
            (bytes, decoded)
        })
    })
    .collect();
for handle in handles {
    let (bytes, decoded) = handle.join().expect("thread finished");
    // work with `bytes` / `decoded`
}

Error Handling

Apache Fory uses Result<T, Error> for all fallible operations:

use fory::Error;
match fory.deserialize::<User>(&bytes) {
    Ok(user) => process_user(user),
    Err(Error::TypeMismatch) => log::error!("Schema mismatch"),
    Err(Error::BufferTooShort) => log::error!("Incomplete data"),
    Err(e) => log::error!("Deserialization failed: {}", e),
}

Documentation

Community and Contribution

Apache Fory is an Apache Software Foundation project with a vibrant, growing community:

How to Contribute

We welcome contributions of all kinds:

  1. Code: Implement features from the roadmap
  2. Docs: Write tutorials, examples, and guides
  3. Testing: Add benchmarks, fuzz tests, integration tests
  4. Feedback: Report bugs, request features, share use cases

See CONTRIBUTING.md for guidelines.

License

Apache Fory is licensed under the Apache License 2.0, a permissive open-source license that allows commercial use, modification, and distribution.

Conclusion

Apache Fory Rust represents a paradigm shift in serialization:

  • No more trade-offs: Get performance and flexibility
  • No more boilerplate: Derive macros handle the complexity
  • No more lock-in: Trait-object and shared reference support by nature

Whether you’re building microservices, data pipelines, or real-time systems, Apache Fory Rust delivers the performance you need with the ergonomics you deserve.

Try it today:

cargo add fory

Join the community:

git clone https://github.com/apache/fory.git
cd fory/rust
cargo test --features tests

Share your experience:

  • Write a blog post about your use case
  • Present at your local Rust meetup
  • Contribute benchmarks from your domain
]]> <![CDATA[Apache Fury Serialization 0.8.0 released]]> https://medium.com/@shawn.ck.yang/apache-fury-serialization-0-8-0-released-9781362a5356?source=rss-c54c340fa1bb------2 https://medium.com/p/9781362a5356 Tue, 08 Oct 2024 16:31:31 GMT 2024-10-08T16:31:31.721Z The Apache Fury team is pleased to announce the 0.8.0 release. This is a major release that includes 23 PR from 7 distinct contributors. See the Install Page to learn how to get the libraries for your platform.

Highlights​

  • Support graalvm 17/21/22 native image
  • Release fury optimized serializers for scala collection
  • Reduce scala collection classname serialization cost using dict encoding

Features​

Bug Fix​

Other Improvements​

New Contributors​

Full Changelog: https://github.com/apache/fury/compare/v0.7.1...v0.8.0

Acknowledgements​

Thanks @@jiacai2050 @fink-arthur @sh-cho @pjfanning @chaokunyang @yoohaemin

A big thank you to all our contributors who have worked hard on this release. Your contributions, whether through code, documentation, or issue reporting, are really appreciated.

]]> <![CDATA[Apache Fury v0.7.1 Released]]> https://medium.com/@shawn.ck.yang/apache-fury-v0-7-1-released-fb89939a9233?source=rss-c54c340fa1bb------2 https://medium.com/p/fb89939a9233 Fri, 13 Sep 2024 16:50:37 GMT 2024-09-13T16:50:37.668Z The Apache Fury team is pleased to announce the 0.7.1 release. This is a major release that includes 20 PR from 8 distinct contributors. See the Install Page to learn how to get the libraries for your platform.

Features​

Bug Fix​

Other Improvements​

New Contributors​

Full Changelog: https://github.com/apache/fury/compare/v0.7.0...v0.7.1

Acknowledgements​

Thanks @jiacai2050 @chaokunyang @theweipeng @funky-eyes @Forchapeatl @zhaommmmomo @yuluo-yx @LiangliangSui @LofiSu

A big thank you to all our contributors who have worked hard on this release. Your contributions, whether through code, documentation, or issue reporting, are really appreciated.

]]> <![CDATA[Apache Fury 0.7.0 released: fast object deep cop]]> https://medium.com/@shawn.ck.yang/apache-fury-0-7-0-released-fast-object-deep-cop-bc4d6dcd3005?source=rss-c54c340fa1bb------2 https://medium.com/p/bc4d6dcd3005 Mon, 05 Aug 2024 11:20:09 GMT 2024-08-05T11:20:09.161Z Apache Fury 0.7.0 released: fast object deep copy support

The Apache Fury team is pleased to announce the 0.6.0 release. This is a major release that includes 24 PR from 7 distinct contributors. See the Install Page to learn how to get the libraries for your platform.

High Light​

Experimental​

Implement fast object deep copy framework for java:

Fury fury = Fury.builder().withRefCopy(true).build();
fury.register(SomeClass.class);
SomeClass a = xxx;
SomeClass copied = fury.copy(a);
| Benchmark                     | objectType    | Score         | Error         | Units |
|-------------------------------|---------------|---------------|---------------|-------|
| fury_copy                     | MEDIA_CONTENT | 1243297.690   | ±  451828.452 | ops/s |
| fury_copy                     | SAMPLE        | 2670545.816   | ± 1378536.021 | ops/s |
| fury_copy                     | STRUCT        | 2673356.422   | ±  202288.322 | ops/s |
| fury_copy                     | STRUCT2       | 1943587.774   | ±  392513.707 | ops/s |
| fury_copy_int_map             | int map       | 1470264.733   | ± 1021875.257 | ops/s |
| fury_copy_list                | int list      | 3556892.276   | ±  127410.724 | ops/s |
| fury_copy_object_array        | array         | 4430589.112   | ±   25366.893 | ops/s |
| fury_copy_string_map          | string map    | 1736145.327   | ±  377806.877 | ops/s |
| kryo_copy                     | MEDIA_CONTENT | 804208.092    | ±   27429.069 | ops/s |
| kryo_copy                     | SAMPLE        | 717669.608    | ±   71093.370 | ops/s |
| kryo_copy                     | STRUCT        | 1076048.642   | ±  223194.146 | ops/s |
| kryo_copy                     | STRUCT2       | 141374.767    | ±   14150.535 | ops/s |
| kryo_copy_int_map             | int map       | 546203.187    | ±   54669.173 | ops/s |
| kryo_copy_list                | int list      | 843643.496    | ±  312306.921 | ops/s |
| kryo_copy_object_array        | object array  | 1593267.344   | ± 1721824.436 | ops/s |
| kryo_copy_string_map          | string map    | 574809.875    | ±   47316.340 | ops/s |

Bug Fix​

Other Improvements​

New Contributors​

Full Changelog: https://github.com/apache/fury/compare/v0.6.0...v0.7.0

Acknowledgements​

Thanks @komamitsu @pjfanning @chaokunyang @weijiang157152688 @kitty-eu-org @urlyy @zhaommmmomo A big thank you to all our contributors who have worked hard on this release. Your contributions, whether through code, documentation, or issue reporting, are really appreciated.

Full Changelog: https://github.com/apache/fury/compare/v0.6.0...v0.7.0

]]> <![CDATA[Apache Fury 0.6.0 Released: 4x faster and 1/2 smaller than Protobuf]]> https://medium.com/@shawn.ck.yang/apache-fury-0-6-0-released-4x-faster-and-1-2-smaller-than-protobuf-24f470b27513?source=rss-c54c340fa1bb------2 https://medium.com/p/24f470b27513 Wed, 24 Jul 2024 12:48:06 GMT 2024-07-24T12:48:06.891Z The Apache Fury team is pleased to announce the 0.6.0 release. This is a major release that includes 35 PR from 12 distinct contributors. See the Install Page to learn how to get the libraries for your platform.

High light​

In this release, we introduced a scoped meta share mode for schema evolution in java and enabled it by default when CompatibleMode is set to Compatible:

  • This mode is 50% faster than previous KV compatible mode, and only 1/6 size of serialized payload than before.
  • It’s 4x faster than protobuf, less than 1/2 serialized size of protobuf for complex object.

Protobuf/JSON will write message fields meta and values in a KV layout, so when serializzing a list of message, they will have two issues:

  • Write meta multiple times even those message are the same type.
  • KV layout is dispersive, which is not friendly for compression.

The meta share mode will write field name&type meta of a struct only once for multiple objects of same type, which will save space and improve performance comparedto protobuf.

With meta share, we can write field name&type meta of a struct only once for multiple objects of same type, which will save space and improve performance comparedto protobuf. And we can also encode the meta into binary in advance, and use one memory copy to write it which will be much faster.

Serialize data​

  public static class NumericStruct {
    public int f1;
    public int f2;
    public int f3;
    public int f4;
    public int f5;
    public int f6;
    public int f7;
    public int f8;

    public static NumericStruct build() {
      NumericStruct struct = new NumericStruct();
      struct.f1 = 1;
      struct.f2 = 2;
      struct.f3 = 3;
      struct.f4 = 4;
      struct.f5 = 5;
      struct.f6 = 6;
      struct.f7 = 7;
      struct.f8 = 8;
      return struct;
    }
  }

  public static class NumericStructList {
    public List<NumericStruct> list;

    public static NumericStructList build() {
      NumericStructList structList = new NumericStructList();
      structList.list = new ArrayList<>(1000);
      for (int i = 0; i < 1000; i++) {
        structList.list.add(NumericStruct.build());
      }
      return structList;
    }
}

Performance:

Benchmark                       Mode  Cnt      Score      Error  Units
fury_deserialize                thrpt   30  49667.900 ± 3004.061  ops/s
fury_kv_compatible_deserialize  thrpt   30  33014.595 ± 3716.199  ops/s
fury_kv_compatible_serialize    thrpt   30  23915.260 ± 3968.119  ops/s
fury_serialize                  thrpt   30  63146.826 ± 2930.505  ops/s
protobuf_deserialize            thrpt   30  14156.610 ±  685.272  ops/s
protobuf_serialize              thrpt   30  10060.293 ±  706.064  ops/s

Size:

Feature​

Bug Fix​

Others​

New Contributors​

Full Changelog: https://github.com/apache/fury/compare/v0.5.1...v0.6.0

]]>