Class SegmentBinaryWriter

java.lang.Object
express.mvp.roray.utils.memory.SegmentBinaryWriter
All Implemented Interfaces:
BinaryWriter
public final class SegmentBinaryWriter extends Object implements BinaryWriter
A high-performance, zero-copy BinaryWriter implementation using MemorySegment. This class is stateful and not thread-safe. A single instance should be used by a single thread at a time. It can be reused by calling the wrap() method.

  • Constructor Details

    • SegmentBinaryWriter

      public SegmentBinaryWriter()

  • Method Details

    • wrap

      public SegmentBinaryWriter wrap(MemorySegment segment)
      Wraps a MemorySegment, preparing the writer for use and resetting its position.
      Parameters:
      segment - The segment to write to.
      Returns:
      This writer instance for chaining.

    • position

      public long position()
      Description copied from interface: BinaryWriter
      Gets the current write offset in bytes.
      Specified by:
      position in interface BinaryWriter

    • position

      public void position(long newPosition)
      Description copied from interface: BinaryWriter
      Sets the current write offset in bytes.
      Specified by:
      position in interface BinaryWriter

    • remaining

      public long remaining()
      Description copied from interface: BinaryWriter
      Gets the number of remaining writable bytes.
      Specified by:
      remaining in interface BinaryWriter

    • writeByte

      public BinaryWriter writeByte(byte value)
      Specified by:
      writeByte in interface BinaryWriter

    • writeNullableByte

      public BinaryWriter writeNullableByte(Byte value)
      Specified by:
      writeNullableByte in interface BinaryWriter

    • writeBoolean

      public BinaryWriter writeBoolean(boolean value)
      Specified by:
      writeBoolean in interface BinaryWriter

    • writeShortBE

      public BinaryWriter writeShortBE(short value)
      Specified by:
      writeShortBE in interface BinaryWriter

    • writeIntBE

      public BinaryWriter writeIntBE(int value)
      Specified by:
      writeIntBE in interface BinaryWriter

    • writeLongBE

      public BinaryWriter writeLongBE(long value)
      Specified by:
      writeLongBE in interface BinaryWriter

    • writeShortLE

      public BinaryWriter writeShortLE(short value)
      Specified by:
      writeShortLE in interface BinaryWriter

    • writeIntLE

      public BinaryWriter writeIntLE(int value)
      Specified by:
      writeIntLE in interface BinaryWriter

    • writeLongLE

      public BinaryWriter writeLongLE(long value)
      Specified by:
      writeLongLE in interface BinaryWriter

    • writeFloatBE

      public BinaryWriter writeFloatBE(float value)
      Specified by:
      writeFloatBE in interface BinaryWriter

    • writeFloatLE

      public BinaryWriter writeFloatLE(float value)
      Specified by:
      writeFloatLE in interface BinaryWriter

    • writeVarInt

      public BinaryWriter writeVarInt(int value)
      Description copied from interface: BinaryWriter
      Writes a 32-bit integer in a variable-length format.
      Specified by:
      writeVarInt in interface BinaryWriter

    • writeVarIntFast

      public BinaryWriter writeVarIntFast(int value)
      Writes a variable-length integer using an optimized batch-write strategy.

      This method pre-computes all VarInt bytes and writes them in a single memory operation using a 64-bit write, avoiding the per-byte overhead of the standard writeVarInt(int) method.

      Performance: Approximately 5-10% faster than writeVarInt(int) for typical values by reducing memory operation count from 1-5 to exactly 1.

      Wire format: Identical to writeVarInt(int) - fully compatible.

      Parameters:
      value - The integer value to encode as VarInt.
      Returns:
      This writer instance, for chaining.
      See Also:

    • writeVarLongFast

      public BinaryWriter writeVarLongFast(long value)
      Writes a variable-length long using an optimized batch-write strategy.

      This method pre-computes all VarLong bytes and writes them in batched memory operations, avoiding the per-byte overhead of the standard writeVarLong(long) method.

      Parameters:
      value - The long value to encode as VarLong.
      Returns:
      This writer instance, for chaining.
      See Also:

    • writeVarLong

      public BinaryWriter writeVarLong(long value)
      Description copied from interface: BinaryWriter
      Writes a 64-bit integer in a variable-length format.
      Specified by:
      writeVarLong in interface BinaryWriter

    • writeString

      public BinaryWriter writeString(String value, MemorySegment scratchBuffer)
      Encodes and writes a String with zero heap allocations by using a provided off-heap scratch buffer for the UTF-8 encoding process.

      This method uses a two-pass encoding strategy:

      1. First pass: Encode UTF-8 bytes into the scratch buffer to determine exact byte length
      2. Second pass: Write VarInt length prefix, then copy encoded bytes to target segment

      Wire format: VarInt length prefix (1-5 bytes) followed by UTF-8 encoded bytes.

      Trade-offs:

      • Pro: Compact wire format (VarInt uses 1 byte for strings < 128 bytes)
      • Pro: Compatible with standard wire protocols
      • Con: Requires scratch buffer allocation/management
      • Con: Two memory operations (encode + copy)

      Alternative: For maximum encode performance when a fixed-size length prefix is acceptable, use writeStringFixedLength(String) which encodes directly to the target buffer in a single pass (approximately 15-25% faster for typical strings).

      Specified by:
      writeString in interface BinaryWriter
      Parameters:
      value - The String to write. Must not be null.
      scratchBuffer - An off-heap MemorySegment used for temporary encoding. Its size must be sufficient to hold the string's UTF-8 bytes (worst case: 3 bytes per char for BMP, 4 bytes for supplementary characters).
      Returns:
      This writer instance, for chaining.
      Throws:
      IllegalArgumentException - if value or scratchBuffer is null, or if scratch buffer is too small
      See Also:

    • writeStringFixedLength

      public BinaryWriter writeStringFixedLength(String value)
      Writes a String using single-pass UTF-8 encoding directly to the target buffer with a fixed 4-byte big-endian length prefix. This method achieves maximum encoding performance by eliminating the scratch buffer and intermediate copy required by writeString(String, MemorySegment).

      Wire format: Fixed 4-byte big-endian length prefix followed by UTF-8 encoded bytes.

      Algorithm:

      1. Reserve 4 bytes for length prefix at current position
      2. Encode UTF-8 bytes directly to target segment with bounds checking
      3. Write actual byte length back to reserved prefix position

      Trade-offs compared to writeString(String, MemorySegment):

      • Pro: ~15-25% faster encoding (single pass, no scratch buffer, no copy)
      • Pro: No scratch buffer required
      • Con: Fixed 4-byte overhead even for small strings (vs 1 byte for VarInt)
      • Con: Maximum string size limited to ~2GB (Integer.MAX_VALUE bytes)

      Use cases:

      • High-frequency encoding in hot paths where performance is critical
      • Internal/binary protocols where wire format overhead is acceptable
      • Scenarios where scratch buffer management is undesirable
      Parameters:
      value - The String to write. Must not be null.
      Returns:
      This writer instance, for chaining.
      Throws:
      IllegalArgumentException - if value is null or contains unpaired surrogates
      IndexOutOfBoundsException - if the target segment lacks capacity for the encoded string
      See Also:

    • writeNullableStringFixedLength

      public BinaryWriter writeNullableStringFixedLength(String value)
      Writes a nullable String using fixed-length encoding.

      Format: 1-byte presence flag, followed by fixed-length string data if present.

      Parameters:
      value - The String to write, or null.
      Returns:
      This writer instance, for chaining.
      See Also:

    • writeBytes

      public BinaryWriter writeBytes(byte[] value)
      Specified by:
      writeBytes in interface BinaryWriter

    • writeSegment

      public BinaryWriter writeSegment(MemorySegment source)
      Description copied from interface: BinaryWriter
      Writes all bytes from the source MemorySegment to this writer's underlying sink.
      Specified by:
      writeSegment in interface BinaryWriter
      Parameters:
      source - The MemorySegment to read from.
      Returns:
      This writer instance for chaining.

    • writeSegmentRaw

      public BinaryWriter writeSegmentRaw(MemorySegment source, long offset, long length)
      Description copied from interface: BinaryWriter
      Writes raw bytes from the source MemorySegment without a length prefix. This is useful when the length is already known or stored elsewhere.
      Specified by:
      writeSegmentRaw in interface BinaryWriter
      Parameters:
      source - The MemorySegment to copy from.
      offset - Starting offset in the source segment.
      length - Number of bytes to copy.
      Returns:
      This writer instance for chaining.

    • writeNullableString

      public BinaryWriter writeNullableString(String value, MemorySegment scratchBuffer)
      Specified by:
      writeNullableString in interface BinaryWriter

    • writeNullableIntBE

      public BinaryWriter writeNullableIntBE(Integer value)
      Specified by:
      writeNullableIntBE in interface BinaryWriter

    • writeDoubleBE

      public BinaryWriter writeDoubleBE(double value)
      Specified by:
      writeDoubleBE in interface BinaryWriter

    • writeDoubleLE

      public BinaryWriter writeDoubleLE(double value)
      Specified by:
      writeDoubleLE in interface BinaryWriter

    • writeNullableLongBE

      public BinaryWriter writeNullableLongBE(Long value)
      Specified by:
      writeNullableLongBE in interface BinaryWriter

    • writeNullableShortBE

      public BinaryWriter writeNullableShortBE(Short value)
      Specified by:
      writeNullableShortBE in interface BinaryWriter

    • writeNullableBytes

      public BinaryWriter writeNullableBytes(byte[] value)
      Specified by:
      writeNullableBytes in interface BinaryWriter

    • writeNullableDoubleLE

      public BinaryWriter writeNullableDoubleLE(Double value)
      Specified by:
      writeNullableDoubleLE in interface BinaryWriter

    • writeNullableBoolean

      public BinaryWriter writeNullableBoolean(Boolean value)
      Specified by:
      writeNullableBoolean in interface BinaryWriter

    • writeNullableFloatLE

      public BinaryWriter writeNullableFloatLE(Float value)
      Specified by:
      writeNullableFloatLE in interface BinaryWriter

    • writeNullableIntLE

      public BinaryWriter writeNullableIntLE(Integer value)
      Specified by:
      writeNullableIntLE in interface BinaryWriter

    • writeNullableDoubleBE

      public BinaryWriter writeNullableDoubleBE(Double value)
      Specified by:
      writeNullableDoubleBE in interface BinaryWriter

    • writeNullableLongLE

      public BinaryWriter writeNullableLongLE(Long value)
      Specified by:
      writeNullableLongLE in interface BinaryWriter

    • writeNullableFloatBE

      public BinaryWriter writeNullableFloatBE(Float value)
      Specified by:
      writeNullableFloatBE in interface BinaryWriter

    • skip

      public BinaryWriter skip(long bytesToSkip)
      Description copied from interface: BinaryWriter
      Advances the writer's position by the given number of bytes.
      Specified by:
      skip in interface BinaryWriter
      Parameters:
      bytesToSkip - The number of bytes to skip.
      Returns:
      This writer instance, for chaining.