This is an automated email from the ASF dual-hosted git repository.
chaokunyang pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/fory-site.git
The following commit(s) were added to refs/heads/main by this push:
new ba8b47ef39 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/'
ba8b47ef39 is described below
commit ba8b47ef393ddd10bd1e13df96bd78095115d12e
Author: chaokunyang <[email protected]>
AuthorDate: Tue Jan 27 14:03:04 2026 +0000
🔄 synced local 'docs/compiler/' with remote 'docs/compiler/'
---
docs/compiler/fdl-syntax.md | 85 +++++++++++++++++++++++++++-------------
docs/compiler/flatbuffers-idl.md | 29 ++++++++++++--
docs/compiler/generated-code.md | 10 ++++-
docs/compiler/protobuf-idl.md | 43 ++++++++++++--------
docs/compiler/type-system.md | 40 ++++++++++++++++++-
5 files changed, 156 insertions(+), 51 deletions(-)
diff --git a/docs/compiler/fdl-syntax.md b/docs/compiler/fdl-syntax.md
index a6604c08ba..c8d5707f9a 100644
--- a/docs/compiler/fdl-syntax.md
+++ b/docs/compiler/fdl-syntax.md
@@ -815,7 +815,7 @@ message Document {
Modifiers can be combined:
-```protobuf
+```fdl
message Example {
optional repeated string tags = 1; // Nullable list
repeated optional string aliases = 2; // Elements may be null
@@ -832,22 +832,41 @@ Modifiers before `repeated` apply to the
field/collection. Modifiers after
### Primitive Types
-| Type | Description | Size |
-| ----------- | --------------------------- | -------- |
-| `bool` | Boolean value | 1 byte |
-| `int8` | Signed 8-bit integer | 1 byte |
-| `int16` | Signed 16-bit integer | 2 bytes |
-| `int32` | Signed 32-bit integer | 4 bytes |
-| `int64` | Signed 64-bit integer | 8 bytes |
-| `float32` | 32-bit floating point | 4 bytes |
-| `float64` | 64-bit floating point | 8 bytes |
-| `string` | UTF-8 string | Variable |
-| `bytes` | Binary data | Variable |
-| `date` | Calendar date | Variable |
-| `timestamp` | Date and time with timezone | Variable |
+| Type | Description | Size |
+| --------------- | ----------------------------------------- | -------- |
+| `bool` | Boolean value | 1 byte |
+| `int8` | Signed 8-bit integer | 1 byte |
+| `int16` | Signed 16-bit integer | 2 bytes |
+| `int32` | Signed 32-bit integer (varint encoding) | 4 bytes |
+| `int64` | Signed 64-bit integer (varint encoding) | 8 bytes |
+| `uint8` | Unsigned 8-bit integer | 1 byte |
+| `uint16` | Unsigned 16-bit integer | 2 bytes |
+| `uint32` | Unsigned 32-bit integer (varint encoding) | 4 bytes |
+| `uint64` | Unsigned 64-bit integer (varint encoding) | 8 bytes |
+| `fixed_int32` | Signed 32-bit integer (fixed encoding) | 4 bytes |
+| `fixed_int64` | Signed 64-bit integer (fixed encoding) | 8 bytes |
+| `fixed_uint32` | Unsigned 32-bit integer (fixed encoding) | 4 bytes |
+| `fixed_uint64` | Unsigned 64-bit integer (fixed encoding) | 8 bytes |
+| `tagged_int64` | Signed 64-bit integer (tagged encoding) | 8 bytes |
+| `tagged_uint64` | Unsigned 64-bit integer (tagged encoding) | 8 bytes |
+| `float16` | 16-bit floating point | 2 bytes |
+| `float32` | 32-bit floating point | 4 bytes |
+| `float64` | 64-bit floating point | 8 bytes |
+| `string` | UTF-8 string | Variable |
+| `bytes` | Binary data | Variable |
+| `date` | Calendar date | Variable |
+| `timestamp` | Date and time with timezone | Variable |
+| `duration` | Duration | Variable |
+| `decimal` | Decimal value | Variable |
See [Type System](type-system.md) for complete type mappings.
+**Encoding notes:**
+
+- `int32`/`int64` and `uint32`/`uint64` use varint encoding by default.
+- Use `fixed_*` for fixed-width integer encoding.
+- Use `tagged_*` for tagged/hybrid encoding (64-bit only).
+
### Named Types
Reference other messages or enums by name:
@@ -1089,32 +1108,38 @@ enum Status {
### Field-Level Fory Options
-Field options are specified in brackets after the field number:
+Field options are specified in brackets after the field number (FDL uses `ref`
modifiers instead
+of bracket options for reference settings):
```protobuf
message Example {
- MyType friend = 1 [(fory).ref = true];
- string nickname = 2 [(fory).nullable = true];
- MyType data = 3 [(fory).ref = true, (fory).nullable = true];
+ ref MyType friend = 1;
+ string nickname = 2 [nullable = true];
+ ref MyType data = 3 [nullable = true];
+ ref(weak = true) MyType parent = 4;
}
```
| Option | Type | Description
|
| --------------------- | ---- |
--------------------------------------------------------- |
-| `ref` | bool | Enable reference tracking (sets ref flag)
|
+| `ref` | bool | Enable reference tracking (protobuf extension
option) |
| `nullable` | bool | Mark field as nullable (sets optional flag)
|
| `deprecated` | bool | Mark this field as deprecated
|
| `thread_safe_pointer` | bool | Rust only: use `Arc` (true) or `Rc` (false)
for ref types |
+| `weak_ref` | bool | C++/Rust only: generate weak pointers for
`ref` fields |
-**Note:** `[(fory).ref = true]` is equivalent to using the `ref` modifier:
`ref MyType friend = 1;`
-Field-level options always apply to the field/collection; use modifiers after
-`repeated` to control element behavior.
+**Note:** For FDL, use `ref` (and optional `ref(...)`) modifiers:
+`ref MyType friend = 1;`, `repeated ref(weak = true) Child children = 2;`,
+`map<string, ref(weak = true) Node> nodes = 3;`. For protobuf, use
+`[(fory).ref = true]` and `[(fory).weak_ref = true]`. `weak_ref` is a codegen
+hint for C++/Rust and is ignored by Java/Python/Go. It must be used with `ref`
+(`repeated ref` for collections, or `map<..., ref T>` for map values).
To use `Rc` instead of `Arc` in Rust for a specific field:
-```protobuf
+```fdl
message Graph {
- ref Node root = 1 [(fory).thread_safe_pointer = false];
+ ref(thread_safe = false) Node root = 1;
}
```
@@ -1169,6 +1194,7 @@ message ForyFieldOptions {
optional bool ref = 1;
optional bool nullable = 2;
optional bool deprecated = 3;
+ optional bool weak_ref = 4;
}
```
@@ -1207,9 +1233,14 @@ reserved_item := INTEGER | INTEGER 'to' INTEGER |
INTEGER 'to' 'max' | STRING
modifiers := { 'optional' | 'ref' } ['repeated' { 'optional' | 'ref' }]
field_type := primitive_type | named_type | map_type
-primitive_type := 'bool' | 'int8' | 'int16' | 'int32' | 'int64'
- | 'float32' | 'float64' | 'string' | 'bytes'
- | 'date' | 'timestamp'
+primitive_type := 'bool'
+ | 'int8' | 'int16' | 'int32' | 'int64'
+ | 'uint8' | 'uint16' | 'uint32' | 'uint64'
+ | 'fixed_int32' | 'fixed_int64' | 'fixed_uint32' |
'fixed_uint64'
+ | 'tagged_int64' | 'tagged_uint64'
+ | 'float16' | 'float32' | 'float64'
+ | 'string' | 'bytes'
+ | 'date' | 'timestamp' | 'duration' | 'decimal'
named_type := qualified_name
qualified_name := IDENTIFIER ('.' IDENTIFIER)* // e.g., Parent.Child
map_type := 'map' '<' field_type ',' field_type '>'
diff --git a/docs/compiler/flatbuffers-idl.md b/docs/compiler/flatbuffers-idl.md
index e12ac13612..638a4da49a 100644
--- a/docs/compiler/flatbuffers-idl.md
+++ b/docs/compiler/flatbuffers-idl.md
@@ -38,6 +38,27 @@ already have FlatBuffers schemas but want Fory-native
serialization and codegen.
- **Unions**: FlatBuffers `union` is translated into an FDL `union`. Case IDs
follow declaration order, starting at 1.
+## Fory-Specific Attributes
+
+FlatBuffers attributes use `key:value` syntax. To avoid conflicts with
+FlatBuffers tooling, Fory options use the `fory_` prefix and are stripped
during
+parsing:
+
+- `fory_ref:true` enables reference tracking for the field.
+- `fory_nullable:true` marks the field optional.
+- `fory_weak_ref:true` marks a weak reference and implies `ref`.
+- `fory_thread_safe_pointer:false` selects the non-thread-safe pointer flavor
+ for ref fields (it does not imply `ref`).
+
+Example:
+
+```fbs
+table TreeNode {
+ children: [TreeNode] (fory_ref: true);
+ parent: TreeNode (fory_weak_ref: true);
+}
+```
+
## Scalar Type Mapping
| FlatBuffers | Fory Primitive |
@@ -46,10 +67,10 @@ already have FlatBuffers schemas but want Fory-native
serialization and codegen.
| `ubyte` | `uint8` |
| `short` | `int16` |
| `ushort` | `uint16` |
-| `int` | `varint32` |
-| `uint` | `var_uint32` |
-| `long` | `varint64` |
-| `ulong` | `var_uint64` |
+| `int` | `int32` |
+| `uint` | `uint32` |
+| `long` | `int64` |
+| `ulong` | `uint64` |
| `float` | `float32` |
| `double` | `float64` |
| `bool` | `bool` |
diff --git a/docs/compiler/generated-code.md b/docs/compiler/generated-code.md
index 88b8674b3b..11c91348c8 100644
--- a/docs/compiler/generated-code.md
+++ b/docs/compiler/generated-code.md
@@ -618,8 +618,10 @@ pub fn register_types(fory: &mut Fory) -> Result<(),
fory::Error> {
}
```
-**Note:** Rust uses `Arc` by default for `ref` fields. Set
-`[(fory).thread_safe_pointer = false]` to generate `Rc` instead.
+**Note:** Rust uses `Arc` by default for `ref` fields. In FDL, use
+`ref(thread_safe = false)` to generate `Rc`, and `ref(weak = true)` to generate
+`ArcWeak`/`RcWeak`. For protobuf/IDL extensions, use
+`[(fory).thread_safe_pointer = false]` and `[(fory).weak_ref = true]`.
### Usage
@@ -764,6 +766,10 @@ int main() {
}
```
+**Note:** C++ uses `std::shared_ptr<T>` for `ref` fields. Set
+`ref(weak = true)` in FDL (or `[(fory).weak_ref = true]` in protobuf) to
generate
+`fory::serialization::SharedWeak<T>` for weak references.
+
## Generated Annotations Summary
### Java Annotations
diff --git a/docs/compiler/protobuf-idl.md b/docs/compiler/protobuf-idl.md
index 2732b34bff..0038ffcd4a 100644
--- a/docs/compiler/protobuf-idl.md
+++ b/docs/compiler/protobuf-idl.md
@@ -192,24 +192,35 @@ message TreeNode {
}
```
+When using protobuf IDL with the Fory compiler, you can opt into reference
+tracking via Fory extension options. `weak_ref` implies `ref`, while
+`thread_safe_pointer` does not:
+
+```protobuf
+message TreeNode {
+ TreeNode parent = 1 [(fory).weak_ref = true];
+ TreeNode child = 2 [(fory).ref = true, (fory).thread_safe_pointer = false];
+}
+```
+
### Type System
-| Type | Protocol Buffers
| FDL |
-| ---------- |
------------------------------------------------------------------------------------------------------
| --------------------------------- |
-| Boolean | `bool`
| `bool` |
-| Integers | `int32`, `int64`, `sint32`, `sint64`, `uint32`, `uint64`,
`fixed32`, `fixed64`, `sfixed32`, `sfixed64` | `int8`, `int16`, `int32`,
`int64` |
-| Floats | `float`, `double`
| `float32`, `float64` |
-| String | `string`
| `string` |
-| Binary | `bytes`
| `bytes` |
-| Timestamp | `google.protobuf.Timestamp`
| `timestamp` |
-| Date | Not built-in
| `date` |
-| Duration | `google.protobuf.Duration`
| Not built-in |
-| List | `repeated T`
| `repeated T` |
-| Map | `map<K, V>`
| `map<K, V>` |
-| Nullable | `optional T` (proto3)
| `optional T` |
-| Oneof | `oneof`
| `union` (case id = field number) |
-| Any | `google.protobuf.Any`
| Not supported |
-| Extensions | `extend`
| Not supported |
+| Type | Protocol Buffers
| FDL
|
+| ---------- |
------------------------------------------------------------------------------------------------------
|
-----------------------------------------------------------------------------------------------
|
+| Boolean | `bool`
| `bool`
|
+| Integers | `int32`, `int64`, `sint32`, `sint64`, `uint32`, `uint64`,
`fixed32`, `fixed64`, `sfixed32`, `sfixed64` | `int8`, `int16`, `int32`,
`int64`, `uint8`, `uint16`, `uint32`, `uint64`, `fixed_*`, `tagged_*` |
+| Floats | `float`, `double`
| `float32`, `float64`
|
+| String | `string`
| `string`
|
+| Binary | `bytes`
| `bytes`
|
+| Timestamp | `google.protobuf.Timestamp`
| `timestamp`
|
+| Date | Not built-in
| `date`
|
+| Duration | `google.protobuf.Duration`
| Not built-in
|
+| List | `repeated T`
| `repeated T`
|
+| Map | `map<K, V>`
| `map<K, V>`
|
+| Nullable | `optional T` (proto3)
| `optional T`
|
+| Oneof | `oneof`
| `union` (case id = field number)
|
+| Any | `google.protobuf.Any`
| Not supported
|
+| Extensions | `extend`
| Not supported
|
### Wire Format
diff --git a/docs/compiler/type-system.md b/docs/compiler/type-system.md
index 8a4ea01753..8cdfbfbcf2 100644
--- a/docs/compiler/type-system.md
+++ b/docs/compiler/type-system.md
@@ -49,7 +49,7 @@ bool is_active = 1;
### Integer Types
-FDL provides fixed-width signed integers:
+FDL provides fixed-width signed integers (varint encoding for 32/64-bit):
| FDL Type | Size | Range |
| -------- | ------ | ----------------- |
@@ -67,6 +67,24 @@ FDL provides fixed-width signed integers:
| `int32` | `int` | `pyfory.int32` | `int32` | `i32` | `int32_t` |
| `int64` | `long` | `pyfory.int64` | `int64` | `i64` | `int64_t` |
+FDL provides fixed-width unsigned integers (varint encoding for 32/64-bit):
+
+| FDL | Size | Range |
+| -------- | ------ | ------------- |
+| `uint8` | 8-bit | 0 to 255 |
+| `uint16` | 16-bit | 0 to 65,535 |
+| `uint32` | 32-bit | 0 to 2^32 - 1 |
+| `uint64` | 64-bit | 0 to 2^64 - 1 |
+
+**Language Mapping (Unsigned):**
+
+| FDL | Java | Python | Go | Rust | C++ |
+| -------- | ------- | --------------- | -------- | ----- | ---------- |
+| `uint8` | `short` | `pyfory.uint8` | `uint8` | `u8` | `uint8_t` |
+| `uint16` | `int` | `pyfory.uint16` | `uint16` | `u16` | `uint16_t` |
+| `uint32` | `long` | `pyfory.uint32` | `uint32` | `u32` | `uint32_t` |
+| `uint64` | `long` | `pyfory.uint64` | `uint64` | `u64` | `uint64_t` |
+
**Examples:**
```protobuf
@@ -93,6 +111,20 @@ class Counters:
large: int # int64 maps to native int
```
+### Integer Encoding Variants
+
+For 32/64-bit integers, FDL uses varint encoding by default. Use explicit
+types when you need fixed-width or tagged encoding:
+
+| FDL Type | Encoding | Notes |
+| --------------- | -------- | ------------------------ |
+| `fixed_int32` | fixed | Signed 32-bit |
+| `fixed_int64` | fixed | Signed 64-bit |
+| `fixed_uint32` | fixed | Unsigned 32-bit |
+| `fixed_uint64` | fixed | Unsigned 64-bit |
+| `tagged_int64` | tagged | Signed 64-bit (hybrid) |
+| `tagged_uint64` | tagged | Unsigned 64-bit (hybrid) |
+
### Floating-Point Types
| FDL Type | Size | Precision |
@@ -398,7 +430,11 @@ message TreeNode {
\*Java uses `@ForyField(ref = true)` annotation.
-Rust uses `Arc` by default; set `[(fory).thread_safe_pointer = false]` to use
`Rc`.
+Rust uses `Arc` by default; set `ref(thread_safe = false)` in FDL (or
+`[(fory).thread_safe_pointer = false]` in protobuf) to use `Rc`. Use
+`ref(weak = true)` in FDL (or `[(fory).weak_ref = true]` in protobuf) with
`ref`
+to generate weak pointer types: `ArcWeak`/`RcWeak` in Rust and
+`fory::serialization::SharedWeak<T>` in C++. Java/Python/Go ignore `weak_ref`.
## Type Compatibility Matrix
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
