(fory-site) branch add_kotlin_json_blog updated: docs: explain Kotlin JSON performance mechanisms

[ch...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

chaokunyang pushed a commit to branch add_kotlin_json_blog
in repository https://gitbox.apache.org/repos/asf/fory-site.git


The following commit(s) were added to refs/heads/add_kotlin_json_blog by this push:
     new 2b0c5f29806 docs: explain Kotlin JSON performance mechanisms
2b0c5f29806 is described below

commit 2b0c5f29806a6b3641f4fc261df6aeddc01ca80c
Author: chaokunyang <sh...@gmail.com>
AuthorDate: Tue Sep 8 02:06:38 2026 +0800

    docs: explain Kotlin JSON performance mechanisms
---
 blog/2026-09-07-fory_kotlin_json.md | 34 +++++++++++++++++++++++++++++++---
 1 file changed, 31 insertions(+), 3 deletions(-)

diff --git a/blog/2026-09-07-fory_kotlin_json.md b/blog/2026-09-07-fory_kotlin_json.md
index adc7deb1cf7..11329973030 100644
--- a/blog/2026-09-07-fory_kotlin_json.md
+++ b/blog/2026-09-07-fory_kotlin_json.md
@@ -170,11 +170,39 @@ data class Profile(
 
 In this example, the constructor parameter `id` maps to the JSON member `user_id`. Naming, formatting, Mixins, and custom codecs use Fory's shared annotation system. The [annotation guide](/docs/json/annotations#kotlin-use-site-targets) explains the supported Kotlin targets and how they combine.
 
-## Performance on Kotlin Models
+## How Fory JSON Achieves High Performance in Kotlin
+
+Fory's Kotlin support connects language-aware object mapping to an optimized JSON engine. The Kotlin module determines how a declared type should be represented and constructed; the shared runtime specializes the repeated work of reading and writing that representation. This design reduces model discovery, dispatch, text processing, and temporary allocation while preserving Kotlin's construction rules.
+
+### Preparing Kotlin Types Once
+
+When preparing a codec, the Kotlin module reads class metadata and resolves the constructor, property accessors, exact generic bindings, nullability, and parameters with compiler defaults. It translates this information into the runtime's object model. Retaining the runtime and `jsonTypeRef<T>()` allows subsequent operations to reuse the resolved codecs without repeating that metadata analysis.
+
+For the `Request` example, the prepared model already identifies `id` as required and records how to invoke the defaults for `label` and `retries`. Each read still checks which members are present and whether their values are valid. Default expressions execute when construction requires them; their results are not cached. The saved work is rediscovering the rules, while the rules themselves remain part of deserialization.
+
+### Generating Code for the Declared Model
+
+On a standard JDK, Fory generates and compiles codecs specialized for the target model. Generated writers use known property accessors and concrete primitive operations. Property names, quotes, colons, and separators can be prepared as encoded prefixes, allowing a field such as `"id":` to be emitted through packed writes instead of repeated escaping and individual character writes.
+
+Generated readers likewise specialize property matching and value decoding for the declared schema. They read constructor arguments, track absent parameters, and invoke the selected constructor or its compiler-generated default form. Common property matches use prepared names and direct input probes, reducing repeated name decoding and generic lookup. Other field orders and escaped names remain supported through fallback paths.
 
-Kotlin-aware construction does not require discovering the model anew for each operation. Fory prepares codecs for the declared schema and reuses that preparation across calls. On standard JDKs, generated codecs specialize property access, object framing, and primitive operations. Deserialization still invokes the model's constructor and enforces its type rules.
+This specialization gives the JVM concrete operations to optimize while preserving normal Kotlin initialization and validation. Runtime generation is enabled by default on standard JDKs; an interpreted path supports environments where runtime compilation is unavailable.
+
+### Processing Numbers and Text Directly
+
+Integer and long writers encode decimal digits directly into the output buffer, including the unsigned representations used by Kotlin. Floating-point writers use direct formatting paths where the JDK supports them. Common scalar writes therefore avoid creating a temporary String for each value. Integer readers also parse digits from the input directly, with syntax and overflow checks, instead of allocating a numeric substring first.
+
+Text processing uses bulk operations on common ASCII and Latin-1 paths. For example, the UTF-8 writer scans ASCII text in 8-byte or 16-byte groups to detect characters that require escaping, then copies eligible spans in bulk. Escapes and non-ASCII characters follow the appropriate encoding paths. Together with prepared property prefixes, this reduces per-character branching and copying overhead across the repeated names and text values in structured JSON.
+
+### Reusing Buffers and Keeping UTF-8 Direct
+
+A reusable `ForyJson` runtime retains execution states containing readers, writers, resolver caches, and output buffers. Each active operation has exclusive use of its borrowed state. Subsequent calls can reuse that working storage, reducing temporary allocation and garbage-collection pressure. Returning a String or byte array still allocates the requested result; buffer growth and constructing the deserialized object graph also require memory.
+
+The byte APIs preserve these paths through the complete operation. `toJsonBytes` writes JSON directly into a UTF-8 buffer, and `fromJson` reads UTF-8 bytes directly into the declared Kotlin model. Typed object mapping does not require an intermediate JSON tree or a String representation of the complete document. This matters when a service already receives or sends bytes, especially for the larger Users and Clients documents below.
+
+## Performance on Kotlin Models
 
-The JSON engine also reuses internal buffers and writes UTF-8 directly. Returning a String or byte array still allocates the requested result; buffer reuse reduces temporary work around that allocation. Together, these mechanisms support repeated operations on Kotlin models. The [Java JSON introduction](/blog/fory_json_fastest_java_json_framework) describes the shared engine's lower-level optimizations.
+The following benchmarks measure these mechanisms together on Kotlin models. MediaContent covers smaller structured messages, while Users and Clients exercise repeated records, collections, and JDK value types in documents of approximately 1 MB. The results measure complete library operations and do not isolate the contribution of each optimization.
 
 ### Benchmark Setup
 


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@fory.apache.org
For additional commands, e-mail: commits-help@fory.apache.org