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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Make sessions safe[r] in multi-process environment

1 participant