pyo3-performance-patterns

Optimize PyO3 async Rust functions by managing the GIL and selecting spawn_blocking or block_in_place.

836|66|Updated Feb 3, 2025
One-click install
npx skills add https://github.com/kreuzberg-dev/html-to-markdown --skill pyo3-performance-patterns-kreuzberg-dev
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: pyo3-performance-patterns
Source: https://github.com/kreuzberg-dev/html-to-markdown/tree/main/.codex/skills/pyo3-performance-patterns
Command: npx skills add https://github.com/kreuzberg-dev/html-to-markdown --skill pyo3-performance-patterns-kreuzberg-dev

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill addresses performance bottlenecks when integrating asynchronous Rust code with Python, particularly concerning GIL management and efficient callback handling.

Core Features & Use Cases

  • Async Callback Optimization: Leverages pyo3_async_runtimes for significantly faster async Python callbacks compared to spawn_blocking.
  • GIL Management: Provides patterns for releasing the GIL before awaiting async operations and using Python::attach() appropriately.
  • Use Case: When calling a Rust function from Python that involves asynchronous operations, this Skill ensures the most performant and deadlock-free execution path is chosen based on whether the operation is quick or long-running.

Quick Start

Use the pyo3-performance-patterns skill to optimize an async Python callback by releasing the GIL before awaiting.

Frequently Asked Questions about pyo3-performance-patterns

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I optimize async Rust functions called from Python using PyO3?

Optimize async Rust functions called from Python by releasing the GIL before awaiting operations and leveraging `pyo3_async_runtimes` for faster callbacks. This approach ensures performant, deadlock-free execution paths based on operation duration.

When should I use spawn_blocking vs block_in_place for Python Rust integration?

Use `spawn_blocking` for long-running operations and `block_in_place` for quick operations when integrating Rust with Python. Choosing the correct method prevents GIL deadlocks in critical sections like PostProcessor and Validator components.

Why does my PyO3 async runtime deadlock waiting on the GIL?

PyO3 async runtimes deadlock when the GIL is held during await operations. Prevent this by releasing the GIL before awaiting async tasks and using `Python::attach()` appropriately to manage critical sections safely.

What is the best way to handle Python callbacks in an async Rust runtime?

The best way to handle Python callbacks in an async Rust runtime is using `pyo3_async_runtimes`, which provides significantly faster execution compared to `spawn_blocking` while properly managing GIL release and attachment.

Does PyO3 support releasing the GIL during asynchronous operations?

Yes, PyO3 supports releasing the GIL during asynchronous operations. You can release the GIL before awaiting async tasks and use `Python::attach()` to re-enter the interpreter context only when necessary, maximizing concurrency.