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 fcb79281cea8bb73edd081bb6be47e8c0c6fc660 Author: chaokunyang <[email protected]> AuthorDate: Sun Feb 8 02:38:03 2026 +0000 🔄 synced local 'docs/guide/' with remote 'docs/guide/' --- docs/guide/go/codegen.md | 22 ++++++++++++++++------ docs/guide/java/compression.md | 4 ++-- docs/guide/java/configuration.md | 12 ++++++------ docs/guide/java/schema-evolution.md | 2 +- docs/guide/python/configuration.md | 32 +++++++++++++++++--------------- docs/guide/python/index.md | 2 +- docs/guide/rust/schema-evolution.md | 2 +- docs/guide/rust/type-registration.md | 10 +++++----- 8 files changed, 49 insertions(+), 37 deletions(-) diff --git a/docs/guide/go/codegen.md b/docs/guide/go/codegen.md index 18850d7174..19cb384580 100644 --- a/docs/guide/go/codegen.md +++ b/docs/guide/go/codegen.md @@ -130,15 +130,25 @@ Strongly-typed serialization methods: ```go type User_ForyGenSerializer struct{} -func (User_ForyGenSerializer) WriteTyped(f *fory.Fory, buf *fory.ByteBuffer, v *User) error { +func NewSerializerFor_User() fory.Serializer { + return &User_ForyGenSerializer{} +} + +func (User_ForyGenSerializer) WriteTyped(ctx *fory.WriteContext, v *User) error { + buf := ctx.Buffer() buf.WriteInt64(v.ID) - fory.WriteString(buf, v.Name) + ctx.WriteString(v.Name) return nil } -func (User_ForyGenSerializer) ReadTyped(f *fory.Fory, buf *fory.ByteBuffer, v *User) error { - v.ID = buf.ReadInt64() - v.Name = fory.ReadString(buf) +func (User_ForyGenSerializer) ReadTyped(ctx *fory.ReadContext, v *User) error { + err := ctx.Err() + buf := ctx.Buffer() + v.ID = buf.ReadInt64(err) + v.Name = ctx.ReadString() + if ctx.HasError() { + return ctx.TakeError() + } return nil } ``` @@ -149,7 +159,7 @@ Serializers are registered in `init()`: ```go func init() { - fory.RegisterGenSerializer(User{}, User_ForyGenSerializer{}) + fory.RegisterSerializerFactory((*User)(nil), NewSerializerFor_User) } ``` diff --git a/docs/guide/java/compression.md b/docs/guide/java/compression.md index f79676a5bf..11cabe634c 100644 --- a/docs/guide/java/compression.md +++ b/docs/guide/java/compression.md @@ -98,8 +98,8 @@ String compression can be enabled via `ForyBuilder#withStringCompressed(true)`. | ------------------- | --------------------------------------------- | ------- | | `compressInt` | Enable int compression | `true` | | `compressLong` | Enable long compression | `true` | -| `compressIntArray` | Enable SIMD int array compression (Java 16+) | `true` | -| `compressLongArray` | Enable SIMD long array compression (Java 16+) | `true` | +| `compressIntArray` | Enable SIMD int array compression (Java 16+) | `false` | +| `compressLongArray` | Enable SIMD long array compression (Java 16+) | `false` | | `compressString` | Enable string compression | `false` | ## Performance Considerations diff --git a/docs/guide/java/configuration.md b/docs/guide/java/configuration.md index b0b2a93632..d13756360a 100644 --- a/docs/guide/java/configuration.md +++ b/docs/guide/java/configuration.md @@ -28,8 +28,8 @@ This page documents all configuration options available through `ForyBuilder`. | `timeRefIgnored` | Whether to ignore reference tracking of all time types registered in `TimeSerializers` and subclasses of those types when ref tracking is enabled. If ignored, ref tracking of every time type can be enabled by invoking `Fory#registerSerializer(Class, Serializer)`. For example, `fory.registerSerializer(Date.class, new DateSerializer(fory, true))`. Note that enabling ref tracking should happen before serializer codegen of any types which contain time [...] | `compressInt` | Enables or disables int compression for smaller size. [...] | `compressLong` | Enables or disables long compression for smaller size. [...] -| `compressIntArray` | Enables or disables SIMD-accelerated compression for int arrays when values can fit in smaller data types. Requires Java 16+. [...] -| `compressLongArray` | Enables or disables SIMD-accelerated compression for long arrays when values can fit in smaller data types. Requires Java 16+. [...] +| `compressIntArray` | Enables or disables SIMD-accelerated compression for int arrays when values can fit in smaller data types. Requires Java 16+. [...] +| `compressLongArray` | Enables or disables SIMD-accelerated compression for long arrays when values can fit in smaller data types. Requires Java 16+. [...] | `compressString` | Enables or disables string compression for smaller size. [...] | `classLoader` | The classloader should not be updated; Fory caches class metadata. Use `LoaderBinding` or `ThreadSafeFory` for classloader updates. [...] | `compatibleMode` | Type forward/backward compatibility config. Also Related to `checkClassVersion` config. `SCHEMA_CONSISTENT`: Class schema must be consistent between serialization peer and deserialization peer. `COMPATIBLE`: Class schema can be different between serialization peer and deserialization peer. They can add/delete fields independently. [See more](schema-evolution.md). [...] @@ -39,14 +39,14 @@ This page documents all configuration options available through `ForyBuilder`. | `requireClassRegistration` | Disabling may allow unknown classes to be deserialized, potentially causing security risks. [...] | `maxDepth` | Set max depth for deserialization, when depth exceeds, an exception will be thrown. This can be used to refuse deserialization DDOS attack. [...] | `suppressClassRegistrationWarnings` | Whether to suppress class registration warnings. The warnings can be used for security audit, but may be annoying, this suppression will be enabled by default. [...] -| `metaShareEnabled` | Enables or disables meta share mode. [...] -| `scopedMetaShareEnabled` | Scoped meta share focuses on a single serialization process. Metadata created or identified during this process is exclusive to it and is not shared with by other serializations. [...] +| `metaShareEnabled` | Enables or disables meta share mode. [...] +| `scopedMetaShareEnabled` | Scoped meta share focuses on a single serialization process. Metadata created or identified during this process is exclusive to it and is not shared with by other serializations. [...] | `metaCompressor` | Set a compressor for meta compression. Note that the passed MetaCompressor should be thread-safe. By default, a `Deflater` based compressor `DeflaterMetaCompressor` will be used. Users can pass other compressor such as `zstd` for better compression rate. [...] -| `deserializeUnknownClass` | Enables or disables deserialization/skipping of data for non-existent or unknown classes. [...] +| `deserializeUnknownClass` | Enables or disables deserialization/skipping of data for non-existent or unknown classes. [...] | `codeGenEnabled` | Disabling may result in faster initial serialization but slower subsequent serializations. [...] | `asyncCompilationEnabled` | If enabled, serialization uses interpreter mode first and switches to JIT serialization after async serializer JIT for a class is finished. [...] | `scalaOptimizationEnabled` | Enables or disables Scala-specific serialization optimization. [...] -| `copyRef` | When disabled, the copy performance will be better. But fory deep copy will ignore circular and shared reference. Same reference of an object graph will be copied into different objects in one `Fory#copy`. [...] +| `copyRef` | When disabled, the copy performance will be better. But fory deep copy will ignore circular and shared reference. Same reference of an object graph will be copied into different objects in one `Fory#copy`. [...] | `serializeEnumByName` | When Enabled, fory serialize enum by name instead of ordinal. [...] ## Example Configuration diff --git a/docs/guide/java/schema-evolution.md b/docs/guide/java/schema-evolution.md index c7db189658..4277b59d8f 100644 --- a/docs/guide/java/schema-evolution.md +++ b/docs/guide/java/schema-evolution.md @@ -73,7 +73,7 @@ Fory supports sharing type metadata (class name, field name, final field type in // .withLanguage(Language.JAVA) // .withRefTracking(false) // // share meta across serialization. -// .withMetaContextShare(true) +// .withMetaShare(true) // Not thread-safe fory. MetaContext context = xxx; diff --git a/docs/guide/python/configuration.md b/docs/guide/python/configuration.md index aa71f70855..ab6d52f730 100644 --- a/docs/guide/python/configuration.md +++ b/docs/guide/python/configuration.md @@ -33,35 +33,37 @@ class Fory: ref: bool = False, strict: bool = True, compatible: bool = False, - max_depth: int = 50 + max_depth: int = 50, + policy: DeserializationPolicy = None, + field_nullable: bool = False, + meta_compressor=None, ) ``` ## ThreadSafeFory Class -Thread-safe serialization interface using thread-local storage: +Thread-safe serialization interface using a pooled wrapper: ```python class ThreadSafeFory: def __init__( - self, - xlang: bool = False, - ref: bool = False, - strict: bool = True, - compatible: bool = False, - max_depth: int = 50 + self, fory_factory=None, **kwargs ) ``` ## Parameters -| Parameter | Type | Default | Description | -| ------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `xlang` | `bool` | `False` | Enable cross-language serialization. When `False`, enables Python-native mode supporting all Python objects. When `True`, enables cross-language mode compatible with Java, Go, Rust, etc. | -| `ref` | `bool` | `False` | Enable reference tracking for shared/circular references. Disable for better performance if your data has no shared references. | -| `strict` | `bool` | `True` | Require type registration for security. **Highly recommended** for production. Only disable in trusted environments. | -| `compatible` | `bool` | `False` | Enable schema evolution in cross-language mode, allowing fields to be added/removed while maintaining compatibility. | -| `max_depth` | `int` | `50` | Maximum deserialization depth for security, preventing stack overflow attacks. | +| Parameter | Type | Default | Description | +| ----------------- | ------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `xlang` | `bool` | `False` | Enable cross-language serialization. When `False`, enables Python-native mode supporting all Python objects. When `True`, enables cross-language mode compatible with Java, Go, Rust, etc. | +| `ref` | `bool` | `False` | Enable reference tracking for shared/circular references. Disable for better performance if your data has no shared references. | +| `strict` | `bool` | `True` | Require type registration for security. **Highly recommended** for production. Only disable in trusted environments. | +| `compatible` | `bool` | `False` | Enable schema evolution in cross-language mode, allowing fields to be added/removed while maintaining compatibility. | +| `max_depth` | `int` | `50` | Maximum deserialization depth for security, preventing stack overflow attacks. | +| `policy` | `DeserializationPolicy \| None` | `None` | Deserialization policy used for security checks. Strongly recommended when `strict=False`. | +| `field_nullable` | `bool` | `False` | In Python-native mode (`xlang=False`), treat dataclass fields as nullable by default. Ignored in xlang mode. | +| `meta_compressor` | `Any` | `None` | Optional metadata compressor used for compatible-mode metadata encoding. | +| `fory_factory` | `Callable \| None` | `None` | `ThreadSafeFory` factory hook. When set, `ThreadSafeFory` creates instances via this callback; otherwise it forwards `**kwargs` to `Fory` construction. | ## Key Methods diff --git a/docs/guide/python/index.md b/docs/guide/python/index.md index 795fc533d2..d0580943ed 100644 --- a/docs/guide/python/index.md +++ b/docs/guide/python/index.md @@ -80,7 +80,7 @@ pip install -e ".[dev,format]" ## Thread Safety -`pyfory` provides `ThreadSafeFory` for thread-safe serialization using thread-local storage: +`pyfory` provides `ThreadSafeFory` for thread-safe serialization using a pooled wrapper: ```python import pyfory diff --git a/docs/guide/rust/schema-evolution.md b/docs/guide/rust/schema-evolution.md index 07d175eff5..f58db6ad0a 100644 --- a/docs/guide/rust/schema-evolution.md +++ b/docs/guide/rust/schema-evolution.md @@ -155,7 +155,7 @@ enum NewEvent { KeyPress(String), // New variant } -let mut fory = Fory::builder().compatible().build(); +let mut fory = Fory::default().compatible(true); // Serialize with old schema let old_bytes = fory.serialize(&OldEvent::Click { x: 100, y: 200 })?; diff --git a/docs/guide/rust/type-registration.md b/docs/guide/rust/type-registration.md index 3e5c0dec03..0c209ce552 100644 --- a/docs/guide/rust/type-registration.md +++ b/docs/guide/rust/type-registration.md @@ -57,7 +57,7 @@ let mut fory = Fory::default() .xlang(true); // Register with namespace-based naming -fory.register_by_namespace::<MyStruct>("com.example", "MyStruct"); +fory.register_by_namespace::<MyStruct>("com.example", "MyStruct")?; ``` ## Register Custom Serializer @@ -66,12 +66,12 @@ For types that need custom serialization logic: ```rust let mut fory = Fory::default(); -fory.register_serializer::<CustomType>(100); +fory.register_serializer::<CustomType>(100)?; ``` -## Registration Order +## Registration Consistency -When using ID-based registration without explicit IDs, the registration order matters. Ensure consistent registration order between serialization and deserialization: +Rust registration APIs use explicit IDs or explicit namespace/type names. Keep the same registration mapping on serializer and deserializer peers: ```rust // Serializer side @@ -80,7 +80,7 @@ fory.register::<TypeA>(1)?; fory.register::<TypeB>(2)?; fory.register::<TypeC>(3)?; -// Deserializer side - MUST use same order +// Deserializer side - MUST use the same ID mapping let mut fory = Fory::default(); fory.register::<TypeA>(1)?; fory.register::<TypeB>(2)?; --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
