perf: add buffer fast-path for vector serializers

Author: mykaul

cassandra/serializers.pyx

@@ -219,12 +219,7 @@ cdef class SerVectorType(Serializer):
             self.type_code = 0
 
     cpdef bytes serialize(self, object value, int protocol_version):
-        # Normalize to tuple/list so indexing works for any iterable.
-        # The Python VectorType.serialize() only requires len() + iteration,
-        # so we must accept the same inputs.  Avoid a copy if value is
-        # already a list or tuple (common fast path for embeddings).
-        if not isinstance(value, (list, tuple)):
-            value = tuple(value)
+        cdef object result
         cdef Py_ssize_t v_length = len(value)
         if v_length != self.vector_size:
             raise ValueError(
@@ -233,6 +228,28 @@ cdef class SerVectorType(Serializer):
                     self.vector_size, self.subtype.typename,
                     self.vector_size, v_length))
 
+        if self.type_code == 1:
+            result = self._serialize_float_buffer(value)
+            if result is not None:
+                return result
+        elif self.type_code == 2:
+            result = self._serialize_double_buffer(value)
+            if result is not None:
+                return result
+        elif self.type_code == 3:
+            result = self._serialize_int32_buffer(value)
+            if result is not None:
+                return result
+
+        # Keep indexable sequences on the fast path. Fall back to tuple()
+        # only for iterable-only inputs so the Cython path still matches
+        # Python VectorType.serialize() input semantics.
+        if v_length != 0 and not isinstance(value, (list, tuple)):
+            try:
+                value[0]
+            except (TypeError, KeyError, IndexError):
+                value = tuple(value)
+
         if self.type_code == 1:
             return self._serialize_float(value)
         elif self.type_code == 2:
@@ -245,8 +262,8 @@ cdef class SerVectorType(Serializer):
     cdef inline bytes _serialize_float(self, object values):
         """Serialize a list of floats into a contiguous big-endian buffer.
 
-        ``values`` is already a tuple (normalized in ``serialize()``), so
-        indexing is always safe and fast.
+        ``values`` is already an indexable sequence (normalized in
+        ``serialize()``), so integer indexing is safe and fast.
         """
         cdef Py_ssize_t i
         cdef Py_ssize_t buf_size = self.vector_size * 4
@@ -277,11 +294,54 @@ cdef class SerVectorType(Serializer):
 
         return result
 
+    cdef inline object _serialize_float_buffer(self, object values):
+        """Fast path for contiguous float32 buffers (e.g. numpy float32 arrays).
+
+        No ``_check_float_range`` is needed: the typed memoryview
+        ``float[::1]`` constrains values to C float (IEEE 754 float32),
+        so overflow is impossible by definition.  Returns ``None`` when
+        *values* does not support the buffer protocol with the required
+        format, letting the caller fall through to the element-wise path.
+        """
+        cdef float[::1] view
+        cdef Py_ssize_t buf_size = self.vector_size * 4
+        cdef Py_ssize_t i
+        cdef object result
+        cdef char *buf
+        cdef char *dst
+        cdef char *src
+        cdef float val
+
+        try:
+            view = values
+        except (TypeError, ValueError):
+            return None
+
+        if buf_size == 0:
+            return b""
+
+        result = PyBytes_FromStringAndSize(NULL, buf_size)
+        buf = PyBytes_AS_STRING(result)
+
+        if is_little_endian:
+            for i in range(self.vector_size):
+                val = view[i]
+                src = <char *>&val
+                dst = buf + i * 4
+                dst[0] = src[3]
+                dst[1] = src[2]
+                dst[2] = src[1]
+                dst[3] = src[0]
+        else:
+            memcpy(buf, &view[0], buf_size)
+
+        return result
+
     cdef inline bytes _serialize_double(self, object values):
         """Serialize a list of doubles into a contiguous big-endian buffer.
 
-        ``values`` is already a tuple (normalized in ``serialize()``), so
-        indexing is always safe and fast.
+        ``values`` is already an indexable sequence (normalized in
+        ``serialize()``), so integer indexing is safe and fast.
         """
         cdef Py_ssize_t i
         cdef Py_ssize_t buf_size = self.vector_size * 8
@@ -313,11 +373,55 @@ cdef class SerVectorType(Serializer):
 
         return result
 
+    cdef inline object _serialize_double_buffer(self, object values):
+        """Fast path for contiguous float64 buffers (e.g. numpy float64 arrays).
+
+        Returns ``None`` when *values* does not expose a compatible
+        buffer, letting the caller fall through to the element-wise path.
+        """
+        cdef double[::1] view
+        cdef Py_ssize_t buf_size = self.vector_size * 8
+        cdef Py_ssize_t i
+        cdef object result
+        cdef char *buf
+        cdef char *dst
+        cdef char *src
+        cdef double val
+
+        try:
+            view = values
+        except (TypeError, ValueError):
+            return None
+
+        if buf_size == 0:
+            return b""
+
+        result = PyBytes_FromStringAndSize(NULL, buf_size)
+        buf = PyBytes_AS_STRING(result)
+
+        if is_little_endian:
+            for i in range(self.vector_size):
+                val = view[i]
+                src = <char *>&val
+                dst = buf + i * 8
+                dst[0] = src[7]
+                dst[1] = src[6]
+                dst[2] = src[5]
+                dst[3] = src[4]
+                dst[4] = src[3]
+                dst[5] = src[2]
+                dst[6] = src[1]
+                dst[7] = src[0]
+        else:
+            memcpy(buf, &view[0], buf_size)
+
+        return result
+
     cdef inline bytes _serialize_int32(self, object values):
         """Serialize a list of int32 values into a contiguous big-endian buffer.
 
-        ``values`` is already a tuple (normalized in ``serialize()``), so
-        indexing is always safe and fast.
+        ``values`` is already an indexable sequence (normalized in
+        ``serialize()``), so integer indexing is safe and fast.
         """
         cdef Py_ssize_t i
         cdef Py_ssize_t buf_size = self.vector_size * 4
