Skip to content

Commit

Permalink
docs: translate some docs (#176)
Browse files Browse the repository at this point in the history 
Signed-off-by: yuluo-yx <[email protected]>
Co-authored-by: Shawn Yang <[email protected]>
  • Loading branch information
@yuluo-yx @chaokunyang
yuluo-yx and chaokunyang authored Aug 30, 2024
1 parent d29d716 commit c2d46fa
Show file tree
Hide file tree
Showing 2 changed files with 151 additions and 0 deletions.
95 changes: 95 additions & 0 deletions i18n/zh-CN/docusaurus-plugin-content-docs/current/guide/xlang_type_mapping.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
---
title: 多语言序列化的类型映射
sidebar_position: 3
id: xlang_type_mapping
---

注意：

- 有关类型定义，请参阅 [Spec 中的类型系统](https://fury.apache.org/docs/specification/fury_xlang_serialization_spec#type-systems)
- `int16_t[n]/vector<T>` 表示 `int16_t[n]/vector<int16_t>`.
- 跨语言序列化并不稳定，请勿在生产环境中使用。

## Type Mapping

| Fury 类型 | Fury 类型 ID | Java | Python | Javascript | C++ | Golang | Rust |
|--------------------|--------------|-----------------|----------------------|-----------------|--------------------------------|------------------|------------------|
| bool | 1 | bool/Boolean | bool | Boolean | bool | bool | bool |
| int8 | 2 | byte/Byte | int/pyfury.Int8 | Type.int8() | int8_t | int8 | i8 |
| int16 | 3 | short/Short | int/pyfury.Int16 | Type.int16() | int16_t | int16 | i6 |
| int32 | 4 | int/Integer | int/pyfury.Int32 | Type.int32() | int32_t | int32 | i32 |
| var_int32 | 5 | int/Integer | int/pyfury.VarInt32 | Type.varint32() | fury::varint32_t | fury.varint32 | fury::varint32 |
| int64 | 6 | long/Long | int/pyfury.Int64 | Type.int64() | int64_t | int64 | i64 |
| var_int64 | 7 | long/Long | int/pyfury.VarInt64 | Type.varint64() | fury::varint64_t | fury.varint64 | fury::varint64 |
| sli_int64 | 8 | long/Long | int/pyfury.SliInt64 | Type.sliint64() | fury::sliint64_t | fury.sliint64 | fury::sliint64 |
| float16 | 9 | float/Float | float/pyfury.Float16 | Type.float16() | fury::float16_t | fury.float16 | fury::f16 |
| float32 | 10 | float/Float | float/pyfury.Float32 | Type.float32() | float | float32 | f32 |
| float64 | 11 | double/Double | float/pyfury.Float64 | Type.float64() | double | float64 | f64 |
| string | 12 | String | str | String | string | string | String/str |
| enum | 13 | Enum subclasses | enum subclasses | / | enum | / | enum |
| list | 14 | List/Collection | list/tuple | array | vector | slice | Vec |
| set | 15 | Set | set | / | set | fury.Set | Set |
| map | 16 | Map | dict | Map | unordered_map | map | HashMap |
| duration | 17 | Duration | timedelta | Number | duration | Duration | Duration |
| timestamp | 18 | Instant | datetime | Number | std::chrono::nanoseconds | Time | DateTime |
| decimal | 19 | BigDecimal | Decimal | bigint | / | / | / |
| binary | 20 | byte[] | bytes | / | `uint8_t[n]/vector<T>` | `[n]uint8/[]T` | `Vec<uint8_t>` |
| array | 21 | array | np.ndarray | / | / | array/slice | Vec |
| bool_array | 22 | bool[] | ndarray(np.bool_) | / | `bool[n]` | `[n]bool/[]T` | `Vec<bool>` |
| int8_array | 23 | byte[] | ndarray(int8) | / | `int8_t[n]/vector<T>` | `[n]int8/[]T` | `Vec<i18>` |
| int16_array | 24 | short[] | ndarray(int16) | / | `int16_t[n]/vector<T>` | `[n]int16/[]T` | `Vec<i16>` |
| int32_array | 25 | int[] | ndarray(int32) | / | `int32_t[n]/vector<T>` | `[n]int32/[]T` | `Vec<i32>` |
| int64_array | 26 | long[] | ndarray(int64) | / | `int64_t[n]/vector<T>` | `[n]int64/[]T` | `Vec<i64>` |
| float16_array | 27 | float[] | ndarray(float16) | / | `fury::float16_t[n]/vector<T>` | `[n]float16/[]T` | `Vec<fury::f16>` |
| float32_array | 28 | float[] | ndarray(float32) | / | `float[n]/vector<T>` | `[n]float32/[]T` | `Vec<f32>` |
| float64_array | 29 | double[] | ndarray(float64) | / | `double[n]/vector<T>` | `[n]float64/[]T` | `Vec<f64>` |
| tensor | 30 | / | / | / | / | / | / |
| sparse tensor | 31 | / | / | / | / | / | / |
| arrow record batch | 32 | / | / | / | / | / | / |
| arrow table | 33 | / | / | / | / | / | / |

### 类型信息（目前尚未实现）

由于语言类型系统之间的差异，这些类型无法在语言之间一对一地映射。

如果用户看到一种语言中的一种类型对应 Apache Fury 类型系统中的多种类型。

例如：java 中的 `long` 类型对应 `int64/varint64/sliint64` 类型。类型为 `int64/varint64/sliint64` 这意味着该语言缺少某些类型，用户在使用 Fury 时必须提供额外的类型信息。

### 类型注解

如果类型是另一个类的字段，用户可以为类型的字段或整个类型提供 meta hints。
这些信息也可以用其他语言提供：

- java：使用注解；
- cpp：使用宏和模板；
- golang：使用 struct tag；
- python: 使用 typehint；
- rust：使用宏。

下面是一个例子：

- Java:

```java
class Foo {
@Int32Type(varint = true)
int f1;
List<@Int32Type(varint = true) Integer> f2;
}
```

- Python:

```python
class Foo:
f1: Int32Type(varint=True)
f2: List[Int32Type(varint=True)]
```

## 类型包装器

如果类型不是类的字段，用户必须用 Fury 类型来包装该类型，以传递额外的类型信息。

例如：假设 Apache Fury Java 提供了 `VarInt64` 类型，当用户调用 `fury.serialize(long_value)` 时，需要像下面这样调用
调用 `fury.serialize(new VarInt64(long_value))`。
56 changes: 56 additions & 0 deletions i18n/zh-CN/docusaurus-plugin-content-docs/current/introduction/introduction.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,56 @@
---
id: introduction
title: Apache Fury 介绍
sidebar_position: 1
---

Fury 是一个由 JIT（即时编译）和零拷贝提供支持的高性能多语言序列化框架。

## 协议

不同的场景有不同的序列化要求。Apache Fury 为这些需求设计并实现了多个二进制协议：

- 跨语言对象图协议：
- 跨语言自动序列化任何对象，无需 IDL 定义、Schema编译和对象协议转换；
- 支持共享引用和循环引用，无重复数据或递归错误；
- 原生支持对象多态。
- 原生 java/python 对象图协议：基于单一语言的完整类型系统进行高度优化；
- 行格式协议：缓存友好的二进制随机访问格式，支持跳过序列化和部分序列化，并且可以自动转换为列格式。

基于 fury 现有的 buffer、encoding、meta、codegen 和其他功能，可以轻松添加新协议。所有这些协议都共享相同的代码库，并且一个协议的优化可以被另一个协议重用。

## 兼容性

### Schema兼容性

Apache Fury java 对象图序列化支持类架构向前/向后兼容。序列化 Peer 节点和反序列化 Peer 节点可以独立添加/删除字段。

我们计划在[元数据压缩](https://github.com/apache/fury/issues/203)完成后支持跨语言序列化Schema兼容性。

### 二进制兼容性

我们仍在改进我们的协议，目前无法确保 fury 版本之间的二进制兼容性。如果您将来要升级 fury，请 `shade` fury。

在 fury 1.0 之前将确保二进制兼容性。

## 安全

静态序列化（如行格式）本质上是安全的。但动态对象图序列化支持反序列化未注册的类型，这可能会带来安全风险。

例如：反序列化可能会调用 `init` constructor 或 `equals`/ `hashCode` 方法，如果方法体中包含恶意代码，系统将处于危险之中。

Apache Fury 提供了一个类注册选项，并默认开启该选项，它只允许反序列化受信任的注册类型或内置类型。**不要禁用类注册或类注册检查，除非您可以确保您的环境确实是安全的**。如果您禁用了 class 注册选项，你需要自行负责序列化的安全性。

## 路线图

- 元压缩、自动元共享和跨语言兼容性；
- 用于 c++/golang 的 AOT 框架，用于静态生成代码；
- C++/Rust 对象图序列化支持；
- Golang/Rust/NodeJS 行存格式支持；
- ProtoBuffer 兼容性支持；
- 特征和模型序列化协议；
- 不断改进我们的序列化基础设施，以更快支持任何新的协议。

## 如何贡献

请阅读[贡献](https://github.com/apache/fury/blob/main/CONTRIBUTING.md)指南以获取有关如何贡献的说明。

0 comments on commit c2d46fa

Please sign in to comment.