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 d799124621 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/'
d799124621 is described below
commit d79912462186a812b8250d9a8d07177ee8f38fec
Author: chaokunyang <[email protected]>
AuthorDate: Mon May 18 04:30:04 2026 +0000
🔄 synced local 'docs/compiler/' with remote 'docs/compiler/'
---
docs/compiler/flatbuffers-idl.md | 19 +++++++++++--------
docs/compiler/protobuf-idl.md | 22 +++++++++++++---------
docs/compiler/schema-idl.md | 24 ++++++++++++++++++------
3 files changed, 42 insertions(+), 23 deletions(-)
diff --git a/docs/compiler/flatbuffers-idl.md b/docs/compiler/flatbuffers-idl.md
index c8e7945701..90600640b4 100644
--- a/docs/compiler/flatbuffers-idl.md
+++ b/docs/compiler/flatbuffers-idl.md
@@ -135,17 +135,20 @@ FlatBuffers metadata attributes use `key:value`. For
Fory-specific options, use
### Supported Field Attributes
-| FlatBuffers Attribute | Effect in Fory
|
-| -------------------------------- |
----------------------------------------------------- |
-| `fory_ref:true` | Enable reference tracking for the field
|
-| `fory_nullable:true` | Mark field optional/nullable
|
-| `fory_weak_ref:true` | Enable weak reference semantics and
implies `ref` |
-| `fory_thread_safe_pointer:false` | For ref fields, select non-thread-safe
pointer flavor |
+| FlatBuffers Attribute | Effect in Fory
|
+| ------------------------------- |
--------------------------------------------------------------------------------
|
+| `fory_ref:true` | Enable reference tracking for the field
|
+| `fory_nullable:true` | Mark field optional/nullable
|
+| `fory_weak_ref:true` | Enable weak reference semantics and
implies `ref` |
+| `fory_thread_safe_pointer:true` | For ref fields, select Rust
`Arc`/`ArcWeak` instead of the default `Rc`/`RcWeak` |
Semantics:
- `fory_weak_ref:true` implies `ref`.
-- `fory_thread_safe_pointer` only takes effect when the field is ref-tracked.
+- `fory_thread_safe_pointer` defaults to `false`, only takes effect when the
field
+ is ref-tracked, and does not change the wire format.
+- In Rust codegen, `fory_weak_ref:true` uses `RcWeak` by default and switches
to
+ `ArcWeak` only when `fory_thread_safe_pointer:true` is also set.
- For list fields, `fory_ref:true` applies to list elements.
Example:
@@ -154,7 +157,7 @@ Example:
table Node {
parent: Node (fory_weak_ref: true);
children: [Node] (fory_ref: true);
- cached: Node (fory_ref: true, fory_thread_safe_pointer: false);
+ cached: Node (fory_ref: true, fory_thread_safe_pointer: true);
}
```
diff --git a/docs/compiler/protobuf-idl.md b/docs/compiler/protobuf-idl.md
index 58bb92bf6e..0105a89558 100644
--- a/docs/compiler/protobuf-idl.md
+++ b/docs/compiler/protobuf-idl.md
@@ -229,14 +229,14 @@ message TreeNode {
### Field-Level Options
-| Option | Type | Description
|
-| ---------------------------- | ------ |
----------------------------------------------------- |
-| `(fory).ref` | bool | Enable reference tracking for this
field |
-| `(fory).nullable` | bool | Treat field as nullable (`optional`)
|
-| `(fory).weak_ref` | bool | Generate weak pointer semantics
(C++/Rust codegen) |
-| `(fory).thread_safe_pointer` | bool | Rust pointer flavor for ref fields
(`Arc` vs `Rc`) |
-| `(fory).deprecated` | bool | Mark field as deprecated
|
-| `(fory).type` | string | Primitive override for tagged 64-bit
integer encoding |
+| Option | Type | Description
|
+| ---------------------------- | ------ |
--------------------------------------------------------------------------- |
+| `(fory).ref` | bool | Enable reference tracking for this
field |
+| `(fory).nullable` | bool | Treat field as nullable (`optional`)
|
+| `(fory).weak_ref` | bool | Generate weak pointer semantics
(C++/Rust codegen) |
+| `(fory).thread_safe_pointer` | bool | Use Rust `Arc`/`ArcWeak` for ref
fields; default `false` uses `Rc`/`RcWeak` |
+| `(fory).deprecated` | bool | Mark field as deprecated
|
+| `(fory).type` | string | Primitive override for tagged 64-bit
integer encoding |
Reference option behavior:
@@ -244,12 +244,16 @@ Reference option behavior:
- For `repeated` fields, `(fory).ref = true` applies to list elements.
- For `map<K, V>` fields, `(fory).ref = true` applies to map values.
- `weak_ref` and `thread_safe_pointer` are codegen hints for C++/Rust.
+- `thread_safe_pointer` defaults to `false`; it changes only the generated Rust
+ pointer carrier and does not change the wire format.
+- In Rust codegen, `(fory).weak_ref = true` uses `RcWeak` by default and
switches
+ to `ArcWeak` only when `(fory).thread_safe_pointer = true`.
### Option Examples by Shape
```protobuf
message Graph {
- Node root = 1 [(fory).ref = true, (fory).thread_safe_pointer = false];
+ Node root = 1 [(fory).ref = true, (fory).thread_safe_pointer = true];
repeated Node nodes = 2 [(fory).ref = true];
map<string, Node> cache = 3 [(fory).ref = true];
Node parent = 4 [(fory).weak_ref = true];
diff --git a/docs/compiler/schema-idl.md b/docs/compiler/schema-idl.md
index 50364d6c27..799b8fb0ee 100644
--- a/docs/compiler/schema-idl.md
+++ b/docs/compiler/schema-idl.md
@@ -966,16 +966,28 @@ message Node {
| Java | `Node parent` | `Node parent` with `@Ref` |
| Python | `parent: Node` | `parent: Node = pyfory.field(ref=True)` |
| Go | `Parent Node` | `Parent *Node` with `fory:"ref"` |
-| Rust | `parent: Node` | `parent: Arc<Node>` |
+| Rust | `parent: Node` | `parent: Rc<Node>` |
| C++ | `Node parent` | `std::shared_ptr<Node> parent` |
| JavaScript | `parent: Node` | `parent: Node` (no ref distinction) |
| Dart | `Node parent` | `Node parent` with `@ForyField(ref: true)` |
| Scala | `parent: Node` | `@Ref parent: Node` |
-Rust uses `Arc` by default; use `ref(thread_safe=false)` or `ref(weak=true)`
-to customize pointer types. For protobuf option syntax, see
+Rust uses `Rc` and `RcWeak` by default for ref-tracked fields. Use
+`ref(thread_safe=true)` when the generated Rust type must use `Arc` or
+`ArcWeak` for cross-thread shared ownership. This setting is a Rust codegen
+carrier choice; it does not change the wire format or make the referenced value
+itself thread-safe. For protobuf option syntax, see
[Protocol Buffers IDL Support](protobuf-idl.md#field-level-options).
+Rust pointer carrier mapping:
+
+| Fory IDL | Rust type |
+| ---------------------------------------------- | --------------- |
+| `ref Node parent` | `Rc<Node>` |
+| `ref(thread_safe=true) Node parent` | `Arc<Node>` |
+| `ref(weak=true) Node parent` | `RcWeak<Node>` |
+| `ref(weak=true, thread_safe=true) Node parent` | `ArcWeak<Node>` |
+
#### `list`
Marks the field as an ordered collection:
@@ -1022,10 +1034,10 @@ accepted as an alias for `list`.
| ----------------------- | ---------------------------------- |
--------------------- | ----------------------- | --------------------- |
----------------------------------------- |
------------------------------------------------------------- |
---------------------- |
| `optional list<string>` | `@Nullable List<String>` |
`Optional[List[str]]` | `[]string` + `nullable` | `Option<Vec<String>>` |
`std::optional<std::vector<std::string>>` | `List<String>?`
| `Option[List[String]]` |
| `list<optional string>` | `List<String>` (nullable elements) |
`List[Optional[str]]` | `[]*string` | `Vec<Option<String>>` |
`std::vector<std::optional<std::string>>` | `List<String?>`
| `List[Option[String]]` |
-| `list<ref User>` | `List<@Ref User>` | `List[User]`
| `[]*User` + `ref=false` | `Vec<Arc<User>>` |
`std::vector<std::shared_ptr<User>>` | `List<User>` + `@ListField(element:
DeclaredType(ref: true))` | `List[User @Ref]` |
+| `list<ref User>` | `List<@Ref User>` | `List[User]`
| `[]*User` + `ref=false` | `Vec<Rc<User>>` |
`std::vector<std::shared_ptr<User>>` | `List<User>` + `@ListField(element:
DeclaredType(ref: true))` | `List[User @Ref]` |
-Use `ref(thread_safe=false)` in Fory IDL (or `[(fory).thread_safe_pointer =
false]` in protobuf)
-to generate `Rc` instead of `Arc` in Rust.
+Use `ref(thread_safe=true)` in Fory IDL (or `[(fory).thread_safe_pointer =
true]` in protobuf)
+to generate `Arc` instead of `Rc` in Rust.
## Field Numbers
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
