mssql-python 1.16.0__cp315-cp315-win_arm64.whl

mssql_python/perf_timer.py

@@ -0,0 +1,286 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT license.
+"""
+Lightweight phase-level profiling for the Python layer.
+
+Usage in cursor.py:
+    from mssql_python.perf_timer import perf_phase
+
+    with perf_phase("py::execute::param_type_detection"):
+        ...
+
+Control from profiler script:
+    from mssql_python.perf_timer import enable, disable, get_stats, reset
+
+Stats dict matches the C++ profiling format so both layers can be
+printed with the same reporter. Entries use a "py::" prefix to
+distinguish from C++ timers.
+"""
+
+import threading
+import time
+from contextlib import contextmanager
+from typing import NamedTuple
+
+
+class _Counter(NamedTuple):
+    calls: int
+    total_ns: int
+    min_ns: int
+    max_ns: int
+
+
+class _Event(NamedTuple):
+    name: str
+    start_ns: int
+    duration_ns: int
+
+
+_enabled = False
+_lock = threading.RLock()
+_local = threading.local()
+_window_start_ns = 0
+_stats: dict[str, _Counter] = {}
+_timeline: list[_Event] = []
+_timeline_enabled = False
+_epoch_ns: int = 0
+
+
+@contextmanager
+def _bookkeeping():
+    # GC can run SQL-cleanup finalizers during our own allocations. Suppress only
+    # recursive samples on this thread, not the cleanup or ordinary nested phases.
+    depth = getattr(_local, "depth", 0)
+    _local.depth = depth + 1
+    try:
+        yield
+    finally:
+        _local.depth = depth
+
+
+def enable():
+    global _enabled, _window_start_ns
+    with _bookkeeping():
+        release = _lock.release
+        _lock.acquire()
+        try:
+            _window_start_ns = time.perf_counter_ns()
+            _enabled = True
+        finally:
+            release()
+
+
+def disable():
+    global _enabled
+    with _bookkeeping():
+        release = _lock.release
+        _lock.acquire()
+        try:
+            _enabled = False
+        finally:
+            release()
+
+
+def is_enabled() -> bool:
+    return _enabled
+
+
+def reset():
+    global _window_start_ns, _stats, _timeline
+    with _bookkeeping():
+        stats, timeline = {}, []
+        release = _lock.release
+        _lock.acquire()
+        try:
+            _window_start_ns = time.perf_counter_ns()
+            _stats = stats
+            _timeline = timeline
+        finally:
+            release()
+
+
+def reset_stats_only():
+    global _window_start_ns, _stats
+    with _bookkeeping():
+        stats = {}
+        release = _lock.release
+        _lock.acquire()
+        try:
+            _window_start_ns = time.perf_counter_ns()
+            _stats = stats
+        finally:
+            release()
+
+
+def enable_timeline():
+    global _timeline_enabled, _epoch_ns, _timeline
+    # Clear any previously recorded events when (re)setting the epoch, so every
+    # event in _timeline shares the current epoch. Otherwise a second
+    # enable_timeline() without an intervening reset() would leave stale events
+    # whose offsets were computed from an older epoch, corrupting the sort.
+    with _bookkeeping():
+        timeline = []
+        release = _lock.release
+        _lock.acquire()
+        try:
+            _timeline = timeline
+            _epoch_ns = time.perf_counter_ns()
+            _timeline_enabled = True
+        finally:
+            release()
+
+
+def disable_timeline():
+    global _timeline_enabled
+    with _bookkeeping():
+        release = _lock.release
+        _lock.acquire()
+        try:
+            _timeline_enabled = False
+        finally:
+            release()
+
+
+def get_timeline() -> list[dict]:
+    with _bookkeeping():
+        # Built-in container copies hold the GIL on supported CPython builds.
+        # Immutable entries stay stable; no profiler lock surrounds GC allocations.
+        snapshot = _timeline.copy()
+        return [
+            {
+                "name": ev.name,
+                "start_us": ev.start_ns // 1000,
+                "duration_us": ev.duration_ns // 1000,
+            }
+            for ev in snapshot
+        ]
+
+
+def get_stats() -> dict:
+    with _bookkeeping():
+        snapshot = _stats.copy()
+        out = {}
+        for name, s in snapshot.items():
+            # Keep fractional microseconds when converting accumulated samples.
+            out[name] = {
+                "calls": s.calls,
+                "total_us": s.total_ns / 1000.0,
+                "min_us": s.min_ns / 1000.0,
+                "max_us": s.max_ns / 1000.0,
+            }
+        return out
+
+
+class _NullPhase:
+    """No-op context manager returned by perf_phase when profiling is disabled.
+
+    A single shared instance is reused so the disabled path costs only a function
+    call plus two slot method calls, avoiding the generator + _GeneratorContextManager
+    allocation of an @contextmanager that every instrumented call site would
+    otherwise pay even when profiling is off.
+    """
+
+    __slots__ = ()
+
+    def __enter__(self):
+        return None
+
+    def __exit__(self, *exc):
+        return False
+
+
+class _Phase:
+    """Times one phase and records it on exit (used only when enabled).
+
+    Recording happens in __exit__, which always runs even if the wrapped block
+    raises, so an exception can't silently drop the sample and desync the Python
+    call counts from the C++ ones.
+    """
+
+    __slots__ = ("_name", "_t0")
+
+    def __init__(self, name: str):
+        self._name = name
+
+    def __enter__(self):
+        self._t0 = perf_start()
+        return None
+
+    def __exit__(self, *exc):
+        perf_stop(self._name, self._t0)
+        return False
+
+
+_NULL_PHASE = _NullPhase()
+
+
+def perf_phase(name: str):
+    if not _enabled:
+        return _NULL_PHASE
+    return _Phase(name)
+
+
+def perf_start() -> int:
+    if not _enabled:
+        return 0
+    return time.perf_counter_ns()
+
+
+def perf_stop(name: str, t0: int):
+    # t0 == 0 means perf_start() ran while disabled (or was never called); a
+    # falsy start has no valid interval, so record nothing rather than a bogus
+    # "now - 0" duration.
+    if not _enabled or not t0:
+        return
+    _record(name, time.perf_counter_ns() - t0, t0)
+
+
+def _record(name: str, elapsed: int, start_ns: int = 0):
+    if getattr(_local, "depth", 0):
+        return
+    with _bookkeeping():
+        # Prebind the no-argument release: RLock.__exit__ and method lookup can
+        # allocate before unlocking, which is unsafe around GC finalizers.
+        release = _lock.release
+        while True:
+            _lock.acquire()
+            try:
+                if not _enabled or (start_ns and start_ns < _window_start_ns):
+                    return
+                stats = _stats
+                entry = stats.get(name)
+                window = _window_start_ns
+                timeline = _timeline
+                epoch = _epoch_ns
+                record_event = _timeline_enabled and start_ns and start_ns >= epoch
+            finally:
+                release()
+
+            # Allocate before locking: GC may run a finalizer that waits for SQL
+            # on another thread, which must be able to finish its own recording.
+            updated = (
+                _Counter(1, elapsed, elapsed, elapsed)
+                if entry is None
+                else _Counter(
+                    entry.calls + 1,
+                    entry.total_ns + elapsed,
+                    min(entry.min_ns, elapsed),
+                    max(entry.max_ns, elapsed),
+                )
+            )
+            event = _Event(name, start_ns - epoch, elapsed) if record_event else None
+
+            _lock.acquire()
+            try:
+                # Revalidate after allocations and any callbacks they triggered.
+                if not _enabled or window != _window_start_ns or stats is not _stats:
+                    return
+                if stats.get(name) is not entry:
+                    continue
+                stats[name] = updated
+                # A timeline-only restart must not discard valid aggregate samples.
+                if event is not None and _timeline_enabled and timeline is _timeline:
+                    timeline.append(event)
+                return
+            finally:
+                release()

