json.rs

Overview

The [json.rs](/projects/287/67742) file provides a JSON serializer implementation optimized for performance and flexibility. It adapts and extends functionality from Serde JSON's serialization logic (`src/value/ser.rs`) to fit within the project's modular serialization framework. The serializer converts Rust data structures implementing `serde::Serialize` into JSON text by writing directly to a generic output writer with support for customizable formatting (compact or pretty-printed).

Key features include:

Support for compact and pretty JSON formatting through pluggable Formatter implementations.
Efficient string escaping using architecture-specific SIMD optimizations (x86_64 with AVX512, SSE2, or generic fallback).
Partial implementation of Serde's Serializer trait, focusing on JSON types most relevant to the project.
Support for serializing sequences (arrays) and maps (objects) with controlled state management.
Integration with the project's writer abstraction (WriteExt + bytes::BufMut) for flexible output buffer management.

This file acts as a core serialization utility that other system components use to convert data into JSON format, enabling output to various sinks (files, network buffers, etc.) while maintaining high throughput and minimal allocations.

Detailed Documentation

Structs

`Serializer<W, F = CompactFormatter>`

A generic JSON serializer that writes serialized data to a writer `W` with formatting controlled by a formatter `F`.

Type Parameters:
- W: Writer type implementing WriteExt and bytes::BufMut traits.
- F: Formatter type implementing the Formatter trait (defaults to CompactFormatter).
Fields:
- writer: W — The output writer buffer.
- formatter: F — The formatter responsible for emitting JSON syntax and formatting.
Usage:

use json::Serializer;
use crate::serialize::writer::formatter::PrettyFormatter;

let writer = ...; // Some buffer implementing WriteExt + BufMut
let mut ser = Serializer::new(writer); // Compact JSON serializer

// Or for pretty-printed JSON:
let mut pretty_ser = Serializer::pretty(writer);

// Serialize a serializable value
value.serialize(&mut ser)?;

Methods:

Method	Description
`new(writer: W) -> Self`	Creates a new serializer with the compact formatter.
`pretty(writer: W) -> Self`	Creates a new serializer with the pretty formatter.
`with_formatter(writer: W, formatter: F) -> Self`	Creates a serializer with a custom formatter.

`Compound<'a, W, F>`

Helper struct used during serialization of sequences (arrays) and maps (objects).

Fields:
- ser: &'a mut Serializer<W, F> — Reference to the parent serializer.
- state: State — Current state tracking if the next element is the first or subsequent.
Role: Implements Serde's SerializeSeq and SerializeMap traits to manage serialization of array and object elements, handling commas and formatting between elements.

`MapKeySerializer<'a, W, F>`

A specialized serializer used exclusively to serialize map keys as JSON strings.

This serializer only supports serializing strings (serialize_str), and all other serialization methods are unreachable.
Ensures that map keys are serialized correctly as JSON strings, escaping as necessary.

Enum

`State`

Represents the state of serialization within compound structures:

First — Indicates the next element to serialize is the first element.
Rest — Indicates subsequent elements (after the first).

Used to determine when to insert commas or other separators.

Trait Implementations

`impl<W, F> ser::Serializer for &mut Serializer<W, F>`

Implements Serde's `Serializer` trait for mutable references to `Serializer`, enabling seamless serialization of Rust data structures to JSON.

Supported Types:
- Primitive types: bool, i32, i64, u32, u64, f32, f64, str and bytes.
- Option types via serialize_none and serialize_some.
- Sequences (serialize_seq) and maps (serialize_map).
Unsupported Types:
- Several integer sizes (i8, i16, i128, u8, u16, u128), characters, unit variants, newtype structs/variants, tuples, struct variants, and more are marked as unreachable!() since they are not implemented or expected in this serializer.
Special Handling:
- Floating point values that are NaN or infinite serialize as JSON null.
- Strings are serialized using a highly optimized escaping function depending on CPU capabilities.

`impl<W, F> ser::SerializeSeq for Compound<'_, W, F>`

Allows serialization of JSON arrays.

Methods:
- serialize_element<T>(&mut self, value: &T) -> Result<()>: Serializes an element, handling commas and formatting.
- end(self) -> Result<()>: Ends the array by writing the closing bracket.

`impl<W, F> ser::SerializeMap for Compound<'_, W, F>`

Allows serialization of JSON objects.

Methods:
- serialize_key<T>(&mut self, key: &T) -> Result<()>: Serializes a key string, applying escaping.
- serialize_value<T>(&mut self, value: &T) -> Result<()>: Serializes the corresponding value.
- serialize_entry<K, V>(&mut self, _key: &K, _value: &V) -> Result<()>: Unreachable (not used).
- end(self) -> Result<()>: Ends the object by writing the closing brace.

