Skip to content

Commit 5c0453f

Browse files
committed
docs: document Rust Standard Row support
1 parent 8302d19 commit 5c0453f

11 files changed

Lines changed: 29 additions & 34 deletions

File tree

README.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -802,6 +802,7 @@ int secondScore = scores.getInt32(1);
802802
For Java imports, nested structs, arrays/maps, Arrow integration, and partial
803803
deserialization, see the [Java row-format guide](docs/row-format/java.md),
804804
[Python row-format guide](docs/row-format/python.md),
805+
[C++ row-format guide](docs/row-format/cpp.md),
805806
[Rust row-format guide](docs/row-format/rust.md), and
806807
[row-format specification](docs/specification/row_format_spec.md).
807808

docs/introduction/product-model.md

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,12 @@ contract you need, then choose a runtime API.
2424

2525
## Serialization products
2626

27-
| Product | Data model | Interoperability boundary |
28-
| ---------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------- |
29-
| Binary Object Serialization: xlang mode | Portable object graphs | Shared wire format across supported runtimes |
30-
| Binary Object Serialization: native mode | Runtime-native object graphs | Same runtime family only |
27+
| Product | Data model | Interoperability boundary |
28+
| ---------------------------------------- | ------------------------------------ | ------------------------------------------------------------------------------- |
29+
| Binary Object Serialization: xlang mode | Portable object graphs | Shared wire format across supported runtimes |
30+
| Binary Object Serialization: native mode | Runtime-native object graphs | Same runtime family only |
3131
| Row Format | Random-access binary rows | Standard Row is shared by Java, Python, C++, and Rust; Compact Row is Java-only |
32-
| Fory JSON | Standard JSON mapped to Java objects | Java API with text interoperability |
32+
| Fory JSON | Standard JSON mapped to Java objects | Java API with text interoperability |
3333

3434
Xlang and native are sibling modes of Binary Object Serialization. Row Format and Fory JSON are
3535
separate products; neither is a third object-serialization mode.

docs/introduction/support-matrix.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ does not imply support for every Fory product.
2727
| Xlang object serialization | Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, Kotlin | One shared xlang wire format |
2828
| Native object serialization | Java, Python, C++, Go, Rust, Scala, Kotlin | Same runtime family only |
2929
| Standard Row Format | Java, Python, C++, Rust | Shared Standard Row layout |
30-
| Compact Row Format | Java | Java-only and currently unstable |
30+
| Compact Row Format | Java | Java-only compact layout |
3131
| Fory JSON | Java | Standard JSON text |
3232
| Fory compiler output | Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Swift, Dart, Scala, Kotlin | Generated models use supported Fory APIs |
3333
| Fory gRPC | Java, Python, C++, Go, Rust, JavaScript/TypeScript, C#, Dart, Scala, Kotlin | Peers must use matching generated Fory service contracts |

docs/json/index.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -59,3 +59,10 @@ Jackson object mapping:
5959

6060
Circular graphs eventually fail `maxDepth`; they are not reconstructed. Use Fory core's binary
6161
native or xlang protocol when reference identity or cycles are required.
62+
63+
## Related Java guides
64+
65+
For binary serialization, start with [Java Object Serialization](../object-serialization/java/index.md)
66+
and choose [xlang](../object-serialization/java/xlang.md) or
67+
[native](../object-serialization/java/native.md). Binary builder options are documented separately
68+
in [Java Configuration](../object-serialization/java/configuration.md).

docs/object-serialization/rust/core-api.md

Lines changed: 3 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -152,12 +152,9 @@ fory = { version = "1.5.0", features = ["chrono"] }
152152

153153
### Custom Types
154154

155-
| Macro | Description |
156-
| ----------------------- | ------------------------------------- |
157-
| `#[derive(ForyStruct)]` | Object graph serialization |
158-
| `#[derive(ForyRow)]` | Standard Row Format for named structs |
159-
160-
`ForyRow` has a separate type set and returns borrowed field views. Row reads and field access use `Result` to report invalid row data. See [Row Format](../../row-format/rust.md) for supported types, nullability, and examples.
155+
Use `#[derive(ForyStruct)]` for object graph serialization. The separate
156+
[Rust Row Format guide](../../row-format/rust.md) documents `#[derive(ForyRow)]` and its supported
157+
type set.
161158

162159
## Serialization APIs
163160

@@ -207,7 +204,6 @@ all supported carriers, and registration.
207204

208205
## Performance Tips
209206

210-
- **Selective Zero-Copy Access**: Row Format returns borrowed views for direct field and element access
211207
- **Buffer Pre-allocation**: Minimizes memory allocations during serialization
212208
- **Compact Encoding**: Variable-length encoding for space efficiency
213209
- **Little-Endian**: Optimized for modern CPU architectures

docs/object-serialization/rust/index.md

Lines changed: 1 addition & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,7 @@ license: |
1919
limitations under the License.
2020
---
2121

22-
**Apache Fory™** is a high-performance multi-language serialization framework. The Rust implementation uses compile-time code generation for object serialization and borrowed views for zero-copy Row Format access.
22+
**Apache Fory™** is a high-performance multi-language serialization framework. The Rust implementation uses compile-time code generation for object serialization.
2323

