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 <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
