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 eafe8bb3bb 🔄 synced local 'docs/guide/' with remote 'docs/guide/'
eafe8bb3bb is described below
commit eafe8bb3bba4f3aa6249a77041ebf85a5fcab047
Author: chaokunyang <[email protected]>
AuthorDate: Tue Jan 27 03:02:24 2026 +0000
🔄 synced local 'docs/guide/' with remote 'docs/guide/'
---
docs/guide/cpp/field-configuration.md | 56 ++++++++++++++--------------
docs/guide/cpp/supported-types.md | 2 +-
docs/guide/xlang/field-reference-tracking.md | 29 +++++++-------
3 files changed, 45 insertions(+), 42 deletions(-)
diff --git a/docs/guide/cpp/field-configuration.md
b/docs/guide/cpp/field-configuration.md
index 7469f7bf15..0f78e1ad3c 100644
--- a/docs/guide/cpp/field-configuration.md
+++ b/docs/guide/cpp/field-configuration.md
@@ -103,7 +103,7 @@ struct Node {
FORY_STRUCT(Node, name, next);
```
-**Valid for:** `std::shared_ptr<T>`, `std::unique_ptr<T>`
+**Valid for:** `std::shared_ptr<T>`, `fory::serialization::SharedWeak<T>`,
`std::unique_ptr<T>`
**Note:** For nullable primitives or strings, use `std::optional<T>` instead:
@@ -123,7 +123,7 @@ Explicitly marks a pointer field as non-nullable. This is
the default for smart
fory::field<std::shared_ptr<Data>, 0, fory::not_null> data; // Must not be
nullptr
```
-**Valid for:** `std::shared_ptr<T>`, `std::unique_ptr<T>`
+**Valid for:** `std::shared_ptr<T>`, `fory::serialization::SharedWeak<T>`,
`std::unique_ptr<T>`
### fory::ref
@@ -138,7 +138,7 @@ struct Graph {
FORY_STRUCT(Graph, name, left, right);
```
-**Valid for:** `std::shared_ptr<T>` only (requires shared ownership)
+**Valid for:** `std::shared_ptr<T>`, `fory::serialization::SharedWeak<T>`
(requires shared ownership)
### fory::dynamic\<V\>
@@ -171,7 +171,7 @@ FORY_STRUCT(Zoo, animal, fixed_animal);
### Combining Tags
-Multiple tags can be combined for shared pointers:
+Multiple tags can be combined for shared pointers and SharedWeak:
```cpp
// Nullable + ref tracking
@@ -180,12 +180,13 @@ fory::field<std::shared_ptr<Node>, 0, fory::nullable,
fory::ref> link;
## Type Rules
-| Type | Allowed Options | Nullability
|
-| -------------------- | ------------------------------- |
---------------------------------- |
-| Primitives, strings | None | Use
`std::optional<T>` if nullable |
-| `std::optional<T>` | None | Inherently nullable
|
-| `std::shared_ptr<T>` | `nullable`, `ref`, `dynamic<V>` | Non-null by default
|
-| `std::unique_ptr<T>` | `nullable`, `dynamic<V>` | Non-null by default
|
+| Type | Allowed Options |
Nullability |
+| ------------------------------------ | ------------------------------- |
---------------------------------- |
+| Primitives, strings | None | Use
`std::optional<T>` if nullable |
+| `std::optional<T>` | None |
Inherently nullable |
+| `std::shared_ptr<T>` | `nullable`, `ref`, `dynamic<V>` |
Non-null by default |
+| `fory::serialization::SharedWeak<T>` | `nullable`, `ref`, `dynamic<V>` |
Non-null by default |
+| `std::unique_ptr<T>` | `nullable`, `dynamic<V>` |
Non-null by default |
## Complete Example
@@ -510,21 +511,21 @@ FORY_FIELD_CONFIG(DataV2,
### FORY_FIELD_CONFIG Options Reference
-| Method | Description | Valid
For |
-| ----------------- | ------------------------------------------------ |
-------------------------- |
-| `.nullable()` | Mark field as nullable | Smart
pointers, primitives |
-| `.ref()` | Enable reference tracking |
`std::shared_ptr` only |
-| `.dynamic(true)` | Force type info to be written (dynamic dispatch) | Smart
pointers |
-| `.dynamic(false)` | Skip type info (use declared type directly) | Smart
pointers |
-| `.varint()` | Use variable-length encoding |
`uint32_t`, `uint64_t` |
-| `.fixed()` | Use fixed-size encoding |
`uint32_t`, `uint64_t` |
-| `.tagged()` | Use tagged hybrid encoding |
`uint64_t` only |
-| `.compress(v)` | Enable/disable field compression | All
types |
+| Method | Description | Valid
For |
+| ----------------- | ------------------------------------------------ |
---------------------------------------------------- |
+| `.nullable()` | Mark field as nullable | Smart
pointers, primitives |
+| `.ref()` | Enable reference tracking |
`std::shared_ptr`, `fory::serialization::SharedWeak` |
+| `.dynamic(true)` | Force type info to be written (dynamic dispatch) | Smart
pointers |
+| `.dynamic(false)` | Skip type info (use declared type directly) | Smart
pointers |
+| `.varint()` | Use variable-length encoding |
`uint32_t`, `uint64_t` |
+| `.fixed()` | Use fixed-size encoding |
`uint32_t`, `uint64_t` |
+| `.tagged()` | Use tagged hybrid encoding |
`uint64_t` only |
+| `.compress(v)` | Enable/disable field compression | All
types |
## Default Values
- **Nullable**: Only `std::optional<T>` is nullable by default; all other
types (including `std::shared_ptr`) are non-nullable
-- **Ref tracking**: Disabled by default for all types (including
`std::shared_ptr`)
+- **Ref tracking**: Enabled by default for `std::shared_ptr<T>` and
`fory::serialization::SharedWeak<T>`, disabled for other types unless configured
You **need to configure fields** when:
@@ -552,12 +553,13 @@ FORY_FIELD_CONFIG(User,
### Default Values Summary
-| Type | Default Nullable | Default Ref Tracking |
-| -------------------- | ---------------- | -------------------- |
-| Primitives, `string` | `false` | `false` |
-| `std::optional<T>` | `true` | `false` |
-| `std::shared_ptr<T>` | `false` | `true` |
-| `std::unique_ptr<T>` | `false` | `false` |
+| Type | Default Nullable | Default Ref
Tracking |
+| ------------------------------------ | ---------------- |
-------------------- |
+| Primitives, `string` | `false` | `false`
|
+| `std::optional<T>` | `true` | `false`
|
+| `std::shared_ptr<T>` | `false` | `true`
|
+| `fory::serialization::SharedWeak<T>` | `false` | `true`
|
+| `std::unique_ptr<T>` | `false` | `false`
|
## Related Topics
diff --git a/docs/guide/cpp/supported-types.md
b/docs/guide/cpp/supported-types.md
index 3963852f2c..ab191a9ad0 100644
--- a/docs/guide/cpp/supported-types.md
+++ b/docs/guide/cpp/supported-types.md
@@ -140,7 +140,7 @@ auto bytes = fory.serialize(shared).value();
auto decoded = fory.deserialize<std::shared_ptr<Person>>(bytes).value();
```
-**With reference tracking enabled (`track_ref(true)`):**
+**With reference tracking enabled (default, `track_ref(true)`):**
- Shared objects are serialized once
- References to the same object are preserved
diff --git a/docs/guide/xlang/field-reference-tracking.md
b/docs/guide/xlang/field-reference-tracking.md
index b4d803a078..729f244000 100644
--- a/docs/guide/xlang/field-reference-tracking.md
+++ b/docs/guide/xlang/field-reference-tracking.md
@@ -113,13 +113,13 @@ By default, **most fields do not track references** even
when global `refTrackin
### Default Behavior by Language
-| Language | Default Ref Tracking | Types That Track Refs by Default |
-| -------- | -------------------- | --------------------------------- |
-| Java | No | None (use annotation to enable) |
-| Python | No | None (use annotation to enable) |
-| Go | No | None (use `fory:"ref"` to enable) |
-| C++ | No | `std::shared_ptr<T>` |
-| Rust | No | `Rc<T>`, `Arc<T>`, `Weak<T>` |
+| Language | Default Ref Tracking | Types That Track Refs by Default
|
+| -------- | -------------------- |
---------------------------------------------------------- |
+| Java | No | None (use annotation to enable)
|
+| Python | No | None (use annotation to enable)
|
+| Go | No | None (use `fory:"ref"` to enable)
|
+| C++ | Yes | `std::shared_ptr<T>`,
`fory::serialization::SharedWeak<T>` |
+| Rust | No | `Rc<T>`, `Arc<T>`, `Weak<T>`
|
### Customizing Per-Field Ref Tracking
@@ -146,18 +146,19 @@ public class Document {
struct Document {
std::string title;
- // shared_ptr tracks refs by default
+ // shared_ptr/SharedWeak track refs by default
std::shared_ptr<Author> author;
+ fory::serialization::SharedWeak<Data> data;
- // Explicitly enable ref tracking
- fory::field<std::vector<Tag>, 1, fory::track_ref<true>> tags;
-
- // Explicitly disable ref tracking
- fory::field<std::shared_ptr<Data>, 2, fory::track_ref<false>> data;
+ // Explicitly mark ref tracking when using field wrappers (optional)
+ fory::field<std::shared_ptr<Tag>, 1, fory::ref> tag_owner;
};
-FORY_STRUCT(Document, title, author, tags, data);
+FORY_STRUCT(Document, title, author, data, tag_owner);
```
+To disable reference tracking for C++ entirely, set
+`Fory::builder().track_ref(false)` on the serializer.
+
#### Rust: Field Attributes
```rust
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
