fix(core): optimize FFI crossings, cache facade sizes, and clarify benchmarks/myths

[AnshMNSoni]

Description

This Pull Request resolves performance bottlenecks in PySTL's Rust extension and Python facades by reducing Python-Rust boundary crossings and adding native type-extraction comparison fast-paths. It also updates the benchmarks and documentation to provide fair algorithmic comparisons.

Key Changes

1. Rust Core & Algorithm Optimizations (src/lib.rs)

• Primitive Type Fast-Paths: Added native type extraction (i64, f64, &str) in PyObjectOrd's eq and cmp implementations. For common primitives, this avoids holding the GIL and crossing the FFI boundary for CPython rich comparison slots.
• Batch Sequence Extraction: Refactored search algorithms (lower_bound, upper_bound, binary_search, equal_range) to extract the PyList into a Rust Vec<PyObject> once at the entry point. Element indexing is now done natively in Rust (&vec[mid]), avoiding $O(\log N)$ FFI queries inside the search loop.
• Helper Comparisons: Added optimized pyobject_lt, pyobject_gt, and pyobject_eq helpers to speed up comparators.

2. Python Facade Optimizations (pythonstl/facade/)

• Facade Size Caching: Added a Python-side self._size cache to stack, queue, and vector classes.
• FFI Redundancy Elimination: Directed .empty(), .size(), and pop validation checks to read from the cached size instead of making FFI calls, reducing boundary crossings from 2 to 1 (or 0) for operations like pop(), top(), and empty().

3. Benchmarks & Documentation Clarity

• Fair Comparisons: Updated benchmark_map.py, benchmark_stack.py, and benchmark_vector.py to compare:
  1. Rust-backed STL Container (use_rust=True)
  2. Pure Python STL Container (use_rust=False)
  3. Python Built-ins (Native, labeled as unordered/native baselines to make algorithmic complexity differences transparent)
• Local Import Paths: Added sys.path.insert block to benchmark files so they target local development code instead of falling back to globally installed site-packages.
• README and Myths Update: Updated the README to explain tree-based sorted collections ($O(\log N)$) vs. hash-based unordered collections ($O(1)$) and added Myths 3 to 6 covering FFI overhead, thread safety, sorted vs. unordered collections, and reference counting.

---

Verification & Benchmarks

1. Test Suite

• Executed pytest successfully: 83 passed in 0.58s (down from 1.37s).

2. Speedups Achieved (Rust vs. Pure Python STL)

• Vector push_back/append: Rust backend is 1.67x faster.
• Vector indexing (at): Rust backend is 1.48x faster.
• Stack pop: Rust backend is 1.48x faster.
• Map insert (ints): Rust backend is 7.53x faster (0.0116s vs. 0.0873s).
• Map find (ints): Rust backend is 1.68x faster (0.0046s vs. 0.0077s).

[deepsource-io]

DeepSource Code Review

We reviewed changes in a58bf25...617f286 on this pull request. Below is the summary for the review, and you can see the individual issues we found as inline review comments.

See full review on DeepSource ↗

PR Report Card

Overall Grade

Security   Reliability   Complexity   Hygiene

Code Review Summary

Analyzer	Status	Updated (UTC)	Details
C & C++		Jul 2, 2026 6:08a.m.	Review ↗
Rust		Jul 2, 2026 6:08a.m.	Review ↗
Python		Jul 2, 2026 6:08a.m.	Review ↗

---

Important

AI Review is run only on demand for your team. We're only showing results of static analysis review right now. To trigger AI Review, comment @deepsourcebot review on this thread.