Add process-bound environments documentation

Author: benoitc

CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 2.2.0 (2026-03-13)
+
+### Added
+
+- **Process-Bound Python Environments** - Each Erlang process gets an isolated Python namespace
+  - `py:get_local_env/1` - Get or create a process-local Python environment
+  - Variables defined via `py:exec()` persist across calls within the same Erlang process
+  - Automatic cleanup when the Erlang process exits (no manual deallocation needed)
+  - Environments are stored in process dictionary, keyed by interpreter ID
+  - Works with both subinterpreter and worker modes
+  - Critical for process affinity: each process maintains independent Python state
+  - Memory-safe: environments created inside the correct interpreter's allocator
+  - See [Process-Bound Environments](docs/context-affinity.md#process-bound-environments) for details
+
+- **Docker Test Configs** - Containerized test environment
+  - `docker/Dockerfile.python312` - Python 3.12 test image
+  - `docker/Dockerfile.python314` - Python 3.14 test image
+  - `docker/Dockerfile.asan` - AddressSanitizer build for memory testing
+  - `docker/docker-compose.yml` - Multi-container test orchestration
+  - `docker/run-tests.sh` - Automated test runner script
+
+- **Async Task Benchmark** - Performance testing for async operations
+  - `examples/bench_async_task.erl` - Erlang benchmark runner
+  - `priv/test_async_task.py` - Python async task implementation
+
 ## 2.1.0 (2026-03-12)
 
 ### Added

docs/context-affinity.md

@@ -240,10 +240,126 @@ case py:contexts_started() of
 end.
 ```
 
+## Process-Bound Environments
+
+Process-bound environments provide true process-level isolation for Python state. Each Erlang process automatically gets its own Python namespace that persists across calls.
+
+### How It Works
+
+When you call `py:call()`, `py:eval()`, or `py:exec()`, the library automatically:
+
+1. Looks up or creates a process-local Python environment for your Erlang process
+2. Executes the Python code using that environment
+3. Stores variables, imports, and objects in that environment
+4. Cleans up automatically when your Erlang process exits
+
+This happens transparently - no explicit binding required.
+
+### Basic Usage
+
+```erlang
+%% Get a context
+Ctx = py:context(1),
+
+%% Define a variable - it persists for THIS Erlang process
+ok = py:exec(Ctx, <<"counter = 0">>),
+ok = py:exec(Ctx, <<"counter += 1">>),
+{ok, 1} = py:eval(Ctx, <<"counter">>).
+
+%% In a different Erlang process, counter is independent:
+spawn(fun() ->
+    ok = py:exec(Ctx, <<"counter = 100">>),
+    {ok, 100} = py:eval(Ctx, <<"counter">>)
+end).
+
+%% Back in original process, still 1
+{ok, 1} = py:eval(Ctx, <<"counter">>).
+```
+
+### Process Affinity for AI Workloads
+
+Process-bound environments are ideal for scenarios where each Erlang process needs isolated Python state:
+
+```erlang
+%% Each user session gets its own chat history
+handle_user_session(UserId) ->
+    Ctx = py:context(),
+    %% Initialize conversation for this process
+    ok = py:exec(Ctx, <<"
+conversation_history = []
+def add_message(role, content):
+    conversation_history.append({'role': role, 'content': content})
+def get_history():
+    return conversation_history
+">>),
+    session_loop(Ctx).
+
+session_loop(Ctx) ->
+    receive
+        {user_message, Msg} ->
+            py:call(Ctx, '__main__', add_message, [<<"user">>, Msg]),
+            %% Process with AI...
+            session_loop(Ctx);
+        get_history ->
+            {ok, History} = py:call(Ctx, '__main__', get_history, []),
+            History
+    end.
+```
+
+### Isolation Between Processes
+
+```erlang
+%% Process A
+spawn(fun() ->
+    Ctx = py:context(1),
+    ok = py:exec(Ctx, <<"x = 'from process A'">>)
+end),
+
+%% Process B - same context, but isolated environment
+spawn(fun() ->
+    Ctx = py:context(1),  %% Same context!
+    ok = py:exec(Ctx, <<"x = 'from process B'">>),
+    {ok, <<"from process B">>} = py:eval(Ctx, <<"x">>)  %% Own value
+end).
+```
+
+### Memory Management
+
+Environments are automatically freed when:
+- The Erlang process exits (normal, abnormal, or killed)
+- The NIF resource destructor runs during garbage collection
+
+No manual cleanup is needed. The environments use the correct memory allocator for each interpreter (critical for subinterpreters which have isolated allocators).
+
+### When to Use Process-Bound Environments
+
+**Good use cases:**
+- Stateful sessions (chat, game state, user preferences)
+- Long-running workers that accumulate state
+- Process-per-request patterns with state
+- AI pipelines with per-request context
+
+**Consider alternatives when:**
+- State must be shared between Erlang processes (use shared state API instead)
+- State needs to outlive the Erlang process (use explicit storage)
+- You need multiple independent namespaces per process (use explicit contexts)
+
+### Technical Details
+
+Process-bound environments work by:
+
+1. Storing a `reference()` in the calling process's dictionary under `py_local_env`
+2. The reference points to a Python dict created inside the interpreter
+3. Each interpreter ID maps to a separate environment (for subinterpreter support)
+4. The NIF uses this dict as `locals` for `exec()` and `eval()` operations
+
+For subinterpreters, environments are created inside the target interpreter to ensure memory safety - Python's subinterpreters have isolated memory allocators.
+
 ## Best Practices
 
 1. **Use explicit contexts for stateful operations**: `Ctx = py:context(1)` ensures state persists
 2. **Use automatic routing for stateless calls**: Let the router handle distribution
 3. **Always unbind in finally blocks**: Prevent context leaks
 4. **Minimize binding time**: Don't hold contexts longer than necessary
 5. **Monitor pool size**: Check `py_context_router:num_contexts()` to understand capacity
+6. **Leverage process-bound environments**: For per-process state, rely on automatic environment isolation rather than manual binding