2424
The Rust implementation provides versatile and high-performance serialization with automatic memory management and compile-time type safety. It supports both xlang mode for cross-language payloads and native mode for Rust-only payloads.
2525

@@ -32,7 +32,6 @@ The Rust implementation provides versatile and high-performance serialization wi
3232
- **Circular references**: Automatic tracking of shared and circular references with `Rc`/`Arc` and weak pointers
3333
- **Polymorphic**: Serialize trait objects with `Box<dyn Trait>`, `Rc<dyn Trait>`, and `Arc<dyn Trait>`
3434
- **Schema evolution**: Compatible mode for independent schema changes
35-
- **Two formats**: Object graph serialization and the Standard Row Format shared with Java, C++, and Python
3635

3736
## Crates
3837

@@ -156,15 +155,6 @@ fn main() -> Result<(), Error> {
156155
- Schema evolution with compatible mode
157156
- Graph-like data structures with circular references
158157

159-
### Standard Row Format
160-
161-
- High-throughput data processing
162-
- Analytics workloads requiring fast field access
163-
- Memory-constrained environments
164-
- Real-time data streaming applications
165-
- Zero-copy field and collection access
166-
- Standard Row Format interchange with Java, C++, and Python
167-
168158
## Next Steps
169159

170160
- [Configuration](configuration.md) - Fory builder options and modes

docs/row-format/compact.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -19,8 +19,8 @@ license: |
1919
limitations under the License.
2020
---
2121

22-
Compact Row is a Java-only row encoding that reduces fixed-slot and null-bitmap overhead. It is
23-
currently unstable and is not wire-compatible with Standard Row.
22+
Compact Row is a Java-only row encoding that reduces fixed-slot and null-bitmap overhead. It is not
23+
wire-compatible with Standard Row.
2424

2525
## Create a compact encoder
2626

@@ -44,7 +44,7 @@ Reuse the encoder within one thread. Create separate encoders for concurrent thr
4444
- The null bitmap is omitted when no field is nullable.
4545
- Fixed-size nested structs can be stored inline.
4646

47-
Choose Compact Row only when every reader is Java and the space reduction justifies using an
48-
unstable format. Use [Standard Row](standard.md) for Java/Python/C++/Rust interchange.
47+
Choose Compact Row only when every reader is Java and the space reduction justifies the
48+
Java-specific layout. Use [Standard Row](standard.md) for Java/Python/C++/Rust interchange.
4949

5050
See the [Row Format specification](../specification/row_format_spec.md) for the exact binary layout.

docs/row-format/index.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -25,10 +25,10 @@ in-memory data processing.
2525

2626
## Choose a row family
2727

28-
| Family | Runtime support | Compatibility |
29-
| --------------------------- | ----------------------- | --------------------------------------------- |
30-
| [Standard Row](standard.md) | Java, Python, C++, Rust | Shared Standard Row layout |
31-
| [Compact Row](compact.md) | Java | Java-only, space-oriented, currently unstable |
28+
| Family | Runtime support | Compatibility |
29+
| --------------------------- | ----------------------- | -------------------------------- |
30+
| [Standard Row](standard.md) | Java, Python, C++, Rust | Shared Standard Row layout |
31+
| [Compact Row](compact.md) | Java | Java-only, space-oriented layout |
3232

3333
Use Binary Object Serialization when the goal is complete object reconstruction, references, or
3434
general application messaging. Use Row Format when a workload reads selected fields, nested arrays,

docs/row-format/rust.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,7 @@ fn main() -> Result<(), Error> {
9898
`ArrayView::iter` and `IntoIterator for &ArrayView` read elements on demand through the same checked path as `get`. Each item is a `Result`, so malformed data is reported when that element is visited.
9999

100100
`MapView` exposes `len`, `is_empty`, `key(index)`, and `value(index)`. Its `keys()` and `values()` array views remain available for independent iteration.
101+
Call `to_btree_map()` only when an owned lookup structure is more useful than indexed access; it materializes the map from the borrowed key and value views.
101102

102103
Struct, array, and map views are cheap `Copy` and `Clone` values. The `RowView` trait provides `as_bytes()`, which returns the exact encoded slice bound to the view, and `encoded_len()`, which returns its length. A nested view returns only its size-delimited child bytes.
103104

docs/row-format/standard.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,7 @@ or complete object reconstruction as its primary access pattern.
5151
| Java | Compatible | [Java](java.md) | Arrow conversion; interface and extension-type mapping |
5252
| Python | Compatible | [Python](python.md) | PyArrow schema and table conversion |
5353
| C++ | Compatible | [C++](cpp.md) | Native row readers and writers |
54-
| Rust | Compatible | [Rust](rust.md) | Borrowed struct, array, and map views |
54+
| Rust | Compatible | [Rust](rust.md) | Borrowed struct, array, and map views |
5555

5656
Use the runtime guides for installation, schema construction, encoding, random
5757
access, partial reads, and language-specific integrations.

0 commit comments

Comments
 (0)