@@ -348,6 +452,47 @@ cdef class SerVectorType(Serializer):
 
         return result
 
+    cdef inline object _serialize_int32_buffer(self, object values):
+        """Fast path for contiguous int32 buffers (e.g. numpy int32 arrays).
+
+        No ``_coerce_int`` / ``_check_int32_range`` is needed: the typed
+        memoryview ``int[::1]`` enforces 32-bit signed integer range at
+        the buffer-protocol level.  Returns ``None`` when *values* does
+        not expose a compatible buffer, letting the caller fall through
+        to the element-wise path.
+        """
+        cdef int[::1] view
+        cdef Py_ssize_t buf_size = self.vector_size * 4
+        cdef Py_ssize_t i
+        cdef object result
+        cdef char *buf
+        cdef char *dst
+        cdef char *src
+
+        try:
+            view = values
+        except (TypeError, ValueError):
+            return None
+
+        if buf_size == 0:
+            return b""
+
+        result = PyBytes_FromStringAndSize(NULL, buf_size)
+        buf = PyBytes_AS_STRING(result)
+
+        if is_little_endian:
+            for i in range(self.vector_size):
+                src = <char *>&view[i]
+                dst = buf + i * 4
+                dst[0] = src[3]
+                dst[1] = src[2]
+                dst[2] = src[1]
+                dst[3] = src[0]
+        else:
+            memcpy(buf, &view[0], buf_size)
+
+        return result
+
     cdef inline bytes _serialize_generic(self, object values, int protocol_version):
         """Fallback: element-by-element Python serialization for non-optimized types."""
         import io

tests/unit/cython/test_serializers.py

@@ -23,6 +23,8 @@
 import struct
 import unittest
 
+import numpy as np
+
 from tests.unit.cython.utils import cythontest
 
 from cassandra.cython_deps import HAVE_CYTHON
@@ -534,6 +536,70 @@ def test_tuple_input(self):
         python_bytes = vec_type.serialize([1, 2, 3], PROTO)
         self.assertEqual(cython_bytes, python_bytes)
 
+    def test_indexable_sequence_input(self):
+        """Indexable non-list sequences should avoid tuple normalization."""
+
+        class IndexableSequence:
+            def __init__(self, data):
+                self._data = list(data)
+
+            def __len__(self):
+                return len(self._data)
+
+            def __getitem__(self, index):
+                return self._data[index]
+
+            def __iter__(self):
+                return iter(self._data)
+
+        vec_type = _make_vector_type(FloatType, 3)
+        ser = SerVectorType(vec_type)
+        values = IndexableSequence([1.0, 2.0, 3.0])
+        cython_bytes = ser.serialize(values, PROTO)
+        python_bytes = vec_type.serialize([1.0, 2.0, 3.0], PROTO)
+        self.assertEqual(cython_bytes, python_bytes)
+
+    def test_numpy_float32_array_input(self):
+        """NumPy float32 arrays should hit the float buffer fast path."""
+        vec_type = _make_vector_type(FloatType, 4)
+        ser = SerVectorType(vec_type)
+        values = np.asarray([1.0, 2.0, 3.0, 4.0], dtype=np.float32)
+        cython_bytes = ser.serialize(values, PROTO)
+        python_bytes = vec_type.serialize(values, PROTO)
+        self.assertEqual(cython_bytes, python_bytes)
+
+    def test_numpy_float64_array_input(self):
+        """NumPy float64 arrays should hit the double buffer fast path."""
+        vec_type = _make_vector_type(DoubleType, 3)
+        ser = SerVectorType(vec_type)
+        values = np.asarray([1.0, -2.5, 3.14], dtype=np.float64)
+        cython_bytes = ser.serialize(values, PROTO)
+        python_bytes = vec_type.serialize(values, PROTO)
+        self.assertEqual(cython_bytes, python_bytes)
+
+    def test_numpy_int32_array_input(self):
+        """NumPy int32 arrays should hit the int32 buffer fast path."""
+        vec_type = _make_vector_type(Int32Type, 3)
+        ser = SerVectorType(vec_type)
+        values = np.asarray([2147483647, -2147483648, 0], dtype=np.int32)
+        cython_bytes = ser.serialize(values, PROTO)
+        python_bytes = vec_type.serialize(values, PROTO)
+        self.assertEqual(cython_bytes, python_bytes)
+
+    def test_numpy_dtype_mismatch_fallthrough(self):
+        """dtype mismatch should fall through to element-wise path correctly.
+
+        A float64 array passed to a FloatType vector cannot bind to
+        float[::1], so the serializer must fall through to the
+        element-wise path and still produce correct bytes.
+        """
+        vec_type = _make_vector_type(FloatType, 3)
+        ser = SerVectorType(vec_type)
+        values = np.asarray([1.0, 2.0, 3.0], dtype=np.float64)
+        cython_bytes = ser.serialize(values, PROTO)
+        python_bytes = vec_type.serialize(values, PROTO)
+        self.assertEqual(cython_bytes, python_bytes)
+
 
 # ---------------------------------------------------------------------------
 # Factory function tests