You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@fory.apache.org by ch...@apache.org on 2026/06/03 22:23:22 UTC
(fory-site) 02/02: 🔄 synced local 'docs/compiler/' with remote 'docs/compiler/'
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
commit 5ec32785932b50ce193276ad968d467c5772e5f9
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Wed Jun 3 22:23:15 2026 +0000
🔄 synced local 'docs/compiler/' with remote 'docs/compiler/'
---
docs/compiler/flatbuffers-idl.md | 20 ++++++------
docs/compiler/protobuf-idl.md | 25 ++++++++-------
docs/compiler/schema-idl.md | 67 ++++++++++++++++++++--------------------
3 files changed, 57 insertions(+), 55 deletions(-)
diff --git a/docs/compiler/flatbuffers-idl.md b/docs/compiler/flatbuffers-idl.md
index 71a249f03e..f7aa298c24 100644
--- a/docs/compiler/flatbuffers-idl.md
+++ b/docs/compiler/flatbuffers-idl.md
@@ -156,20 +156,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:true` | For ref fields, select Rust `Arc`/`ArcWeak` instead of the default `Rc`/`RcWeak` |
+| 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 Rust `Rc`/`RcWeak` instead of the default `Arc`/`ArcWeak` |
Semantics:
- `fory_weak_ref:true` implies `ref`.
-- `fory_thread_safe_pointer` defaults to `false`, only takes effect when the field
+- `fory_thread_safe_pointer` defaults to `true`, 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.
+- In Rust codegen, `fory_weak_ref:true` uses `ArcWeak` by default and switches to
+ `RcWeak` only when `fory_thread_safe_pointer:false` is set.
- For list fields, `fory_ref:true` applies to list elements.
Example:
@@ -178,7 +178,7 @@ Example:
table Node {
parent: Node (fory_weak_ref: true);
children: [Node] (fory_ref: true);
- cached: Node (fory_ref: true, fory_thread_safe_pointer: true);
+ local: Node (fory_ref: true, fory_thread_safe_pointer: false);
}
```
diff --git a/docs/compiler/protobuf-idl.md b/docs/compiler/protobuf-idl.md
index 3a13fb8ff4..59f4c63a77 100644
--- a/docs/compiler/protobuf-idl.md
+++ b/docs/compiler/protobuf-idl.md
@@ -232,14 +232,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 | 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 |
+| 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 ref carrier selection; default `true` uses `Arc`/`ArcWeak`, explicit `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:
@@ -247,19 +247,20 @@ 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
+- `thread_safe_pointer` defaults to `true`; 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`.
+- In Rust codegen, `(fory).weak_ref = true` uses `ArcWeak` by default and
+ switches to `RcWeak` only when `(fory).thread_safe_pointer = false`.
### Option Examples by Shape
```protobuf
message Graph {
- Node root = 1 [(fory).ref = true, (fory).thread_safe_pointer = true];
+ Node root = 1 [(fory).ref = true];
repeated Node nodes = 2 [(fory).ref = true];
map<string, Node> cache = 3 [(fory).ref = true];
Node parent = 4 [(fory).weak_ref = true];
+ Node local = 5 [(fory).ref = true, (fory).thread_safe_pointer = false];
}
```
diff --git a/docs/compiler/schema-idl.md b/docs/compiler/schema-idl.md
index 5b99fc892a..89705883b0 100644
--- a/docs/compiler/schema-idl.md
+++ b/docs/compiler/schema-idl.md
@@ -1052,7 +1052,7 @@ 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: Rc<Node>` |
+| Rust | `parent: Node` | `parent: Arc<Node>` |
| C++ | `Node parent` | `std::shared_ptr<Node> parent` |
| C# | `Node parent` | `Node? parent` with runtime ref tracking |
| JavaScript/TypeScript | `parent: Node` | `parent: Node` (no ref distinction) |
@@ -1061,21 +1061,21 @@ message Node {
| Scala | `parent: Node` | `@Ref parent: Node` |
| Kotlin | `parent: Node` | `@Ref parent: Node?` |
-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
+Rust uses `Arc` and `ArcWeak` by default for ref-tracked fields. Use
+`ref(thread_safe=false)` when a generated Rust type must use single-threaded
+`Rc` or `RcWeak` carriers. 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>` |
+| Fory IDL | Rust type |
+| ----------------------------------------------- | --------------- |
+| `ref Node parent` | `Arc<Node>` |
+| `ref(thread_safe=false) Node parent` | `Rc<Node>` |
+| `ref(weak=true) Node parent` | `ArcWeak<Node>` |
+| `ref(weak=true, thread_safe=false) Node parent` | `RcWeak<Node>` |
#### `list`
@@ -1127,10 +1127,11 @@ 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<Rc<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<Arc<User>>` | `std::vector<std::shared_ptr<User>>` | `List<User>` + `@ListField(element: DeclaredType(ref: true))` | `List[User @Ref]` |
-Use `ref(thread_safe=true)` in Fory IDL (or `[(fory).thread_safe_pointer = true]` in protobuf)
-to generate `Arc` instead of `Rc` in Rust.
+Use `ref(thread_safe=false)` in Fory IDL (or
+`[(fory).thread_safe_pointer = false]` in protobuf) to generate `Rc` instead of
+`Arc` in Rust.
## Field Numbers
@@ -1339,15 +1340,15 @@ Underscore spellings for integer encoding are not FDL type names.
#### Any
-| Language | Type | Notes |
-| --------------------- | -------------- | -------------------- |
-| Java | `Object` | Runtime type written |
-| Python | `Any` | Runtime type written |
-| Go | `any` | Runtime type written |
-| Rust | `Box<dyn Any>` | Runtime type written |
-| C++ | `std::any` | Runtime type written |
-| JavaScript/TypeScript | `any` | Runtime type written |
-| Dart | `Object?` | Runtime type written |
+| Language | Type | Notes |
+| --------------------- | ---------------------------- | -------------------- |
+| Java | `Object` | Runtime type written |
+| Python | `Any` | Runtime type written |
+| Go | `any` | Runtime type written |
+| Rust | `Arc<dyn Any + Send + Sync>` | Runtime type written |
+| C++ | `std::any` | Runtime type written |
+| JavaScript/TypeScript | `any` | Runtime type written |
+| Dart | `Object?` | Runtime type written |
**Example:**
@@ -1369,15 +1370,15 @@ message Envelope [id=122] {
**Generated Code (`Envelope.payload`):**
-| Language | Generated Field Type |
-| --------------------- | ----------------------- |
-| Java | `Object payload` |
-| Python | `payload: Any` |
-| Go | `Payload any` |
-| Rust | `payload: Box<dyn Any>` |
-| C++ | `std::any payload` |
-| JavaScript/TypeScript | `payload: any` |
-| Dart | `Object? payload` |
+| Language | Generated Field Type |
+| --------------------- | ------------------------------------- |
+| Java | `Object payload` |
+| Python | `payload: Any` |
+| Go | `Payload any` |
+| Rust | `payload: Arc<dyn Any + Send + Sync>` |
+| C++ | `std::any payload` |
+| JavaScript/TypeScript | `payload: any` |
+| Dart | `Object? payload` |
**Notes:**
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org