sse2.rs

Overview

`sse2.rs` is a Rust source file that implements an optimized function for formatting and escaping strings using SIMD (Single Instruction, Multiple Data) instructions available on x86_64 processors with SSE2 support. The core functionality revolves around efficiently processing string data in 16-byte chunks, detecting characters that require escaping (such as backslashes, double quotes, and control characters), and writing an escaped version of the string to a destination buffer.

This file is primarily designed for performance-critical string escaping operations, likely as part of a larger serialization or text processing system—such as JSON encoding or similar tasks where escaping special characters in strings is necessary.

The implementation harnesses low-level CPU instructions for parallel byte comparisons and masking, significantly improving throughput over scalar (byte-by-byte) approaches.

Detailed Explanation

Function: format_escaped_str_impl_sse2_128

pub(crate) unsafe fn format_escaped_str_impl_sse2_128(
    odst: *mut u8,
    value_ptr: *const u8,
    value_len: usize,
) -> usize

Purpose

Formats a byte slice (string) pointed to by `value_ptr` of length `value_len` by escaping certain characters and writing the result into the buffer at `odst`. The output string is wrapped with double quotes (`"`). The function returns the total number of bytes written.

Parameters

• odst: *mut u8
  A mutable raw pointer to the destination buffer where the escaped string will be written.

• value_ptr: *const u8
  A raw pointer to the input string (byte slice) to be escaped.

• value_len: usize
  The length of the input string in bytes.

Returns

• usize — The total number of bytes written into the destination buffer (including the surrounding quotes).

Safety

• The function is marked unsafe because it performs unchecked pointer arithmetic and raw pointer dereferencing.

• The caller must ensure that odst points to a valid writable memory region large enough to hold the escaped string.

• value_ptr must point to a valid readable region of at least value_len bytes.

Usage Example

let input = b"Hello \"world\" \\ test";
let mut output = [0u8; 64];
let bytes_written = unsafe {
    format_escaped_str_impl_sse2_128(output.as_mut_ptr(), input.as_ptr(), input.len())
};
let escaped_str = std::str::from_utf8(&output[..bytes_written]).unwrap();
assert_eq!(escaped_str, "\"Hello \\\"world\\\" \\\\ test\"");

Implementation Details

SIMD Processing Using SSE2

• Uses 128-bit registers (__m128i) to process 16 bytes at a time.

• Loads chunks of 16 bytes from the input string using _mm_loadu_si128.

• Sets up SIMD registers containing the characters to detect:

  • Backslash (\) → ASCII 0x5C

  • Double quote (") → ASCII 0x22

  • Control characters (characters with ASCII code ≤ 0x1F), detected by subtracting 0x1F and checking for zero or negative results.

• Uses SIMD comparison instructions (_mm_cmpeq_epi8) to identify bytes that match these criteria.

• Combines the comparison results with _mm_or_si128 and extracts a bitmask with _mm_movemask_epi8.

• The bitmask indicates which bytes in the 16-byte chunk require escaping.

Processing Logic

• If the input length is less than 16 bytes (STRIDE), the function falls back to a scalar implementation (impl_format_scalar! macro).

• For inputs of length 16 or more:

  • The function iterates over each 16-byte chunk:

    • Loads the chunk.

    • Checks if any byte needs escaping.

    • If so, it identifies the first byte to escape, writes all previous bytes as-is, then writes the escaped byte using write_escape! macro.

    • Advances pointers accordingly.

  • After processing full chunks, it handles the last partial chunk carefully using a scratch buffer to avoid out-of-bounds access.

• The string is wrapped with double quotes at the start and end.

• Returns the total length of the written escaped string including quotes.

Macros and External Dependencies

• impl_format_scalar!: Likely a macro to perform scalar escaping on small inputs. Not defined in this file.

• write_escape!: Macro to write the escaped version of a character. Not defined here.

• trailing_zeros!: Macro or function to find the position of the first set bit in the mask, i.e., the index of the byte that needs escaping.

These macros and functions are expected to be part of the larger codebase and provide specialized implementations for escaping and bit manipulation.

Interaction with Other Parts of the System

• This file provides a low-level utility function for escaping strings, probably used by higher-level serialization modules such as JSON serializers.

• The use of SSE2 intrinsics ties this implementation to x86_64 architectures supporting SSE2 instructions.

• The macro dependencies imply integration into a codebase with flexible implementations for scalar and SIMD escaping.

• The output format (surrounding quotes and escaped special characters) suggests usage in contexts requiring strict string literal formatting.

• It interacts with memory management carefully, assuming that buffers are pre-allocated and large enough.

Summary

• Processes strings efficiently using SIMD SSE2 instructions.

• Detects and escapes backslashes, double quotes, and control characters.

• Falls back to scalar processing for small inputs.

• Uses advanced bitmasking and pointer arithmetic to maximize performance.

• Outputs an escaped string wrapped in double quotes.

• Requires unsafe code blocks for direct memory and SIMD intrinsics manipulation.

Mermaid Diagram: Flowchart of format_escaped_str_impl_sse2_128

flowchart TD
    Start([Start]) --> WriteQuoteStart["Write initial '\"' to dst"]
    WriteQuoteStart --> CheckLen{"value_len < 16?"}
    CheckLen -- Yes --> ScalarEscaping["impl_format_scalar!(dst, src, value_len)"]
    ScalarEscaping --> WriteQuoteEnd["Write final '\"' to dst"]
    WriteQuoteEnd --> Return["Return bytes written"]

    CheckLen -- No --> InitSIMD["Initialize SIMD registers:\n- blash '\\'\n- quote '\"'\n- x20 for control chars\n- zero"]
    InitSIMD --> LoopStart["Set pointers and nb = value_len\nStart main loop"]
    LoopStart --> LoopCondition{"nb >= 16?"}
    LoopCondition -- No --> HandleLastChunk["Handle last partial chunk using scratch buffer"]
    HandleLastChunk --> WriteQuoteEnd

    LoopCondition -- Yes --> LoadChunk["Load 16 bytes from src"]
    LoadChunk --> CompareMask["Compare for '\\', '\"', control chars\nGenerate mask"]
    CompareMask --> MaskCheck{"mask != 0?"}
    MaskCheck -- No --> AdvancePointers["Advance src/dst by 16\nnb -= 16"]
    AdvancePointers --> LoopStart

    MaskCheck -- Yes --> EscapeByte["Find first byte to escape\nWrite previous bytes\nWrite escaped byte"]
    EscapeByte --> UpdatePointers["Update pointers and nb"]
    UpdatePointers --> LoopStart

    Return --> End([End])

End of Documentation for sse2.rs