This is an automated email from the ASF dual-hosted git repository. chaokunyang pushed a commit to branch remvoe_parts_of_emojis in repository https://gitbox.apache.org/repos/asf/fory-site.git
commit cb7a12b595e85ff2bf642f77c8d5b4cb493dca8f Author: chaokunyang <[email protected]> AuthorDate: Tue Mar 24 13:51:02 2026 +0800 update docs --- docs/introduction/features.md | 80 +++----- docs/introduction/overview.md | 46 ++--- .../current/introduction/benchmark.md | 56 +++--- .../current/introduction/features.md | 223 +++++++++++++++++++-- .../current/introduction/overview.md | 47 ++--- .../version-0.16/introduction/benchmark.md | 56 +++--- .../version-0.16/introduction/features.md | 223 +++++++++++++++++++-- .../version-0.16/introduction/overview.md | 47 ++--- .../version-0.16/introduction/features.md | 80 +++----- .../version-0.16/introduction/overview.md | 46 ++--- 10 files changed, 630 insertions(+), 274 deletions(-) diff --git a/docs/introduction/features.md b/docs/introduction/features.md index 27d736ac31..1651d47036 100644 --- a/docs/introduction/features.md +++ b/docs/introduction/features.md @@ -6,7 +6,7 @@ sidebar_position: 2 ## Core Capabilities -### 🚀 High-Performance Serialization +### High-Performance Serialization Apache Fory™ delivers exceptional performance through advanced optimization techniques: @@ -16,7 +16,7 @@ Apache Fory™ delivers exceptional performance through advanced optimization te - **Intelligent Encoding**: Variable-length compression for integers and strings; SIMD acceleration for arrays (Java 16+) - **Meta Sharing**: Class metadata packing reduces redundant type information across serializations -### 🌍 Cross-Language Serialization +### Cross-Language Serialization The **[xlang serialization format](../specification/xlang_serialization_spec.md)** enables seamless data exchange across programming languages: @@ -26,7 +26,7 @@ The **[xlang serialization format](../specification/xlang_serialization_spec.md) - **Schema Evolution**: Optional forward/backward compatibility for evolving schemas - **Automatic Serialization**: No IDL or schema definitions required; serialize any object directly without code generation -### 📊 Row Format +### Row Format A cache-friendly **[row format](../specification/row_format_spec.md)** optimized for analytics workloads: @@ -35,7 +35,7 @@ A cache-friendly **[row format](../specification/row_format_spec.md)** optimized - **Apache Arrow Integration**: Seamless conversion to columnar format for analytics pipelines - **Multi-Language**: Available in Java, Python, Rust and C++ -### 🔒 Security & Production-Readiness +### Security & Production-Readiness Enterprise-grade security and compatibility: @@ -46,7 +46,7 @@ Enterprise-grade security and compatibility: ## Java Features -### 🚀 High Performance +### High Performance - **JIT Code Generation**: Highly-extensible JIT framework generates serializer code at runtime using async multi-threaded compilation, delivering 20-170x speedup through: - Inlining variables to reduce memory access @@ -58,13 +58,13 @@ Enterprise-grade security and compatibility: - **Meta Sharing**: Cached class metadata reduces redundant type information - **SIMD Acceleration**: Java Vector API support for array operations (Java 16+) -### 🔧 Drop-in Replacement +### Drop-in Replacement - **100% JDK Serialization Compatible**: Supports `writeObject`/`readObject`/`writeReplace`/`readResolve`/`readObjectNoData`/`Externalizable` - **Java 8-24 Support**: Works across all modern Java versions including Java 17+ records - **GraalVM Native Image**: AOT compilation support without reflection configuration -### 🔄 Advanced Features +### Advanced Features - **Reference Tracking**: Automatic handling of shared and circular references - **Schema Evolution**: Forward/backward compatibility for class schema changes @@ -74,45 +74,45 @@ Enterprise-grade security and compatibility: ## Python Features -### 🔧 **Flexible Serialization Modes** +### **Flexible Serialization Modes** - **Python native Mode**: Full Python compatibility, drop-in replacement for pickle/cloudpickle - **Cross-Language Mode**: Optimized for multi-language data exchange - **Row Format**: Zero-copy row format for analytics workloads -### 🎯 Versatile Serialization Features +### Versatile Serialization Features - **Shared/circular reference support** for complex object graphs in both Python-native and cross-language modes - **Polymorphism support** for customized types with automatic type dispatching - **Schema evolution** support for backward/forward compatibility when using dataclasses in cross-language mode - **Out-of-band buffer support** for zero-copy serialization of large data structures like NumPy arrays and Pandas DataFrames, compatible with pickle protocol 5 -### ⚡ **Blazing Fast Performance** +### **Blazing Fast Performance** - **Extremely fast performance** compared to other serialization frameworks - **Runtime code generation** and **Cython-accelerated** core implementation for optimal performance -### 📦 Compact Data Size +### Compact Data Size - **Compact object graph protocol** with minimal space overhead—up to 3× size reduction compared to pickle/cloudpickle - **Meta packing and sharing** to minimize type forward/backward compatibility space overhead -### 🛡️ **Security & Safety** +### **Security & Safety** - **Strict mode** prevents deserialization of untrusted types by type registration and checks. - **Reference tracking** for handling circular references safely ## Rust Features -### 🚀 Why Apache Fory™ Rust? +### Why Apache Fory™ Rust? -- **🔥 Blazingly Fast**: Zero-copy deserialization and optimized binary protocols -- **🌍 Cross-Language**: Seamlessly serialize/deserialize data across Java, Python, C++, Go, JavaScript, and Rust -- **🎯 Type-Safe**: Compile-time type checking with derive macros -- **🔄 Circular References**: Automatic tracking of shared and circular references with `Rc`/`Arc` and weak pointers -- **🧬 Polymorphic**: Serialize trait objects with `Box<dyn Trait>`, `Rc<dyn Trait>`, and `Arc<dyn Trait>` -- **📦 Schema Evolution**: Compatible mode for independent schema changes -- **⚡ Two Modes**: Object graph serialization and zero-copy row-based format +- **Blazingly Fast**: Zero-copy deserialization and optimized binary protocols +- **Cross-Language**: Seamlessly serialize/deserialize data across Java, Python, C++, Go, JavaScript, and Rust +- **Type-Safe**: Compile-time type checking with derive macros +- **Circular References**: Automatic tracking of shared and circular references with `Rc`/`Arc` and weak pointers +- **Polymorphic**: Serialize trait objects with `Box<dyn Trait>`, `Rc<dyn Trait>`, and `Arc<dyn Trait>` +- **Schema Evolution**: Compatible mode for independent schema changes +- **Two Modes**: Object graph serialization and zero-copy row-based format ### Object Graph Serialization @@ -193,38 +193,18 @@ When a Scala class has default parameters, the Scala compiler generates methods ## Kotlin Features +Kotlin support builds on the default Fory Java implementation and adds handling for Kotlin-specific types and schema evolution. + ### Supported Types -- primitives: `Byte`, `Boolean`, `Int`, `Short`, `Long`, `Char`, `Float`, `Double`, `UByte`, `UShort`, `UInt`, `ULong`. -- `Byte`, `Boolean`, `Int`, `Short`, `Long`, `Char`, `Float`, `Double` works out of the box with the default fory java implementation. -- stdlib `collection`: `ArrayDeque`, `ArrayList`, `HashMap`,`HashSet`, `LinkedHashSet`, `LinkedHashMap`. -- `ArrayList`, `HashMap`,`HashSet`, `LinkedHashSet`, `LinkedHashMap` works out of the box with the default fory java implementation. -- `String` works out of the box with the default fory java implementation. -- arrays: `Array`, `BooleanArray`, `ByteArray`, `CharArray`, `DoubleArray`, `FloatArray`, `IntArray`, `LongArray`, `ShortArray` -- all standard array types work out of the box with the default fory java implementation. -- unsigned arrays: `UByteArray`, `UShortArray`, `UIntArray`, `ULongArray` -- from stdlib: `Pair`, `Triple`, `Result` -- kotlin.random: `Random` -- kotlin.ranges: `CharRange`, `CharProgression`, `IntRange`, `IntProgression`, `LongRange`, `LongProgression`, `UintRange`, `UintProgression`, `ULongRange`, `ULongProgression` -- kotlin.text: `Regex` -- kotlin.time: `Duration` -- kotlin.uuid: `Uuid` - -Additional support is added for the following classes in kotlin: - -- Unsigned primitives: `UByte`, `UShort`, `UInt`, `ULong` -- Unsigned array types: `UByteArray`, `UShortArray`, `UIntArray`, `ULongArray` -- Empty collections: `emptyList`, `emptyMap`, `emptySet` -- Collections: `ArrayDeque` -- kotlin.time: `Duration` -- kotlin.uuid: `Uuid` +- Primitive types: `Byte`, `Boolean`, `Int`, `Short`, `Long`, `Char`, `Float`, `Double` +- Unsigned types: `UByte`, `UShort`, `UInt`, `ULong` +- Strings, standard arrays, and standard collections through the default Java implementation +- Kotlin collections and arrays such as `ArrayDeque`, `Array`, `BooleanArray`, `ByteArray`, `IntArray`, `LongArray`, `UByteArray`, `UIntArray`, and `ULongArray` +- Common stdlib types including `Pair`, `Triple`, `Result`, `Regex`, `Random`, `Duration`, and `Uuid` +- Kotlin ranges and progressions such as `CharRange`, `IntRange`, `LongRange`, `UIntRange`, `ULongRange`, and related progression types +- Empty collections such as `emptyList`, `emptyMap`, and `emptySet` ### Data Class Default Value Support -Apache Fory™ Kotlin provides support for Kotlin data class default values during serialization and deserialization. This feature allows for backward and forward compatibility when data class schemas evolve. - -When a Kotlin data class has parameters with default values, Apache Fory™ can: - -1. **Detect default values** using Kotlin reflection -2. **Apply default values** during deserialization when fields are missing from serialized data -3. **Support schema evolution** by allowing new fields with defaults to be added without breaking existing serialized data +In compatible mode, Fory can detect Kotlin data class default values and apply them during deserialization when fields are missing. This allows schemas to evolve more safely, for example when adding new fields with defaults. diff --git a/docs/introduction/overview.md b/docs/introduction/overview.md index ae0341c6bd..a1e86f49a7 100644 --- a/docs/introduction/overview.md +++ b/docs/introduction/overview.md @@ -59,7 +59,7 @@ print(decoded) # User(name='Alice', age=30) ## Key Features -### 🚀 High-Performance Serialization +### High-Performance Serialization Apache Fory™ delivers exceptional performance through advanced optimization techniques: @@ -69,7 +69,7 @@ Apache Fory™ delivers exceptional performance through advanced optimization te - **Intelligent Encoding**: Variable-length compression for integers and strings; SIMD acceleration for arrays (Java 16+) - **Meta Sharing**: Class metadata packing reduces redundant type information across serializations -### 🔄 Cross-Language Serialization +### Cross-Language Serialization The **[xlang serialization format](../specification/xlang_serialization_spec.md)** enables seamless data exchange across programming languages: @@ -79,7 +79,7 @@ The **[xlang serialization format](../specification/xlang_serialization_spec.md) - **Schema Evolution**: Optional forward/backward compatibility for evolving schemas - **Automatic Serialization**: No IDL or schema definitions required; serialize any object directly without code generation -### 📊 Row Format +### Row Format A cache-friendly **[row format](../specification/row_format_spec.md)** optimized for analytics workloads: @@ -88,7 +88,7 @@ A cache-friendly **[row format](../specification/row_format_spec.md)** optimized - **Apache Arrow Integration**: Seamless conversion to columnar format for analytics pipelines - **Multi-Language**: Available in Java, Python, Rust and C++ -### 🔒 Security & Production-Readiness +### Security & Production-Readiness Enterprise-grade security and compatibility: @@ -116,24 +116,24 @@ All protocols share the same optimized codebase, allowing improvements in one pr | Guide | Description | Source | Website | | -------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------- | -| **Java Serialization** | Comprehensive guide for Java serialization | [Java Guide](https://github.com/apache/fory/blob/main/docs/guide/java/) | [📖 View](../guide/java) | -| **Cross-Language Serialization** | Multi-language object exchange | [Xlang Guide](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [📖 View](../guide/xlang) | -| **Row Format** | Zero-copy random access format | [Java Row Format](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [📖 View](../guide/java/row-format.md) | -| **Python** | Python-specific features and usage | [Python Guide](https://github.com/apache/fory/blob/main/docs/guide/python/) | [📖 View](../guide/python) | -| **Rust** | Rust implementation and patterns | [Rust Guide](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [📖 View](../guide/rust) | -| **Go** | Go implementation and usage | [Go Guide](https://github.com/apache/fory/blob/main/docs/guide/go/) | [📖 View](../guide/go) | -| **Scala** | Scala integration and best practices | [Scala Guide](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [📖 View](../guide/scala) | -| **GraalVM** | Native image support and AOT compilation | [GraalVM Guide](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [📖 View](../guide/graalvm_guide.md) | -| **Development** | Building and contributing to Fory | [Development](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [📖 View](../guide/DEVELOPMENT) | +| **Java Serialization** | Comprehensive guide for Java serialization | [Java Guide](https://github.com/apache/fory/blob/main/docs/guide/java/) | [View](../guide/java) | +| **Cross-Language Serialization** | Multi-language object exchange | [Xlang Guide](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [View](../guide/xlang) | +| **Row Format** | Zero-copy random access format | [Java Row Format](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [View](../guide/java/row-format.md) | +| **Python** | Python-specific features and usage | [Python Guide](https://github.com/apache/fory/blob/main/docs/guide/python/) | [View](../guide/python) | +| **Rust** | Rust implementation and patterns | [Rust Guide](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [View](../guide/rust) | +| **Go** | Go implementation and usage | [Go Guide](https://github.com/apache/fory/blob/main/docs/guide/go/) | [View](../guide/go) | +| **Scala** | Scala integration and best practices | [Scala Guide](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [View](../guide/scala) | +| **GraalVM** | Native image support and AOT compilation | [GraalVM Guide](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [View](../guide/graalvm_guide.md) | +| **Development** | Building and contributing to Fory | [Development](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [View](../guide/DEVELOPMENT) | ### Protocol Specifications | Specification | Description | Source | Website | | ----------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| **Xlang Serialization** | Cross-language binary protocol | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [📖 View](../specification/xlang_serialization_spec.md) | -| **Java Serialization** | Java-optimized protocol | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [📖 View](../specification/java_serialization_spec.md) | -| **Row Format** | Row-based binary format | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [📖 View](../specification/row_format_spec.md) | -| **Type Mapping** | Cross-language type conversion | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [📖 View](../specification/xlang_type_mapping.md) | +| **Xlang Serialization** | Cross-language binary protocol | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [View](../specification/xlang_serialization_spec.md) | +| **Java Serialization** | Java-optimized protocol | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [View](../specification/java_serialization_spec.md) | +| **Row Format** | Row-based binary format | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [View](../specification/row_format_spec.md) | +| **Type Mapping** | Cross-language type conversion | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [View](../specification/xlang_type_mapping.md) | ## Compatibility @@ -190,11 +190,11 @@ We welcome contributions! Please read our [Contributing Guide](https://github.co **Ways to Contribute**: -- 🐛 Report bugs and issues -- 💡 Propose new features -- 📝 Improve documentation -- 🔧 Submit pull requests -- 🧪 Add test cases -- 📊 Share benchmarks +- Report bugs and issues +- Propose new features +- Improve documentation +- Submit pull requests +- Add test cases +- Share benchmarks See [Development Guide](../guide/DEVELOPMENT.md) for build instructions and development workflow. diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/benchmark.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/benchmark.md index 568bd14fc0..fc67c0ac41 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/benchmark.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/benchmark.md @@ -1,26 +1,24 @@ --- id: benchmark title: 性能测试 -sidebar_position: 2 +sidebar_position: 3 --- -不同的序列化框架适用于不同的场景，此处的性能测试结果仅供参考。 - -如果您需要针对特定场景进行性能测试，请确保所有序列化框架都针对该场景进行了适当配置。 - -动态序列化框架支持多态和引用，与静态序列化框架相比会有更多开销，除非像 Apache Fory™ 那样使用 JIT 技术。 -由于 Apache Fory™ 会在运行时生成代码，因此在收集性能测试统计数据之前请进行预热。 +> **说明**：不同的序列化框架在不同场景下各有优势。性能测试结果仅供参考。 +> 对于你的具体使用场景，请使用合适的配置和工作负载自行进行基准测试。 ## Java 性能测试 -Java 部分已切换为 `docs/benchmarks/java` 中的最新性能测试图。图表现在按以下维度分组： +Java 性能测试部分使用 `docs/benchmarks/java` 中的当前基准套件，对 Fory 与常见 Java 序列化框架进行对比。 -- **Heap**：序列化到堆上 `byte[]` 缓冲区 +图表按以下维度分组： + +- **Heap**：序列化到堆上的 `byte[]` 缓冲区 - **Off-heap**：序列化到 direct/off-heap 缓冲区 -- **Compatible**：启用前向/后向兼容的 Schema 演进模式 -- **Consistent**：要求读写两端 Schema 完全一致的模式 +- **Compatible**：启用向前和向后兼容的 Schema 演进模式 +- **Consistent**：要求通信双方 Schema 完全一致的 Schema 一致模式 -**测试数据类型**： +**测试类**： - `Struct`：包含 [100 个基础类型字段](https://github.com/apache/fory/tree/main/docs/benchmarks#Struct) 的类 - `MediaContent`：来自 [jvm-serializers](https://github.com/eishay/jvm-serializers/blob/master/tpc/src/data/media/MediaContent.java) 的类 @@ -66,7 +64,7 @@ Consistent 模式： <img width="90%" alt="" src="/img/benchmarks/deserialization/bench_deserialize_STRUCT_from_directBuffer_tps.png" /> -### 仓库基准汇总 +### 仓库吞吐汇总 序列化吞吐： @@ -86,46 +84,56 @@ Consistent 模式： <img width="90%" alt="" src="/img/benchmarks/zerocopy/zero_copy_bench_deserialize_BUFFER_from_array_tps.png" /> -注意：Apache Fory™ 依赖运行时代码生成，进行性能测试前必须充分预热。 +**重要说明**：Fory 的运行时代码生成依赖充分预热后才能进行准确的性能测量。 -更多说明、原始数据和完整 Java benchmark README 请参见 [Java Benchmarks](https://github.com/apache/fory/tree/main/docs/benchmarks/java)。 +更多性能测试说明、原始数据和完整 Java benchmark README 请参见 [Java Benchmarks](https://github.com/apache/fory/tree/main/docs/benchmarks/java)。 ## Rust 性能测试 +Fory Rust 相比其他 Rust 序列化框架展现出有竞争力的性能。 + <img src="/img/benchmarks/rust/company.png" width="90%"/> <img src="/img/benchmarks/rust/ecommerce_data.png" width="90%"/> <img src="/img/benchmarks/rust/system_data.png" width="90%"/> -注意：结果取决于硬件、数据集和实现版本。有关如何自行运行性能测试的信息，请参阅 Fory Rust Benchmark 指南：https://github.com/apache/fory/blob/main/benchmarks/rust_benchmark/README.md +注意：结果取决于硬件、数据集和实现版本。关于如何自行运行性能测试，请参见 Rust 指南：https://github.com/apache/fory/blob/main/benchmarks/rust_benchmark/README.md ## C++ 性能测试 -Fory C++ 在性能方面相较 Protobuf C++ 序列化框架具有竞争力。 +Fory C++ 相比 Protobuf C++ 序列化框架展现出有竞争力的性能。 <img src="/img/benchmarks/cpp/throughput.png" width="90%"/> ## Go 性能测试 -Fory Go 在单对象和列表两类工作负载下，相较 Protobuf 与 Msgpack 展现出较强的性能表现。 +Fory Go 在单对象和列表两类工作负载下，相比 Protobuf 和 Msgpack 展现出较强的性能表现。 <img src="/img/blog/fory_0_16_0_release/go_benchmark_combined.png" width="90%"/> 注意：结果取决于硬件、数据集和实现版本。详细信息请参见 Go 性能测试报告：https://fory.apache.org/docs/benchmarks/go/ -## Python 性能测试 +## C\# 性能测试 + +Fory C\# 在强类型对象的序列化和反序列化工作负载下，相比 Protobuf 和 Msgpack 展现出较强的性能表现。 + +<img src="/img/blog/fory_0_16_0_release/csharp_benchmark_combined.png" width="90%"/> + +注意：结果取决于硬件和运行时版本。详细信息请参见 C\# 性能测试报告：https://fory.apache.org/docs/benchmarks/csharp/ + +## Swift 性能测试 -Fory Python 在单对象和列表两类工作负载下，相较 `pickle` 与 Protobuf 展现出较强的性能表现。 +Fory Swift 在标量对象和列表两类工作负载下，相比 Protobuf 和 Msgpack 展现出较强的性能表现。 -<img src="/img/benchmarks/python/throughput.png" width="90%"/> +<img src="/img/blog/fory_0_16_0_release/swift_benchmark_combined.png" width="90%"/> -注意：结果取决于硬件、数据集、Python 运行时和实现版本。详细信息请参见 Python 性能测试报告：https://fory.apache.org/docs/benchmarks/python/ +注意：结果取决于硬件和运行时版本。详细信息请参见 Swift 性能测试报告：https://fory.apache.org/docs/benchmarks/swift/ ## JavaScript 性能测试 -<img width="33%" alt="" src="/img/benchmarks/javascript/complex_object.jpg" /> +<img width="50%" alt="" src="/img/benchmarks/javascript/complex_object.jpg" /> -此柱状图使用的数据包含一个具有多种字段类型的复杂对象，JSON 数据大小为 3KB。 +该柱状图使用的数据包含一个具有多种字段类型的复杂对象，JSON 数据大小为 3KB。 性能测试代码请参见 [benchmarks](https://github.com/apache/fory/blob/main/javascript/benchmark/index.js)。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/features.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/features.md index fd3aa1252f..ce2907baf1 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/features.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/features.md @@ -1,21 +1,210 @@ --- id: features -title: Features -sidebar_position: 3 +title: 特性 +sidebar_position: 2 --- -- 多种语言：Java/Python/C++/Golang/Javascript/Rust。 -- 零拷贝：类似[pickle5](https://peps.python.org/pep-0574/)，支持堆外读/写的跨语言序列化。 -- 高性能：高度可扩展的 JIT 框架，可在运行时以异步多线程方式生成序列化程序代码，以加快序列化速度，通过以下方式提升 20-170 倍的速度： - - 减少在生成代码中内联变量减少内存访问； - - 通过在生成的代码中内联调用来减少虚拟方法调用； - - 减少条件分支； - - 减少哈希查找； -- 二进制协议：对象图、行格式等。 - -除了跨语言序列化之外，Apache Fory™ 还支持以下功能： - -- 直接替换 Java 序列化框架，如 JDK/Kryo/Hessian，无需修改任何代码，但速度提高 100 倍。它可以大大提高 RPC 调用性能、数据传输和对象持久化的效率； -- JDK 序列化 100% 兼容，原生支持 java 自定义序列化 `writeObject/readObject/writeReplace/readResolve/readObjectNoData`； -- 支持 golang 的共享和循环引用对象序列化； -- 支持 golang 的自动对象序列化。 +## 核心能力 + +### 高性能序列化 + +Apache Fory™ 通过先进的优化技术提供卓越性能： + +- **JIT 编译**：Java 运行时代码生成可消除虚方法调用并内联热点路径 +- **静态代码生成**：Rust、C++ 和 Go 的编译时代码生成可在无运行时开销的情况下实现峰值性能 +- **零拷贝操作**：直接访问内存，无需中间缓冲区复制；行格式支持随机访问和部分序列化 +- **智能编码**：对整数和字符串采用变长压缩；对数组提供 SIMD 加速（Java 16+） +- **元数据共享**：类元数据打包可减少多次序列化中的冗余类型信息 + +### 跨语言序列化 + +**[xlang 序列化格式](../specification/xlang_serialization_spec.md)** 支持不同编程语言之间的无缝数据交换： + +- **自动类型映射**：在语言特定类型之间进行智能转换（[类型映射](../specification/xlang_type_mapping.md)） +- **引用保持**：共享引用和循环引用在跨语言场景下也能正确工作 +- **多态**：对象会按其真实运行时类型进行序列化和反序列化 +- **Schema 演进**：可选的向前和向后兼容能力，支持 Schema 演进 +- **自动序列化**：无需 IDL 或 Schema 定义；无需代码生成即可直接序列化任意对象 + +### 行格式 + +面向分析类工作负载优化、对缓存友好的 **[行格式](../specification/row_format_spec.md)**： + +- **零拷贝随机访问**：无需反序列化整个对象即可读取单个字段 +- **部分操作**：按需序列化和反序列化部分字段以提升效率 +- **Apache Arrow 集成**：可无缝转换为列式格式，适用于分析流水线 +- **多语言支持**：支持 Java、Python、Rust 和 C++ + +### 安全性与生产就绪 + +企业级安全性与兼容性： + +- **类注册**：基于白名单的反序列化控制机制（默认启用） +- **深度限制**：防止递归对象图攻击 +- **可配置策略**：支持自定义类检查器和反序列化策略 +- **平台支持**：支持 Java 8-24、GraalVM 原生镜像及多种操作系统平台 + +## Java 特性 + +### 高性能 + +- **JIT 代码生成**：高度可扩展的 JIT 框架可通过异步多线程编译在运行时生成序列化器代码，并通过以下方式带来 20-170 倍加速： + - 内联变量以减少内存访问 + - 内联方法调用以消除虚分发开销 + - 尽量减少条件分支 + - 消除哈希查找 +- **零拷贝**：直接访问内存，无需中间缓冲区复制；行格式支持随机访问和部分序列化 +- **变长编码**：对整数和长整数进行优化压缩 +- **元数据共享**：缓存类元数据以减少冗余类型信息 +- **SIMD 加速**：支持 Java Vector API 进行数组操作（Java 16+） + +### 直接替换 + +- **100% 兼容 JDK 序列化**：支持 `writeObject`/`readObject`/`writeReplace`/`readResolve`/`readObjectNoData`/`Externalizable` +- **支持 Java 8-24**：兼容所有现代 Java 版本，包括 Java 17+ 的 record +- **GraalVM 原生镜像**：支持 AOT 编译，无需反射配置 + +### 高级特性 + +- **引用跟踪**：自动处理共享引用和循环引用 +- **Schema 演进**：支持类 Schema 的向前和向后兼容 +- **多态**：完整支持继承层次结构和接口 +- **深拷贝**：高效深拷贝复杂对象图并保留引用关系 +- **安全性**：支持类注册和可配置的反序列化策略 + +## Python 特性 + +### **灵活的序列化模式** + +- **Python 原生模式**：完全兼容 Python，可直接替换 pickle/cloudpickle +- **跨语言模式**：针对多语言数据交换进行优化 +- **行格式**：面向分析工作负载的零拷贝行格式 + +### 多样化的序列化特性 + +- **支持共享引用和循环引用**：适用于 Python 原生模式和跨语言模式下的复杂对象图 +- **支持多态**：对自定义类型进行自动类型分发 +- **支持 Schema 演进**：在跨语言模式下，对 dataclass 提供向前和向后兼容能力 +- **支持带外缓冲区**：可对 NumPy 数组、Pandas DataFrame 等大型数据结构进行零拷贝序列化，并兼容 pickle protocol 5 + +### **极速性能** + +- **性能极快**：相比其他序列化框架具有明显性能优势 +- **运行时代码生成** 与 **Cython 加速** 的核心实现，可提供最佳性能 + +### 紧凑的数据大小 + +- **紧凑的对象图协议**：空间开销极低，相比 pickle/cloudpickle 最多可减少 3 倍数据大小 +- **元数据打包与共享**：可减少类型向前和向后兼容带来的额外空间开销 + +### **安全与可靠性** + +- **严格模式**：通过类型注册和校验，防止反序列化不受信任的类型 +- **引用跟踪**：可安全处理循环引用 + +## Rust 特性 + +### 为什么选择 Apache Fory™ Rust？ + +- **极致性能**：支持零拷贝反序列化和优化的二进制协议 +- **跨语言**：可在 Java、Python、C++、Go、JavaScript 和 Rust 之间无缝序列化和反序列化数据 +- **类型安全**：通过 derive macro 在编译期进行类型检查 +- **循环引用**：自动跟踪共享引用和循环引用，支持 `Rc`/`Arc` 与弱引用 +- **多态**：支持对 `Box<dyn Trait>`、`Rc<dyn Trait>` 和 `Arc<dyn Trait>` 等 trait 对象进行序列化 +- **Schema 演进**：兼容模式支持类型定义独立演进 +- **双模式**：同时支持对象图序列化和零拷贝行格式 + +### 对象图序列化 + +自动序列化复杂对象图，并保留对象之间的结构和关系。`#[derive(ForyObject)]` macro 会在编译期生成高效的序列化代码，从而消除运行时开销： + +- 支持任意深度的嵌套 struct 序列化 +- 支持集合类型（Vec、HashMap、HashSet、BTreeMap） +- 支持枚举类型 +- 通过 `Option<T>` 支持可选字段 +- 自动处理基础类型和字符串 +- 使用变长整数实现高效二进制编码 + +### 共享引用与循环引用 + +通过 `Rc<T>` 和 `Arc<T>` 自动跟踪并保留共享对象的引用标识。当同一个对象被多次引用时，Fory 只会序列化一次，并在后续位置使用引用 ID。这带来以下好处： + +- **空间效率**：序列化结果中不会重复存储相同数据 +- **引用标识保持**：反序列化后的对象会保留相同的共享关系 +- **支持循环引用**：可使用 `RcWeak<T>` 和 `ArcWeak<T>` 断开循环 + +### Trait 对象序列化 + +通过 trait 对象实现多态序列化，从而支持动态分发和类型灵活性。这对插件系统、异构集合和可扩展架构非常重要。支持的 trait 对象类型包括： + +- `Box<dyn Trait>` - 拥有所有权的 trait 对象 +- `Rc<dyn Trait>` - 引用计数 trait 对象 +- `Arc<dyn Trait>` - 线程安全的引用计数 trait 对象 +- `Vec<Box<dyn Trait>>`、`HashMap<K, Box<dyn Trait>>` - trait 对象集合 + +### Schema 演进 + +在 **兼容模式** 下支持 Schema 演进，允许序列化端和反序列化端使用不同的类型定义。这使分布式系统中的服务可以独立演进而不破坏兼容性： + +- 新增带默认值的字段 +- 删除废弃字段（反序列化时跳过） +- 修改字段可空性（`T` ↔ `Option<T>`） +- 调整字段顺序（按名称匹配，而非按位置匹配） +- 对缺失字段进行类型安全的默认值回退 + +### 自定义序列化器 + +对于不支持 `#[derive(ForyObject)]` 的类型，可以手动实现 `Serializer` trait。这适用于以下场景： + +- 其他 crate 中的外部类型 +- 有特殊序列化需求的类型 +- 与旧数据格式兼容 +- 对性能要求极高的自定义编码 + +### 基于行的序列化 + +高性能 **行格式** 支持零拷贝反序列化。与传统对象序列化需要在内存中重建整个对象不同，行格式支持直接从二进制数据中 **随机访问** 字段，而无需完整反序列化。 + +- **零拷贝访问**：读取字段时无需分配或复制数据 +- **部分反序列化**：只访问需要的字段 +- **内存映射文件**：可处理大于 RAM 的数据 +- **缓存友好**：顺序内存布局可更高效利用 CPU 缓存 +- **惰性求值**：将高成本操作延迟到字段访问时再执行 + +## Scala 特性 + +### 支持的类型 + +Apache Fory™ 支持所有 Scala 对象序列化： + +- 支持 `case class` 序列化 +- 支持 `pojo/bean` 类序列化 +- 支持 `object` 单例序列化 +- 支持 `collection` 序列化 +- 其他类型如 `tuple/either` 以及基础类型也都支持 + +同时支持 Scala 2 和 Scala 3。 + +### Scala 类默认值支持 + +Fory 在兼容模式下支持 Scala 类在反序列化时使用默认值。该特性使 case class 或普通 Scala 类在带有默认参数时也能实现向前和向后兼容。 + +当 Scala 类带有默认参数时，Scala 编译器会在伴生对象中（针对 case class）或类自身中（针对普通 Scala 类）生成类似 `apply$default$1`、`apply$default$2` 的方法，用于返回默认值。Fory 可以识别这些方法，并在反序列化时为缺失字段应用默认值。 + +## Kotlin 特性 + +Kotlin 支持建立在默认的 Fory Java 实现之上，并增加了对 Kotlin 特有类型和 Schema 演进的处理能力。 + +### 支持的类型 + +- 基础类型：`Byte`、`Boolean`、`Int`、`Short`、`Long`、`Char`、`Float`、`Double` +- 无符号类型：`UByte`、`UShort`、`UInt`、`ULong` +- 通过默认 Java 实现支持字符串、标准数组和标准集合 +- Kotlin 集合和数组，例如 `ArrayDeque`、`Array`、`BooleanArray`、`ByteArray`、`IntArray`、`LongArray`、`UByteArray`、`UIntArray` 和 `ULongArray` +- 常见标准库类型，包括 `Pair`、`Triple`、`Result`、`Regex`、`Random`、`Duration` 和 `Uuid` +- Kotlin range 和 progression 类型，例如 `CharRange`、`IntRange`、`LongRange`、`UIntRange`、`ULongRange` 及其对应的 progression 类型 +- 空集合，如 `emptyList`、`emptyMap` 和 `emptySet` + +### 数据类默认值支持 + +在兼容模式下，Fory 可以识别 Kotlin 数据类的默认值，并在字段缺失时于反序列化阶段自动应用这些默认值。这使 Schema 演进更加安全，例如在新增带默认值字段时无需破坏兼容性。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md index c278da4303..e2d46e8707 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/overview.md @@ -13,7 +13,7 @@ sidebar_position: 1 ## 快速示例 -跨语言序列化 - 在 Rust 中序列化，在 Python 中反序列化： +跨语言序列化，在 Rust 中序列化，在 Python 中反序列化： **Rust** @@ -59,7 +59,7 @@ print(decoded) # User(name='Alice', age=30) ## 核心特性 -### 🚀 高性能序列化 +### 高性能序列化 Apache Fory™ 通过先进的优化技术提供卓越性能： @@ -69,7 +69,7 @@ Apache Fory™ 通过先进的优化技术提供卓越性能： - **智能编码**：整数和字符串的变长压缩；数组的 SIMD 加速（Java 16+） - **元数据共享**：类元数据打包减少跨序列化的冗余类型信息 -### 🔄 跨语言序列化 +### 跨语言序列化 **[xlang 序列化格式](../specification/xlang_serialization_spec.md)** 支持跨编程语言的无缝数据交换： @@ -79,7 +79,7 @@ Apache Fory™ 通过先进的优化技术提供卓越性能： - **Schema 演进**：可选的向前/向后兼容性支持 Schema 演进 - **自动序列化**：无需 IDL 或 Schema 定义；直接序列化任何对象，无需代码生成 -### 📊 行格式 +### 行格式 针对分析工作负载优化的缓存友好型 **[行格式](../specification/row_format_spec.md)**： @@ -88,7 +88,7 @@ Apache Fory™ 通过先进的优化技术提供卓越性能： - **Apache Arrow 集成**：无缝转换为列格式以用于分析流水线 - **多语言支持**：可用于 Java、Python、Rust 和 C++ -### 🔒 安全性与生产就绪 +### 安全性与生产就绪 企业级安全性和兼容性： @@ -116,23 +116,24 @@ Apache Fory™ 实现了针对不同场景优化的多个二进制协议： | 指南 | 描述 | 源文件 | 网站 | | ---------------- | ----------------------- | ------------------------------------------------------------------------------------- | -------------------------------------- | -| **Java 序列化** | Java 序列化综合指南 | [Java 指南](https://github.com/apache/fory/blob/main/docs/guide/java/) | [📖 查看](../guide/java) | -| **跨语言序列化** | 多语言对象交换 | [Xlang 指南](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [📖 查看](../guide/xlang) | -| **行格式** | 零拷贝随机访问格式 | [Java 行格式](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [📖 查看](../guide/java/row-format.md) | -| **Python** | Python 特定功能和用法 | [Python 指南](https://github.com/apache/fory/blob/main/docs/guide/python/) | [📖 查看](../guide/python) | -| **Rust** | Rust 实现和模式 | [Rust 指南](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [📖 查看](../guide/rust) | -| **Scala** | Scala 集成和最佳实践 | [Scala 指南](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [📖 查看](../guide/scala) | -| **GraalVM** | 原生镜像支持和 AOT 编译 | [GraalVM 指南](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [📖 查看](../guide/graalvm_guide.md) | -| **开发** | 构建和贡献 Fory | [开发指南](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [📖 查看](../guide/DEVELOPMENT) | +| **Java 序列化** | Java 序列化综合指南 | [Java 指南](https://github.com/apache/fory/blob/main/docs/guide/java/) | [查看](../guide/java) | +| **跨语言序列化** | 多语言对象交换 | [Xlang 指南](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [查看](../guide/xlang) | +| **行格式** | 零拷贝随机访问格式 | [Java 行格式](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [查看](../guide/java/row-format.md) | +| **Python** | Python 特定功能和用法 | [Python 指南](https://github.com/apache/fory/blob/main/docs/guide/python/) | [查看](../guide/python) | +| **Rust** | Rust 实现和模式 | [Rust 指南](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [查看](../guide/rust) | +| **Go** | Go 实现和用法 | [Go 指南](https://github.com/apache/fory/blob/main/docs/guide/go/) | [查看](../guide/go) | +| **Scala** | Scala 集成和最佳实践 | [Scala 指南](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [查看](../guide/scala) | +| **GraalVM** | 原生镜像支持和 AOT 编译 | [GraalVM 指南](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [查看](../guide/graalvm_guide.md) | +| **开发** | 构建和贡献 Fory | [开发指南](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [查看](../guide/DEVELOPMENT) | ### 协议规范 | 规范 | 描述 | 源文件 | 网站 | | ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| **跨语言序列化** | 跨语言二进制协议 | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [📖 查看](../specification/xlang_serialization_spec.md) | -| **Java 序列化** | Java 优化协议 | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [📖 查看](../specification/java_serialization_spec.md) | -| **行格式** | 基于行的二进制格式 | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [📖 查看](../specification/row_format_spec.md) | -| **类型映射** | 跨语言类型转换 | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [📖 查看](../specification/xlang_type_mapping.md) | +| **跨语言序列化** | 跨语言二进制协议 | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [查看](../specification/xlang_serialization_spec.md) | +| **Java 序列化** | Java 优化协议 | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [查看](../specification/java_serialization_spec.md) | +| **行格式** | 基于行的二进制格式 | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [查看](../specification/row_format_spec.md) | +| **类型映射** | 跨语言类型转换 | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [查看](../specification/xlang_type_mapping.md) | ## 兼容性 @@ -189,11 +190,11 @@ Fory 默认**启用**动态协议的类注册，只允许受信任的已注册 **贡献方式**： -- 🐛 报告错误和问题 -- 💡 提出新功能 -- 📝 改进文档 -- 🔧 提交 Pull Request -- 🧪 添加测试用例 -- 📊 分享基准测试 +- 报告错误和问题 +- 提出新功能 +- 改进文档 +- 提交 Pull Request +- 添加测试用例 +- 分享基准测试 详见[开发指南](../guide/DEVELOPMENT.md)了解构建说明和开发工作流程。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/benchmark.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/benchmark.md index 568bd14fc0..fc67c0ac41 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/benchmark.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/benchmark.md @@ -1,26 +1,24 @@ --- id: benchmark title: 性能测试 -sidebar_position: 2 +sidebar_position: 3 --- -不同的序列化框架适用于不同的场景，此处的性能测试结果仅供参考。 - -如果您需要针对特定场景进行性能测试，请确保所有序列化框架都针对该场景进行了适当配置。 - -动态序列化框架支持多态和引用，与静态序列化框架相比会有更多开销，除非像 Apache Fory™ 那样使用 JIT 技术。 -由于 Apache Fory™ 会在运行时生成代码，因此在收集性能测试统计数据之前请进行预热。 +> **说明**：不同的序列化框架在不同场景下各有优势。性能测试结果仅供参考。 +> 对于你的具体使用场景，请使用合适的配置和工作负载自行进行基准测试。 ## Java 性能测试 -Java 部分已切换为 `docs/benchmarks/java` 中的最新性能测试图。图表现在按以下维度分组： +Java 性能测试部分使用 `docs/benchmarks/java` 中的当前基准套件，对 Fory 与常见 Java 序列化框架进行对比。 -- **Heap**：序列化到堆上 `byte[]` 缓冲区 +图表按以下维度分组： + +- **Heap**：序列化到堆上的 `byte[]` 缓冲区 - **Off-heap**：序列化到 direct/off-heap 缓冲区 -- **Compatible**：启用前向/后向兼容的 Schema 演进模式 -- **Consistent**：要求读写两端 Schema 完全一致的模式 +- **Compatible**：启用向前和向后兼容的 Schema 演进模式 +- **Consistent**：要求通信双方 Schema 完全一致的 Schema 一致模式 -**测试数据类型**： +**测试类**： - `Struct`：包含 [100 个基础类型字段](https://github.com/apache/fory/tree/main/docs/benchmarks#Struct) 的类 - `MediaContent`：来自 [jvm-serializers](https://github.com/eishay/jvm-serializers/blob/master/tpc/src/data/media/MediaContent.java) 的类 @@ -66,7 +64,7 @@ Consistent 模式： <img width="90%" alt="" src="/img/benchmarks/deserialization/bench_deserialize_STRUCT_from_directBuffer_tps.png" /> -### 仓库基准汇总 +### 仓库吞吐汇总 序列化吞吐： @@ -86,46 +84,56 @@ Consistent 模式： <img width="90%" alt="" src="/img/benchmarks/zerocopy/zero_copy_bench_deserialize_BUFFER_from_array_tps.png" /> -注意：Apache Fory™ 依赖运行时代码生成，进行性能测试前必须充分预热。 +**重要说明**：Fory 的运行时代码生成依赖充分预热后才能进行准确的性能测量。 -更多说明、原始数据和完整 Java benchmark README 请参见 [Java Benchmarks](https://github.com/apache/fory/tree/main/docs/benchmarks/java)。 +更多性能测试说明、原始数据和完整 Java benchmark README 请参见 [Java Benchmarks](https://github.com/apache/fory/tree/main/docs/benchmarks/java)。 ## Rust 性能测试 +Fory Rust 相比其他 Rust 序列化框架展现出有竞争力的性能。 + <img src="/img/benchmarks/rust/company.png" width="90%"/> <img src="/img/benchmarks/rust/ecommerce_data.png" width="90%"/> <img src="/img/benchmarks/rust/system_data.png" width="90%"/> -注意：结果取决于硬件、数据集和实现版本。有关如何自行运行性能测试的信息，请参阅 Fory Rust Benchmark 指南：https://github.com/apache/fory/blob/main/benchmarks/rust_benchmark/README.md +注意：结果取决于硬件、数据集和实现版本。关于如何自行运行性能测试，请参见 Rust 指南：https://github.com/apache/fory/blob/main/benchmarks/rust_benchmark/README.md ## C++ 性能测试 -Fory C++ 在性能方面相较 Protobuf C++ 序列化框架具有竞争力。 +Fory C++ 相比 Protobuf C++ 序列化框架展现出有竞争力的性能。 <img src="/img/benchmarks/cpp/throughput.png" width="90%"/> ## Go 性能测试 -Fory Go 在单对象和列表两类工作负载下，相较 Protobuf 与 Msgpack 展现出较强的性能表现。 +Fory Go 在单对象和列表两类工作负载下，相比 Protobuf 和 Msgpack 展现出较强的性能表现。 <img src="/img/blog/fory_0_16_0_release/go_benchmark_combined.png" width="90%"/> 注意：结果取决于硬件、数据集和实现版本。详细信息请参见 Go 性能测试报告：https://fory.apache.org/docs/benchmarks/go/ -## Python 性能测试 +## C\# 性能测试 + +Fory C\# 在强类型对象的序列化和反序列化工作负载下，相比 Protobuf 和 Msgpack 展现出较强的性能表现。 + +<img src="/img/blog/fory_0_16_0_release/csharp_benchmark_combined.png" width="90%"/> + +注意：结果取决于硬件和运行时版本。详细信息请参见 C\# 性能测试报告：https://fory.apache.org/docs/benchmarks/csharp/ + +## Swift 性能测试 -Fory Python 在单对象和列表两类工作负载下，相较 `pickle` 与 Protobuf 展现出较强的性能表现。 +Fory Swift 在标量对象和列表两类工作负载下，相比 Protobuf 和 Msgpack 展现出较强的性能表现。 -<img src="/img/benchmarks/python/throughput.png" width="90%"/> +<img src="/img/blog/fory_0_16_0_release/swift_benchmark_combined.png" width="90%"/> -注意：结果取决于硬件、数据集、Python 运行时和实现版本。详细信息请参见 Python 性能测试报告：https://fory.apache.org/docs/benchmarks/python/ +注意：结果取决于硬件和运行时版本。详细信息请参见 Swift 性能测试报告：https://fory.apache.org/docs/benchmarks/swift/ ## JavaScript 性能测试 -<img width="33%" alt="" src="/img/benchmarks/javascript/complex_object.jpg" /> +<img width="50%" alt="" src="/img/benchmarks/javascript/complex_object.jpg" /> -此柱状图使用的数据包含一个具有多种字段类型的复杂对象，JSON 数据大小为 3KB。 +该柱状图使用的数据包含一个具有多种字段类型的复杂对象，JSON 数据大小为 3KB。 性能测试代码请参见 [benchmarks](https://github.com/apache/fory/blob/main/javascript/benchmark/index.js)。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/features.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/features.md index fd3aa1252f..ce2907baf1 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/features.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/features.md @@ -1,21 +1,210 @@ --- id: features -title: Features -sidebar_position: 3 +title: 特性 +sidebar_position: 2 --- -- 多种语言：Java/Python/C++/Golang/Javascript/Rust。 -- 零拷贝：类似[pickle5](https://peps.python.org/pep-0574/)，支持堆外读/写的跨语言序列化。 -- 高性能：高度可扩展的 JIT 框架，可在运行时以异步多线程方式生成序列化程序代码，以加快序列化速度，通过以下方式提升 20-170 倍的速度： - - 减少在生成代码中内联变量减少内存访问； - - 通过在生成的代码中内联调用来减少虚拟方法调用； - - 减少条件分支； - - 减少哈希查找； -- 二进制协议：对象图、行格式等。 - -除了跨语言序列化之外，Apache Fory™ 还支持以下功能： - -- 直接替换 Java 序列化框架，如 JDK/Kryo/Hessian，无需修改任何代码，但速度提高 100 倍。它可以大大提高 RPC 调用性能、数据传输和对象持久化的效率； -- JDK 序列化 100% 兼容，原生支持 java 自定义序列化 `writeObject/readObject/writeReplace/readResolve/readObjectNoData`； -- 支持 golang 的共享和循环引用对象序列化； -- 支持 golang 的自动对象序列化。 +## 核心能力 + +### 高性能序列化 + +Apache Fory™ 通过先进的优化技术提供卓越性能： + +- **JIT 编译**：Java 运行时代码生成可消除虚方法调用并内联热点路径 +- **静态代码生成**：Rust、C++ 和 Go 的编译时代码生成可在无运行时开销的情况下实现峰值性能 +- **零拷贝操作**：直接访问内存，无需中间缓冲区复制；行格式支持随机访问和部分序列化 +- **智能编码**：对整数和字符串采用变长压缩；对数组提供 SIMD 加速（Java 16+） +- **元数据共享**：类元数据打包可减少多次序列化中的冗余类型信息 + +### 跨语言序列化 + +**[xlang 序列化格式](../specification/xlang_serialization_spec.md)** 支持不同编程语言之间的无缝数据交换： + +- **自动类型映射**：在语言特定类型之间进行智能转换（[类型映射](../specification/xlang_type_mapping.md)） +- **引用保持**：共享引用和循环引用在跨语言场景下也能正确工作 +- **多态**：对象会按其真实运行时类型进行序列化和反序列化 +- **Schema 演进**：可选的向前和向后兼容能力，支持 Schema 演进 +- **自动序列化**：无需 IDL 或 Schema 定义；无需代码生成即可直接序列化任意对象 + +### 行格式 + +面向分析类工作负载优化、对缓存友好的 **[行格式](../specification/row_format_spec.md)**： + +- **零拷贝随机访问**：无需反序列化整个对象即可读取单个字段 +- **部分操作**：按需序列化和反序列化部分字段以提升效率 +- **Apache Arrow 集成**：可无缝转换为列式格式，适用于分析流水线 +- **多语言支持**：支持 Java、Python、Rust 和 C++ + +### 安全性与生产就绪 + +企业级安全性与兼容性： + +- **类注册**：基于白名单的反序列化控制机制（默认启用） +- **深度限制**：防止递归对象图攻击 +- **可配置策略**：支持自定义类检查器和反序列化策略 +- **平台支持**：支持 Java 8-24、GraalVM 原生镜像及多种操作系统平台 + +## Java 特性 + +### 高性能 + +- **JIT 代码生成**：高度可扩展的 JIT 框架可通过异步多线程编译在运行时生成序列化器代码，并通过以下方式带来 20-170 倍加速： + - 内联变量以减少内存访问 + - 内联方法调用以消除虚分发开销 + - 尽量减少条件分支 + - 消除哈希查找 +- **零拷贝**：直接访问内存，无需中间缓冲区复制；行格式支持随机访问和部分序列化 +- **变长编码**：对整数和长整数进行优化压缩 +- **元数据共享**：缓存类元数据以减少冗余类型信息 +- **SIMD 加速**：支持 Java Vector API 进行数组操作（Java 16+） + +### 直接替换 + +- **100% 兼容 JDK 序列化**：支持 `writeObject`/`readObject`/`writeReplace`/`readResolve`/`readObjectNoData`/`Externalizable` +- **支持 Java 8-24**：兼容所有现代 Java 版本，包括 Java 17+ 的 record +- **GraalVM 原生镜像**：支持 AOT 编译，无需反射配置 + +### 高级特性 + +- **引用跟踪**：自动处理共享引用和循环引用 +- **Schema 演进**：支持类 Schema 的向前和向后兼容 +- **多态**：完整支持继承层次结构和接口 +- **深拷贝**：高效深拷贝复杂对象图并保留引用关系 +- **安全性**：支持类注册和可配置的反序列化策略 + +## Python 特性 + +### **灵活的序列化模式** + +- **Python 原生模式**：完全兼容 Python，可直接替换 pickle/cloudpickle +- **跨语言模式**：针对多语言数据交换进行优化 +- **行格式**：面向分析工作负载的零拷贝行格式 + +### 多样化的序列化特性 + +- **支持共享引用和循环引用**：适用于 Python 原生模式和跨语言模式下的复杂对象图 +- **支持多态**：对自定义类型进行自动类型分发 +- **支持 Schema 演进**：在跨语言模式下，对 dataclass 提供向前和向后兼容能力 +- **支持带外缓冲区**：可对 NumPy 数组、Pandas DataFrame 等大型数据结构进行零拷贝序列化，并兼容 pickle protocol 5 + +### **极速性能** + +- **性能极快**：相比其他序列化框架具有明显性能优势 +- **运行时代码生成** 与 **Cython 加速** 的核心实现，可提供最佳性能 + +### 紧凑的数据大小 + +- **紧凑的对象图协议**：空间开销极低，相比 pickle/cloudpickle 最多可减少 3 倍数据大小 +- **元数据打包与共享**：可减少类型向前和向后兼容带来的额外空间开销 + +### **安全与可靠性** + +- **严格模式**：通过类型注册和校验，防止反序列化不受信任的类型 +- **引用跟踪**：可安全处理循环引用 + +## Rust 特性 + +### 为什么选择 Apache Fory™ Rust？ + +- **极致性能**：支持零拷贝反序列化和优化的二进制协议 +- **跨语言**：可在 Java、Python、C++、Go、JavaScript 和 Rust 之间无缝序列化和反序列化数据 +- **类型安全**：通过 derive macro 在编译期进行类型检查 +- **循环引用**：自动跟踪共享引用和循环引用，支持 `Rc`/`Arc` 与弱引用 +- **多态**：支持对 `Box<dyn Trait>`、`Rc<dyn Trait>` 和 `Arc<dyn Trait>` 等 trait 对象进行序列化 +- **Schema 演进**：兼容模式支持类型定义独立演进 +- **双模式**：同时支持对象图序列化和零拷贝行格式 + +### 对象图序列化 + +自动序列化复杂对象图，并保留对象之间的结构和关系。`#[derive(ForyObject)]` macro 会在编译期生成高效的序列化代码，从而消除运行时开销： + +- 支持任意深度的嵌套 struct 序列化 +- 支持集合类型（Vec、HashMap、HashSet、BTreeMap） +- 支持枚举类型 +- 通过 `Option<T>` 支持可选字段 +- 自动处理基础类型和字符串 +- 使用变长整数实现高效二进制编码 + +### 共享引用与循环引用 + +通过 `Rc<T>` 和 `Arc<T>` 自动跟踪并保留共享对象的引用标识。当同一个对象被多次引用时，Fory 只会序列化一次，并在后续位置使用引用 ID。这带来以下好处： + +- **空间效率**：序列化结果中不会重复存储相同数据 +- **引用标识保持**：反序列化后的对象会保留相同的共享关系 +- **支持循环引用**：可使用 `RcWeak<T>` 和 `ArcWeak<T>` 断开循环 + +### Trait 对象序列化 + +通过 trait 对象实现多态序列化，从而支持动态分发和类型灵活性。这对插件系统、异构集合和可扩展架构非常重要。支持的 trait 对象类型包括： + +- `Box<dyn Trait>` - 拥有所有权的 trait 对象 +- `Rc<dyn Trait>` - 引用计数 trait 对象 +- `Arc<dyn Trait>` - 线程安全的引用计数 trait 对象 +- `Vec<Box<dyn Trait>>`、`HashMap<K, Box<dyn Trait>>` - trait 对象集合 + +### Schema 演进 + +在 **兼容模式** 下支持 Schema 演进，允许序列化端和反序列化端使用不同的类型定义。这使分布式系统中的服务可以独立演进而不破坏兼容性： + +- 新增带默认值的字段 +- 删除废弃字段（反序列化时跳过） +- 修改字段可空性（`T` ↔ `Option<T>`） +- 调整字段顺序（按名称匹配，而非按位置匹配） +- 对缺失字段进行类型安全的默认值回退 + +### 自定义序列化器 + +对于不支持 `#[derive(ForyObject)]` 的类型，可以手动实现 `Serializer` trait。这适用于以下场景： + +- 其他 crate 中的外部类型 +- 有特殊序列化需求的类型 +- 与旧数据格式兼容 +- 对性能要求极高的自定义编码 + +### 基于行的序列化 + +高性能 **行格式** 支持零拷贝反序列化。与传统对象序列化需要在内存中重建整个对象不同，行格式支持直接从二进制数据中 **随机访问** 字段，而无需完整反序列化。 + +- **零拷贝访问**：读取字段时无需分配或复制数据 +- **部分反序列化**：只访问需要的字段 +- **内存映射文件**：可处理大于 RAM 的数据 +- **缓存友好**：顺序内存布局可更高效利用 CPU 缓存 +- **惰性求值**：将高成本操作延迟到字段访问时再执行 + +## Scala 特性 + +### 支持的类型 + +Apache Fory™ 支持所有 Scala 对象序列化： + +- 支持 `case class` 序列化 +- 支持 `pojo/bean` 类序列化 +- 支持 `object` 单例序列化 +- 支持 `collection` 序列化 +- 其他类型如 `tuple/either` 以及基础类型也都支持 + +同时支持 Scala 2 和 Scala 3。 + +### Scala 类默认值支持 + +Fory 在兼容模式下支持 Scala 类在反序列化时使用默认值。该特性使 case class 或普通 Scala 类在带有默认参数时也能实现向前和向后兼容。 + +当 Scala 类带有默认参数时，Scala 编译器会在伴生对象中（针对 case class）或类自身中（针对普通 Scala 类）生成类似 `apply$default$1`、`apply$default$2` 的方法，用于返回默认值。Fory 可以识别这些方法，并在反序列化时为缺失字段应用默认值。 + +## Kotlin 特性 + +Kotlin 支持建立在默认的 Fory Java 实现之上，并增加了对 Kotlin 特有类型和 Schema 演进的处理能力。 + +### 支持的类型 + +- 基础类型：`Byte`、`Boolean`、`Int`、`Short`、`Long`、`Char`、`Float`、`Double` +- 无符号类型：`UByte`、`UShort`、`UInt`、`ULong` +- 通过默认 Java 实现支持字符串、标准数组和标准集合 +- Kotlin 集合和数组，例如 `ArrayDeque`、`Array`、`BooleanArray`、`ByteArray`、`IntArray`、`LongArray`、`UByteArray`、`UIntArray` 和 `ULongArray` +- 常见标准库类型，包括 `Pair`、`Triple`、`Result`、`Regex`、`Random`、`Duration` 和 `Uuid` +- Kotlin range 和 progression 类型，例如 `CharRange`、`IntRange`、`LongRange`、`UIntRange`、`ULongRange` 及其对应的 progression 类型 +- 空集合，如 `emptyList`、`emptyMap` 和 `emptySet` + +### 数据类默认值支持 + +在兼容模式下，Fory 可以识别 Kotlin 数据类的默认值，并在字段缺失时于反序列化阶段自动应用这些默认值。这使 Schema 演进更加安全，例如在新增带默认值字段时无需破坏兼容性。 diff --git a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/overview.md b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/overview.md index c278da4303..e2d46e8707 100644 --- a/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/overview.md +++ b/i18n/zh-CN/docusaurus-plugin-content-docs/version-0.16/introduction/overview.md @@ -13,7 +13,7 @@ sidebar_position: 1 ## 快速示例 -跨语言序列化 - 在 Rust 中序列化，在 Python 中反序列化： +跨语言序列化，在 Rust 中序列化，在 Python 中反序列化： **Rust** @@ -59,7 +59,7 @@ print(decoded) # User(name='Alice', age=30) ## 核心特性 -### 🚀 高性能序列化 +### 高性能序列化 Apache Fory™ 通过先进的优化技术提供卓越性能： @@ -69,7 +69,7 @@ Apache Fory™ 通过先进的优化技术提供卓越性能： - **智能编码**：整数和字符串的变长压缩；数组的 SIMD 加速（Java 16+） - **元数据共享**：类元数据打包减少跨序列化的冗余类型信息 -### 🔄 跨语言序列化 +### 跨语言序列化 **[xlang 序列化格式](../specification/xlang_serialization_spec.md)** 支持跨编程语言的无缝数据交换： @@ -79,7 +79,7 @@ Apache Fory™ 通过先进的优化技术提供卓越性能： - **Schema 演进**：可选的向前/向后兼容性支持 Schema 演进 - **自动序列化**：无需 IDL 或 Schema 定义；直接序列化任何对象，无需代码生成 -### 📊 行格式 +### 行格式 针对分析工作负载优化的缓存友好型 **[行格式](../specification/row_format_spec.md)**： @@ -88,7 +88,7 @@ Apache Fory™ 通过先进的优化技术提供卓越性能： - **Apache Arrow 集成**：无缝转换为列格式以用于分析流水线 - **多语言支持**：可用于 Java、Python、Rust 和 C++ -### 🔒 安全性与生产就绪 +### 安全性与生产就绪 企业级安全性和兼容性： @@ -116,23 +116,24 @@ Apache Fory™ 实现了针对不同场景优化的多个二进制协议： | 指南 | 描述 | 源文件 | 网站 | | ---------------- | ----------------------- | ------------------------------------------------------------------------------------- | -------------------------------------- | -| **Java 序列化** | Java 序列化综合指南 | [Java 指南](https://github.com/apache/fory/blob/main/docs/guide/java/) | [📖 查看](../guide/java) | -| **跨语言序列化** | 多语言对象交换 | [Xlang 指南](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [📖 查看](../guide/xlang) | -| **行格式** | 零拷贝随机访问格式 | [Java 行格式](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [📖 查看](../guide/java/row-format.md) | -| **Python** | Python 特定功能和用法 | [Python 指南](https://github.com/apache/fory/blob/main/docs/guide/python/) | [📖 查看](../guide/python) | -| **Rust** | Rust 实现和模式 | [Rust 指南](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [📖 查看](../guide/rust) | -| **Scala** | Scala 集成和最佳实践 | [Scala 指南](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [📖 查看](../guide/scala) | -| **GraalVM** | 原生镜像支持和 AOT 编译 | [GraalVM 指南](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [📖 查看](../guide/graalvm_guide.md) | -| **开发** | 构建和贡献 Fory | [开发指南](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [📖 查看](../guide/DEVELOPMENT) | +| **Java 序列化** | Java 序列化综合指南 | [Java 指南](https://github.com/apache/fory/blob/main/docs/guide/java/) | [查看](../guide/java) | +| **跨语言序列化** | 多语言对象交换 | [Xlang 指南](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [查看](../guide/xlang) | +| **行格式** | 零拷贝随机访问格式 | [Java 行格式](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [查看](../guide/java/row-format.md) | +| **Python** | Python 特定功能和用法 | [Python 指南](https://github.com/apache/fory/blob/main/docs/guide/python/) | [查看](../guide/python) | +| **Rust** | Rust 实现和模式 | [Rust 指南](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [查看](../guide/rust) | +| **Go** | Go 实现和用法 | [Go 指南](https://github.com/apache/fory/blob/main/docs/guide/go/) | [查看](../guide/go) | +| **Scala** | Scala 集成和最佳实践 | [Scala 指南](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [查看](../guide/scala) | +| **GraalVM** | 原生镜像支持和 AOT 编译 | [GraalVM 指南](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [查看](../guide/graalvm_guide.md) | +| **开发** | 构建和贡献 Fory | [开发指南](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [查看](../guide/DEVELOPMENT) | ### 协议规范 | 规范 | 描述 | 源文件 | 网站 | | ---------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| **跨语言序列化** | 跨语言二进制协议 | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [📖 查看](../specification/xlang_serialization_spec.md) | -| **Java 序列化** | Java 优化协议 | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [📖 查看](../specification/java_serialization_spec.md) | -| **行格式** | 基于行的二进制格式 | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [📖 查看](../specification/row_format_spec.md) | -| **类型映射** | 跨语言类型转换 | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [📖 查看](../specification/xlang_type_mapping.md) | +| **跨语言序列化** | 跨语言二进制协议 | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [查看](../specification/xlang_serialization_spec.md) | +| **Java 序列化** | Java 优化协议 | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [查看](../specification/java_serialization_spec.md) | +| **行格式** | 基于行的二进制格式 | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [查看](../specification/row_format_spec.md) | +| **类型映射** | 跨语言类型转换 | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [查看](../specification/xlang_type_mapping.md) | ## 兼容性 @@ -189,11 +190,11 @@ Fory 默认**启用**动态协议的类注册，只允许受信任的已注册 **贡献方式**： -- 🐛 报告错误和问题 -- 💡 提出新功能 -- 📝 改进文档 -- 🔧 提交 Pull Request -- 🧪 添加测试用例 -- 📊 分享基准测试 +- 报告错误和问题 +- 提出新功能 +- 改进文档 +- 提交 Pull Request +- 添加测试用例 +- 分享基准测试 详见[开发指南](../guide/DEVELOPMENT.md)了解构建说明和开发工作流程。 diff --git a/versioned_docs/version-0.16/introduction/features.md b/versioned_docs/version-0.16/introduction/features.md index 27d736ac31..1651d47036 100644 --- a/versioned_docs/version-0.16/introduction/features.md +++ b/versioned_docs/version-0.16/introduction/features.md @@ -6,7 +6,7 @@ sidebar_position: 2 ## Core Capabilities -### 🚀 High-Performance Serialization +### High-Performance Serialization Apache Fory™ delivers exceptional performance through advanced optimization techniques: @@ -16,7 +16,7 @@ Apache Fory™ delivers exceptional performance through advanced optimization te - **Intelligent Encoding**: Variable-length compression for integers and strings; SIMD acceleration for arrays (Java 16+) - **Meta Sharing**: Class metadata packing reduces redundant type information across serializations -### 🌍 Cross-Language Serialization +### Cross-Language Serialization The **[xlang serialization format](../specification/xlang_serialization_spec.md)** enables seamless data exchange across programming languages: @@ -26,7 +26,7 @@ The **[xlang serialization format](../specification/xlang_serialization_spec.md) - **Schema Evolution**: Optional forward/backward compatibility for evolving schemas - **Automatic Serialization**: No IDL or schema definitions required; serialize any object directly without code generation -### 📊 Row Format +### Row Format A cache-friendly **[row format](../specification/row_format_spec.md)** optimized for analytics workloads: @@ -35,7 +35,7 @@ A cache-friendly **[row format](../specification/row_format_spec.md)** optimized - **Apache Arrow Integration**: Seamless conversion to columnar format for analytics pipelines - **Multi-Language**: Available in Java, Python, Rust and C++ -### 🔒 Security & Production-Readiness +### Security & Production-Readiness Enterprise-grade security and compatibility: @@ -46,7 +46,7 @@ Enterprise-grade security and compatibility: ## Java Features -### 🚀 High Performance +### High Performance - **JIT Code Generation**: Highly-extensible JIT framework generates serializer code at runtime using async multi-threaded compilation, delivering 20-170x speedup through: - Inlining variables to reduce memory access @@ -58,13 +58,13 @@ Enterprise-grade security and compatibility: - **Meta Sharing**: Cached class metadata reduces redundant type information - **SIMD Acceleration**: Java Vector API support for array operations (Java 16+) -### 🔧 Drop-in Replacement +### Drop-in Replacement - **100% JDK Serialization Compatible**: Supports `writeObject`/`readObject`/`writeReplace`/`readResolve`/`readObjectNoData`/`Externalizable` - **Java 8-24 Support**: Works across all modern Java versions including Java 17+ records - **GraalVM Native Image**: AOT compilation support without reflection configuration -### 🔄 Advanced Features +### Advanced Features - **Reference Tracking**: Automatic handling of shared and circular references - **Schema Evolution**: Forward/backward compatibility for class schema changes @@ -74,45 +74,45 @@ Enterprise-grade security and compatibility: ## Python Features -### 🔧 **Flexible Serialization Modes** +### **Flexible Serialization Modes** - **Python native Mode**: Full Python compatibility, drop-in replacement for pickle/cloudpickle - **Cross-Language Mode**: Optimized for multi-language data exchange - **Row Format**: Zero-copy row format for analytics workloads -### 🎯 Versatile Serialization Features +### Versatile Serialization Features - **Shared/circular reference support** for complex object graphs in both Python-native and cross-language modes - **Polymorphism support** for customized types with automatic type dispatching - **Schema evolution** support for backward/forward compatibility when using dataclasses in cross-language mode - **Out-of-band buffer support** for zero-copy serialization of large data structures like NumPy arrays and Pandas DataFrames, compatible with pickle protocol 5 -### ⚡ **Blazing Fast Performance** +### **Blazing Fast Performance** - **Extremely fast performance** compared to other serialization frameworks - **Runtime code generation** and **Cython-accelerated** core implementation for optimal performance -### 📦 Compact Data Size +### Compact Data Size - **Compact object graph protocol** with minimal space overhead—up to 3× size reduction compared to pickle/cloudpickle - **Meta packing and sharing** to minimize type forward/backward compatibility space overhead -### 🛡️ **Security & Safety** +### **Security & Safety** - **Strict mode** prevents deserialization of untrusted types by type registration and checks. - **Reference tracking** for handling circular references safely ## Rust Features -### 🚀 Why Apache Fory™ Rust? +### Why Apache Fory™ Rust? -- **🔥 Blazingly Fast**: Zero-copy deserialization and optimized binary protocols -- **🌍 Cross-Language**: Seamlessly serialize/deserialize data across Java, Python, C++, Go, JavaScript, and Rust -- **🎯 Type-Safe**: Compile-time type checking with derive macros -- **🔄 Circular References**: Automatic tracking of shared and circular references with `Rc`/`Arc` and weak pointers -- **🧬 Polymorphic**: Serialize trait objects with `Box<dyn Trait>`, `Rc<dyn Trait>`, and `Arc<dyn Trait>` -- **📦 Schema Evolution**: Compatible mode for independent schema changes -- **⚡ Two Modes**: Object graph serialization and zero-copy row-based format +- **Blazingly Fast**: Zero-copy deserialization and optimized binary protocols +- **Cross-Language**: Seamlessly serialize/deserialize data across Java, Python, C++, Go, JavaScript, and Rust +- **Type-Safe**: Compile-time type checking with derive macros +- **Circular References**: Automatic tracking of shared and circular references with `Rc`/`Arc` and weak pointers +- **Polymorphic**: Serialize trait objects with `Box<dyn Trait>`, `Rc<dyn Trait>`, and `Arc<dyn Trait>` +- **Schema Evolution**: Compatible mode for independent schema changes +- **Two Modes**: Object graph serialization and zero-copy row-based format ### Object Graph Serialization @@ -193,38 +193,18 @@ When a Scala class has default parameters, the Scala compiler generates methods ## Kotlin Features +Kotlin support builds on the default Fory Java implementation and adds handling for Kotlin-specific types and schema evolution. + ### Supported Types -- primitives: `Byte`, `Boolean`, `Int`, `Short`, `Long`, `Char`, `Float`, `Double`, `UByte`, `UShort`, `UInt`, `ULong`. -- `Byte`, `Boolean`, `Int`, `Short`, `Long`, `Char`, `Float`, `Double` works out of the box with the default fory java implementation. -- stdlib `collection`: `ArrayDeque`, `ArrayList`, `HashMap`,`HashSet`, `LinkedHashSet`, `LinkedHashMap`. -- `ArrayList`, `HashMap`,`HashSet`, `LinkedHashSet`, `LinkedHashMap` works out of the box with the default fory java implementation. -- `String` works out of the box with the default fory java implementation. -- arrays: `Array`, `BooleanArray`, `ByteArray`, `CharArray`, `DoubleArray`, `FloatArray`, `IntArray`, `LongArray`, `ShortArray` -- all standard array types work out of the box with the default fory java implementation. -- unsigned arrays: `UByteArray`, `UShortArray`, `UIntArray`, `ULongArray` -- from stdlib: `Pair`, `Triple`, `Result` -- kotlin.random: `Random` -- kotlin.ranges: `CharRange`, `CharProgression`, `IntRange`, `IntProgression`, `LongRange`, `LongProgression`, `UintRange`, `UintProgression`, `ULongRange`, `ULongProgression` -- kotlin.text: `Regex` -- kotlin.time: `Duration` -- kotlin.uuid: `Uuid` - -Additional support is added for the following classes in kotlin: - -- Unsigned primitives: `UByte`, `UShort`, `UInt`, `ULong` -- Unsigned array types: `UByteArray`, `UShortArray`, `UIntArray`, `ULongArray` -- Empty collections: `emptyList`, `emptyMap`, `emptySet` -- Collections: `ArrayDeque` -- kotlin.time: `Duration` -- kotlin.uuid: `Uuid` +- Primitive types: `Byte`, `Boolean`, `Int`, `Short`, `Long`, `Char`, `Float`, `Double` +- Unsigned types: `UByte`, `UShort`, `UInt`, `ULong` +- Strings, standard arrays, and standard collections through the default Java implementation +- Kotlin collections and arrays such as `ArrayDeque`, `Array`, `BooleanArray`, `ByteArray`, `IntArray`, `LongArray`, `UByteArray`, `UIntArray`, and `ULongArray` +- Common stdlib types including `Pair`, `Triple`, `Result`, `Regex`, `Random`, `Duration`, and `Uuid` +- Kotlin ranges and progressions such as `CharRange`, `IntRange`, `LongRange`, `UIntRange`, `ULongRange`, and related progression types +- Empty collections such as `emptyList`, `emptyMap`, and `emptySet` ### Data Class Default Value Support -Apache Fory™ Kotlin provides support for Kotlin data class default values during serialization and deserialization. This feature allows for backward and forward compatibility when data class schemas evolve. - -When a Kotlin data class has parameters with default values, Apache Fory™ can: - -1. **Detect default values** using Kotlin reflection -2. **Apply default values** during deserialization when fields are missing from serialized data -3. **Support schema evolution** by allowing new fields with defaults to be added without breaking existing serialized data +In compatible mode, Fory can detect Kotlin data class default values and apply them during deserialization when fields are missing. This allows schemas to evolve more safely, for example when adding new fields with defaults. diff --git a/versioned_docs/version-0.16/introduction/overview.md b/versioned_docs/version-0.16/introduction/overview.md index ae0341c6bd..a1e86f49a7 100644 --- a/versioned_docs/version-0.16/introduction/overview.md +++ b/versioned_docs/version-0.16/introduction/overview.md @@ -59,7 +59,7 @@ print(decoded) # User(name='Alice', age=30) ## Key Features -### 🚀 High-Performance Serialization +### High-Performance Serialization Apache Fory™ delivers exceptional performance through advanced optimization techniques: @@ -69,7 +69,7 @@ Apache Fory™ delivers exceptional performance through advanced optimization te - **Intelligent Encoding**: Variable-length compression for integers and strings; SIMD acceleration for arrays (Java 16+) - **Meta Sharing**: Class metadata packing reduces redundant type information across serializations -### 🔄 Cross-Language Serialization +### Cross-Language Serialization The **[xlang serialization format](../specification/xlang_serialization_spec.md)** enables seamless data exchange across programming languages: @@ -79,7 +79,7 @@ The **[xlang serialization format](../specification/xlang_serialization_spec.md) - **Schema Evolution**: Optional forward/backward compatibility for evolving schemas - **Automatic Serialization**: No IDL or schema definitions required; serialize any object directly without code generation -### 📊 Row Format +### Row Format A cache-friendly **[row format](../specification/row_format_spec.md)** optimized for analytics workloads: @@ -88,7 +88,7 @@ A cache-friendly **[row format](../specification/row_format_spec.md)** optimized - **Apache Arrow Integration**: Seamless conversion to columnar format for analytics pipelines - **Multi-Language**: Available in Java, Python, Rust and C++ -### 🔒 Security & Production-Readiness +### Security & Production-Readiness Enterprise-grade security and compatibility: @@ -116,24 +116,24 @@ All protocols share the same optimized codebase, allowing improvements in one pr | Guide | Description | Source | Website | | -------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------- | -| **Java Serialization** | Comprehensive guide for Java serialization | [Java Guide](https://github.com/apache/fory/blob/main/docs/guide/java/) | [📖 View](../guide/java) | -| **Cross-Language Serialization** | Multi-language object exchange | [Xlang Guide](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [📖 View](../guide/xlang) | -| **Row Format** | Zero-copy random access format | [Java Row Format](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [📖 View](../guide/java/row-format.md) | -| **Python** | Python-specific features and usage | [Python Guide](https://github.com/apache/fory/blob/main/docs/guide/python/) | [📖 View](../guide/python) | -| **Rust** | Rust implementation and patterns | [Rust Guide](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [📖 View](../guide/rust) | -| **Go** | Go implementation and usage | [Go Guide](https://github.com/apache/fory/blob/main/docs/guide/go/) | [📖 View](../guide/go) | -| **Scala** | Scala integration and best practices | [Scala Guide](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [📖 View](../guide/scala) | -| **GraalVM** | Native image support and AOT compilation | [GraalVM Guide](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [📖 View](../guide/graalvm_guide.md) | -| **Development** | Building and contributing to Fory | [Development](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [📖 View](../guide/DEVELOPMENT) | +| **Java Serialization** | Comprehensive guide for Java serialization | [Java Guide](https://github.com/apache/fory/blob/main/docs/guide/java/) | [View](../guide/java) | +| **Cross-Language Serialization** | Multi-language object exchange | [Xlang Guide](https://github.com/apache/fory/blob/main/docs/guide/xlang/) | [View](../guide/xlang) | +| **Row Format** | Zero-copy random access format | [Java Row Format](https://github.com/apache/fory/blob/main/docs/guide/java/row-format.md) | [View](../guide/java/row-format.md) | +| **Python** | Python-specific features and usage | [Python Guide](https://github.com/apache/fory/blob/main/docs/guide/python/) | [View](../guide/python) | +| **Rust** | Rust implementation and patterns | [Rust Guide](https://github.com/apache/fory/blob/main/docs/guide/rust/) | [View](../guide/rust) | +| **Go** | Go implementation and usage | [Go Guide](https://github.com/apache/fory/blob/main/docs/guide/go/) | [View](../guide/go) | +| **Scala** | Scala integration and best practices | [Scala Guide](https://github.com/apache/fory/blob/main/docs/guide/scala/) | [View](../guide/scala) | +| **GraalVM** | Native image support and AOT compilation | [GraalVM Guide](https://github.com/apache/fory/blob/main/docs/guide/graalvm_guide.md) | [View](../guide/graalvm_guide.md) | +| **Development** | Building and contributing to Fory | [Development](https://github.com/apache/fory/blob/main/docs/guide/DEVELOPMENT.md) | [View](../guide/DEVELOPMENT) | ### Protocol Specifications | Specification | Description | Source | Website | | ----------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | -| **Xlang Serialization** | Cross-language binary protocol | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [📖 View](../specification/xlang_serialization_spec.md) | -| **Java Serialization** | Java-optimized protocol | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [📖 View](../specification/java_serialization_spec.md) | -| **Row Format** | Row-based binary format | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [📖 View](../specification/row_format_spec.md) | -| **Type Mapping** | Cross-language type conversion | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [📖 View](../specification/xlang_type_mapping.md) | +| **Xlang Serialization** | Cross-language binary protocol | [xlang_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_serialization_spec.md) | [View](../specification/xlang_serialization_spec.md) | +| **Java Serialization** | Java-optimized protocol | [java_serialization_spec.md](https://github.com/apache/fory/blob/main/docs/specification/java_serialization_spec.md) | [View](../specification/java_serialization_spec.md) | +| **Row Format** | Row-based binary format | [row_format_spec.md](https://github.com/apache/fory/blob/main/docs/specification/row_format_spec.md) | [View](../specification/row_format_spec.md) | +| **Type Mapping** | Cross-language type conversion | [xlang_type_mapping.md](https://github.com/apache/fory/blob/main/docs/specification/xlang_type_mapping.md) | [View](../specification/xlang_type_mapping.md) | ## Compatibility @@ -190,11 +190,11 @@ We welcome contributions! Please read our [Contributing Guide](https://github.co **Ways to Contribute**: -- 🐛 Report bugs and issues -- 💡 Propose new features -- 📝 Improve documentation -- 🔧 Submit pull requests -- 🧪 Add test cases -- 📊 Share benchmarks +- Report bugs and issues +- Propose new features +- Improve documentation +- Submit pull requests +- Add test cases +- Share benchmarks See [Development Guide](../guide/DEVELOPMENT.md) for build instructions and development workflow. --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
