feat: Add graceful shutdown support for tokio runtime

[achimnol]

Summary

This PR adds graceful shutdown support for the tokio runtime, addressing #40.

Motivation

When Python extensions built with pyo3-async-runtimes are used in subprocesses or short-lived contexts, tokio tasks may still be running when Python interpreter finalization begins. This causes fatal errors like:

Fatal Python error: PyGILState_Release: thread state...must be current when releasing

Real-world Use Case: etcd-client-py

This implementation enables proper shutdown coordination as demonstrated in lablup/etcd-client-py#17, which uses the new APIs to implement automatic runtime cleanup:

1. Reference counting via ACTIVE_CONTEXTS atomic counter tracks client contexts
2. Async shutdown sequence in __aexit__:
   • Awaits tokio cleanup task (returns flag for last context)
   • If final context, calls _trigger_shutdown() (wraps request_shutdown_background)
   • Awaits asyncio.to_thread() to block-join the runtime (wraps join_pending_shutdown)

This ensures shutdown completes within the async context, avoiding deadlocks and race conditions where the runtime shuts down mid-task.

Implementation

The tokio runtime now lives in a dedicated thread (inspired by valkey-glide):

struct RuntimeWrapper {
    handle: Handle,                           // Thread-safe handle for spawning
    runtime_thread: Mutex<Option<JoinHandle<()>>>,
    shutdown_notifier: Arc<Notify>,
    timeout_sender: Mutex<Option<SyncSender<u64>>>,
}

When request_shutdown(timeout_ms) is called:

1. The shutdown notifier signals the runtime thread
2. The timeout value is sent via channel
3. The runtime thread calls Runtime::shutdown_timeout()
4. request_shutdown blocks on thread.join() until complete

New APIs

Tokio

Function	Description
get_handle() -> Handle	Returns cloneable Handle (recommended)
spawn(fut)	Convenience function for spawning futures
spawn_blocking(f)	Convenience function for blocking tasks
request_shutdown(timeout_ms) -> bool	Blocking shutdown
request_shutdown_background(timeout_ms) -> bool	Non-blocking shutdown
join_pending_shutdown(py) -> bool	Join pending background shutdown

async-std (API consistency)

Function	Description
spawn(fut)	Wrapper for async_std::task::spawn
spawn_blocking(f)	Wrapper for async_std::task::spawn_blocking
request_shutdown(timeout_ms) -> bool	Sets flag only (cannot actually shut down)

Deprecated APIs

• tokio::get_runtime() - Cannot be gracefully shut down. Use get_handle() instead.

Usage Example

import asyncio
from my_rust_module import cleanup_runtime

async def main():
    await do_work()
    cleanup_runtime()  # Wraps request_shutdown()

asyncio.run(main())

Dependency Changes

• Replaced futures with futures-channel + futures-util for reduced dependency tree
• Added parking_lot for RwLock
• Added tokio sync feature for Notify

Backward Compatibility

• Existing code using future_into_py works unchanged
• get_runtime() is deprecated but still functional (uses a separate leaked runtime)
• No breaking changes to the public API

Testing

Tested in etcd-client-py across:

• Python 3.11, 3.12, 3.13, 3.14, 3.14t (free-threaded)
• Linux x86_64 and ARM64
• macOS

Related

• Fixes Do we need some kind of shutdown method? #40
• Used by lablup/etcd-client-py#17

[achimnol]

I have worked with Claude Code to resolve the runtime cleanup issues in our library (etcd-client-py) as mentioned above. Since this PR is an AI-generated code, it may have some clutters that need to be refined. I tried my best to make it human-readable, but please feel free to give me feedbacks.
(e.g., suggestions for test scenarios, desired changes to the code structure, etc.)

Also refer to the test cases in etcd-client-py for stress tests iterating over 20 times per run:

• tests/test_shutdown_stress.py: https://github.com/lablup/etcd-client-py/pull/14/changes#diff-9a687e833e5f4f50d89e095488b053ffa462f972e5a82f477174cfe3098b6e20