`impl<W, F> ser::Serializer for MapKeySerializer<'_, W, F>`

A restricted serializer for map keys that only supports string serialization.

All methods except serialize_str are unreachable, enforcing that map keys must serialize to strings.

Functions

`set_str_formatter_fn()`

Sets the string escaping function pointer (`STR_FORMATTER_FN`) at runtime based on detected CPU features, enabling selection between AVX512 and legacy implementations.

`format_escaped_str<W>(writer: &mut W, value: &str)`

Writes a JSON-escaped string to the writer using the fastest available implementation:

Uses AVX512, SSE2, generic SIMD, or scalar fallback depending on platform and compile-time features.
Reserves adequate space in the buffer before writing.
Advances the internal buffer pointer after writing.

`to_writer<W, T>(writer: W, value: &T) -> Result<()>`

Serializes a serializable value `value` to the provided writer using the compact formatter.

Convenience function for quick serialization to a writer.

`to_writer_pretty<W, T>(writer: W, value: &T) -> Result<()>`

Serializes a value to the provided writer using the pretty formatter.

Macros

`reserve_str!($writer, $value)`

Reserves buffer space in the writer for an escaped string, estimating the required capacity as `value.len() * 8 + 32`.

Important Implementation Details and Algorithms

Selective Serialization Support: The serializer explicitly marks many Serde methods as unreachable, streamlining the implementation to only support the expected JSON types in the system's use cases. This reduces complexity and improves maintainability.
Formatter Abstraction: The use of a generic Formatter trait allows the serializer to switch between compact and pretty-printed JSON outputs without changing serialization logic.
SIMD-Optimized String Escaping: The core string escaping logic uses architecture-specific SIMD instructions for fast processing of JSON strings, with runtime detection to choose the best implementation. This optimization is critical for high-performance JSON serialization of large text data.
Stateful Compound Serialization: The Compound struct manages the state of serializing arrays and objects, controlling delimiter insertion and formatting via the State enum.
Writer Buffer Management: The serializer interfaces with a custom writer trait (WriteExt + bytes::BufMut) that supports buffer reservation and unsafe writing, enabling zero-copy writes and minimal allocations.

Interactions with Other System Components

Formatter Module: The serializer depends on formatter implementations (CompactFormatter, PrettyFormatter) from crate::serialize::writer::formatter, which define how JSON tokens and whitespace are emitted.
Writer Abstraction: The serializer writes to any W implementing WriteExt and bytes::BufMut, allowing integration with various output sinks (memory buffers, file streams, network buffers).
Serde Serialization Framework: Implements Serde's Serializer trait, enabling seamless serialization of any Serialize data structure from the broader system.
String Escaping Module: Utilizes SIMD-accelerated string escaping implementations from crate::serialize::writer::str.
Error Handling: Uses Serde JSON's error types (serde_json::error::Error) for consistent error reporting.

Usage Examples

use serde::Serialize;
use crate::serialize::writer::buffer::Buffer; // Hypothetical writer buffer
use json::{Serializer, to_writer, to_writer_pretty};

#[derive(Serialize)]
struct Person {
    name: String,
    age: u32,
}

fn serialize_person_compact(person: &Person) -> Result<Vec<u8>, serde_json::error::Error> {
    let mut buffer = Buffer::new();
    to_writer(&mut buffer, person)?;
    Ok(buffer.into_inner())
}

fn serialize_person_pretty(person: &Person) -> Result<Vec<u8>, serde_json::error::Error> {
    let mut buffer = Buffer::new();
    to_writer_pretty(&mut buffer, person)?;
    Ok(buffer.into_inner())
}

Visual Diagram

flowchart TD
    Serializer -->|uses| Formatter
    Serializer -->|writes to| Writer[WriteExt + BufMut]
    Serializer -->|creates| Compound
    Compound -->|manages| State{First / Rest}
    Compound -->|implements| SerializeSeq
    Compound -->|implements| SerializeMap
    SerializeMap -->|uses| MapKeySerializer
    MapKeySerializer -->|serialize_str only| Serializer

    Formatter --> CompactFormatter
    Formatter --> PrettyFormatter

    Serializer --> format_escaped_str
    format_escaped_str -->|calls| SIMD_String_Escaping

    to_writer --> Serializer
    to_writer_pretty --> Serializer

Summary

The [json.rs](/projects/287/67742) file is a core JSON serialization module tailored for high-performance and configurable formatting. It integrates with Serde's serialization traits and the project's writer and formatter abstractions, providing a robust and optimized pathway from Rust data structures to JSON text output. Its design balances minimalism (by marking unsupported operations as unreachable) and performance (leveraging SIMD string escaping and zero-copy buffer writes). This file is foundational for any system components requiring JSON serialization capabilities.