mssql_python/pooling.py

@@ -0,0 +1,151 @@
+"""
+Copyright (c) Microsoft Corporation.
+Licensed under the MIT license.
+This module provides connection pooling functionality for the mssql_python package.
+"""
+
+import atexit
+import threading
+from typing import Dict
+
+from mssql_python import ddbc_bindings
+from mssql_python.logging import logger
+
+
+class PoolingManager:
+    """
+    Manages connection pooling for the mssql_python package.
+
+    This class provides thread-safe connection pooling functionality using the
+    underlying DDBC bindings. It follows a singleton pattern with class-level
+    state management.
+    """
+
+    _enabled: bool = False
+    _initialized: bool = False
+    _pools_closed: bool = False  # Track if pools have been closed
+    _lock: threading.Lock = threading.Lock()
+    _config: Dict[str, int] = {"max_size": 100, "idle_timeout": 600}
+
+    @classmethod
+    def enable(cls, max_size: int = 100, idle_timeout: int = 600) -> None:
+        """
+        Enable connection pooling with specified parameters.
+
+        Args:
+            max_size: Maximum number of connections in the pool (default: 100)
+            idle_timeout: Timeout in seconds for idle connections (default: 600)
+
+        Raises:
+            ValueError: If parameters are invalid (max_size <= 0 or idle_timeout < 0)
+        """
+        logger.debug(
+            "PoolingManager.enable: Attempting to enable pooling - max_size=%d, idle_timeout=%d",
+            max_size,
+            idle_timeout,
+        )
+        with cls._lock:
+            if cls._enabled:
+                logger.debug("PoolingManager.enable: Pooling already enabled, skipping")
+                return
+
+            if max_size <= 0 or idle_timeout < 0:
+                logger.error(
+                    "PoolingManager.enable: Invalid parameters - max_size=%d, idle_timeout=%d",
+                    max_size,
+                    idle_timeout,
+                )
+                raise ValueError("Invalid pooling parameters")
+
+            logger.info(
+                "PoolingManager.enable: Enabling connection pooling - max_size=%d, idle_timeout=%d seconds",
+                max_size,
+                idle_timeout,
+            )
+            # enable_pooling() only configures the connection-pool manager; it
+            # does not load the native driver, so it must not resolve/freeze
+            # the ODBC provider (an explicit pooling() before selecting a
+            # provider would otherwise lock in the default prematurely).
+            ddbc_bindings.enable_pooling(max_size, idle_timeout)
+            cls._config["max_size"] = max_size
+            cls._config["idle_timeout"] = idle_timeout
+            cls._enabled = True
+            # Re-arm the disable guard: enable_pooling() calls setAccepting(true)
+            # on the native manager, so the Python state must mirror that a
+            # fresh disable() is once again required to disarm it. Without this
+            # reset, an enable -> disable -> enable -> disable sequence would
+            # leave _pools_closed True after the first disable, causing the
+            # second disable to skip disable_pooling() and desync from the
+            # native manager (which is still accepting).
+            cls._pools_closed = False
+            cls._initialized = True
+            logger.info("PoolingManager.enable: Connection pooling enabled successfully")
+
+    @classmethod
+    def disable(cls) -> None:
+        """
+        Disable connection pooling and clean up resources.
+
+        This method safely disables pooling and closes existing connections.
+        It can be called multiple times safely.
+        """
+        logger.debug("PoolingManager.disable: Attempting to disable pooling")
+        with cls._lock:
+            if (
+                cls._enabled and not cls._pools_closed
+            ):  # Only cleanup if enabled and not already closed
+                logger.info("PoolingManager.disable: Closing connection pools")
+                ddbc_bindings.disable_pooling()
+                logger.info("PoolingManager.disable: Connection pools closed successfully")
+            else:
+                logger.debug("PoolingManager.disable: Pooling already disabled or closed")
+            cls._pools_closed = True
+            cls._enabled = False
+            cls._initialized = True
+
+    @classmethod
+    def is_enabled(cls) -> bool:
+        """
+        Check if connection pooling is currently enabled.
+
+        Returns:
+            bool: True if pooling is enabled, False otherwise
+        """
+        return cls._enabled
+
+    @classmethod
+    def is_initialized(cls) -> bool:
+        """
+        Check if the pooling manager has been initialized.
+
+        Returns:
+            bool: True if initialized (either enabled or disabled), False otherwise
+        """
+        return cls._initialized
+
+    @classmethod
+    def _reset_for_testing(cls) -> None:
+        """Reset pooling state - for testing purposes only"""
+        with cls._lock:
+            cls._enabled = False
+            cls._initialized = False
+            cls._pools_closed = False
+
+
+@atexit.register
+def shutdown_pooling():
+    """
+    Shutdown pooling during application exit.
+
+    This function is registered with atexit to ensure proper cleanup of
+    connection pools when the application terminates.
+    """
+    logger.debug("shutdown_pooling: atexit cleanup triggered")
+    with PoolingManager._lock:
+        if PoolingManager._enabled and not PoolingManager._pools_closed:
+            logger.info("shutdown_pooling: Closing connection pools during application exit")
+            ddbc_bindings.close_pooling()
+            PoolingManager._pools_closed = True
+            logger.info("shutdown_pooling: Connection pools closed successfully")
+        else:
+            logger.debug("shutdown_pooling: No active pools to close")

mssql_python/py.typed

@@ -0,0 +1 @@
+