perf: cache apply_parameters to avoid repeated type() class creation

Cache the results of _CassandraType.apply_parameters() in a class-level
dict keyed by (cls, subtypes, names). This avoids the expensive type()
metaclass machinery on repeated calls with the same type signature,
which is the common case during result-set deserialization.

Benchmark: 31.7x speedup (6.48 us/call -> 0.20 us/call) for cached hits.

UserType and VectorType define their own apply_parameters() overrides
(with their own, independently-keyed caching/lookup) and never read or
write this cache, so this change cannot affect UDT or vector<...>
dimension/subtype resolution.

Fix a crash the cache key introduced for types that accept zero
subtypes (num_subtypes == 'UNKNOWN', e.g. CompositeType,
ColumnToCollectionType): `tuple(names) if names else names` left an
explicit empty `names` list unconverted (`[]` is falsy), producing an
unhashable list inside the cache-key tuple and raising TypeError on
the dict lookup. Normalize with `is not None` instead, and add
regression tests for the empty-names case and for confirming
VectorType stays independent of the shared cache.

Signed-off-by: Yaniv Michael Kaul <yaniv.kaul@scylladb.com>

Author: mykaul

benchmarks/bench_cache_apply_parameters.py

@@ -0,0 +1,81 @@
+# Copyright DataStax, Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+Micro-benchmark: apply_parameters caching.
+
+Measures the speedup from caching parameterized type creation
+in _CassandraType.apply_parameters().
+
+Run:
+    python benchmarks/bench_cache_apply_parameters.py
+"""
+import timeit
+from cassandra.cqltypes import (
+    MapType, SetType, ListType, TupleType,
+    Int32Type, UTF8Type, FloatType, DoubleType, BooleanType,
+    _CassandraType,
+)
+
+
+def bench_apply_parameters():
+    """Benchmark apply_parameters with cache (repeated calls)."""
+    cache = _CassandraType._apply_parameters_cache
+
+    # Warm up the cache
+    MapType.apply_parameters([UTF8Type, Int32Type])
+    SetType.apply_parameters([FloatType])
+    ListType.apply_parameters([DoubleType])
+    TupleType.apply_parameters([Int32Type, UTF8Type, BooleanType])
+
+    calls = [
+        (MapType, [UTF8Type, Int32Type]),
+        (SetType, [FloatType]),
+        (ListType, [DoubleType]),
+        (TupleType, [Int32Type, UTF8Type, BooleanType]),
+    ]
+
+    def run_cached():
+        for cls, subtypes in calls:
+            cls.apply_parameters(subtypes)
+
+    # Benchmark cached path
+    n = 100_000
+    t_cached = timeit.timeit(run_cached, number=n)
+    print(f"Cached apply_parameters ({len(calls)} types x {n} iters): "
+          f"{t_cached:.3f}s  ({t_cached / (n * len(calls)) * 1e6:.2f} us/call)")
+
+    # Benchmark uncached path (clear cache each iteration)
+    def run_uncached():
+        # The four calls below use distinct cache keys, so a single clear
+        # per iteration still leaves every call a cache miss.
+        cache.clear()
+        for cls, subtypes in calls:
+            cls.apply_parameters(subtypes)
+
+    t_uncached = timeit.timeit(run_uncached, number=n)
+    print(f"Uncached apply_parameters ({len(calls)} types x {n} iters): "
+          f"{t_uncached:.3f}s  ({t_uncached / (n * len(calls)) * 1e6:.2f} us/call)")
+
+    speedup = t_uncached / t_cached
+    print(f"Speedup: {speedup:.1f}x")
+
+
+def main():
+    """Run the apply_parameters cache benchmark."""
+    bench_apply_parameters()
+
+
+if __name__ == '__main__':
+    main()

cassandra/cqltypes.py

@@ -41,6 +41,7 @@
 import time
 import struct
 import sys
+import threading
 from uuid import UUID
 
 from cassandra.marshal import (int8_pack, int8_unpack, int16_pack, int16_unpack,
@@ -276,6 +277,26 @@ class _CassandraType(object, metaclass=CassandraTypeType):
     num_subtypes = 0
     empty_binary_ok = False
 
+    # Cache of previously-constructed parameterized subtypes, keyed on
+    # (cls, subtypes, names) -- see apply_parameters() below. This is a
+    # single dict shared by every subclass that does not override
+    # apply_parameters() (e.g. ListType, SetType, MapType, TupleType,
+    # CompositeType). Growth is bounded by the number of distinct
+    # (type, subtypes, names) combinations actually seen, which in
+    # practice tracks the number of distinct column/type shapes across
+    # the schemas a session talks to -- not the number of rows or queries.
+    # UserType and VectorType define their own apply_parameters()
+    # overrides (with their own, differently-keyed caches) and never
+    # populate or consult this dict.
+    _apply_parameters_cache = {}  # noqa: RUF012  # shared cache is intentional
+
+    # Guards the get-then-create-then-set sequence in apply_parameters()
+    # below so that concurrent callers racing on the same (cls, subtypes,
+    # names) cannot each create their own class and clobber one another
+    # in the cache. Shared by every subclass using _apply_parameters_cache,
+    # for the same reason that cache itself is shared.
+    _apply_parameters_cache_lock = threading.Lock()
+
     support_empty_values = False
     """
     Back in the Thrift days, empty strings were used for "null" values of
@@ -373,8 +394,37 @@ def apply_parameters(cls, subtypes, names=None):
         if cls.num_subtypes != 'UNKNOWN' and len(subtypes) != cls.num_subtypes:
             raise ValueError("%s types require %d subtypes (%d given)"
                              % (cls.typename, cls.num_subtypes, len(subtypes)))
-        newname = cls.cass_parameterized_type_with(subtypes)
-        return type(newname, (cls,), {'subtypes': subtypes, 'cassname': cls.cassname, 'fieldnames': names})
+        subtypes = tuple(subtypes)
+        # Use `is not None` (rather than a truthiness check) so an explicit
+        # empty sequence (`names=[]`, e.g. for a type parameterized with zero
+        # subtypes) is normalized to a hashable `()` instead of being left as
+        # an unhashable list, which would raise on the dict lookup below.
+        # Normalize once and reuse the same value for both the cache key and
+        # the `fieldnames` stored on the created class -- otherwise, if the
+        # caller passed a mutable list, the cache key would be a tuple
+        # snapshot while `fieldnames` aliased the caller's original list, and
+        # a later mutation of that list would silently corrupt the cached
+        # class for every subsequent cache hit.
+        norm_names = tuple(names) if names is not None else None
+        cache_key = (cls, subtypes, norm_names)
+        cached = cls._apply_parameters_cache.get(cache_key)
+        if cached is not None:
+            return cached
+        # The get-then-create-then-set sequence above is not atomic, so
+        # guard the miss path with a lock and re-check the cache once
+        # inside it: two threads can otherwise race past the check above
+        # for the same (cls, subtypes, names), each create its own class
+        # via type(), and stomp on each other's cache entry, leaving some
+        # callers holding a class that is not the one now cached (breaking
+        # `is`-based identity assumptions).
+        with cls._apply_parameters_cache_lock:
+            cached = cls._apply_parameters_cache.get(cache_key)
+            if cached is not None:
+                return cached
+            newname = cls.cass_parameterized_type_with(subtypes)
+            result = type(newname, (cls,), {'subtypes': subtypes, 'cassname': cls.cassname, 'fieldnames': norm_names})
+            cls._apply_parameters_cache[cache_key] = result
+        return result
 
     @classmethod
     def cql_parameterized_type(cls):