Skip to content

Conversation

@krishvsoni
Copy link

Added documentation for Session safety in multi-process environments

Description

This PR adds comprehensive documentation warning users about the risks of using Session objects in multi-process environments where fork() is used, particularly with frameworks like Celery.

Problem

When a Session is created before forking, the underlying connection pool is shared across processes, leading to requests and responses being mixed up between processes. This causes dangerous and hard-to-debug issues.

Changes

docs/user/advanced.rst

  • Added warning section in Session Objects documentation
  • Documented three common scenarios where the issue occurs
  • Provided three recommended solutions with code examples
  • Added note about Windows not being affected

docs/api.rst

  • Added brief warning in Session API reference
  • Cross-referenced to detailed documentation in advanced.rst

Solutions Documented

  1. Create Sessions after forking (preferred approach)
  2. Reinitialize adapters after forking by remounting them
  3. Use application-level session management

Fixes

Closes #4323

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

1 participant