Update docs for simplified API, add parallel execution guide, bump to 3.0.0

Documentation updates after API simplification:
- Remove WSGI/ASGI references from buffer.md, getting-started.md
- Remove py_asgi examples from asyncio.md
- Mark subinterp/OWN_GIL as internal in scalability.md, process-bound-envs.md
- Update migration.md with simplified mode descriptions
- Update source comments in py_buffer.erl, py_nif.erl, py_reactor_context.erl
- Remove missing owngil_internals.md from rebar.config

New documentation:
- Add docs/parallel-execution.md explaining parallel pool architecture

Version bump:
- Bump version to 3.0.0 in app.src and getting-started.md

Author: benoitc

README.md

@@ -18,7 +18,7 @@ schedulers.
 **Parallelism options:**
 - **Worker mode** (default) - Works with any Python version
 - **Free-threaded Python** (3.13t+) - True parallelism, automatic detection
-- **Parallel pool** (Python 3.14+) - Build with `ENABLE_PARALLEL_PYTHON=ON` for subinterpreter-based parallelism
+- **Parallel pool** - Build with `ENABLE_PARALLEL_PYTHON=ON` for automatic parallel execution
 - **BEAM processes** - Fan out work across lightweight Erlang processes
 
 Key features:
@@ -603,7 +603,7 @@ By default, erlang_python uses **worker mode** which works with any Python versi
 
 For true parallel Python execution:
 
-- **Build with parallel pool** (Python 3.14+):
+- **Build with parallel pool**:
   ```bash
   CMAKE_OPTIONS="-DENABLE_PARALLEL_PYTHON=ON" rebar3 compile
   ```

docs/asyncio.md

@@ -915,30 +915,13 @@ erlang.run(main())
 - You need precise sub-millisecond timing
 - Your app makes many small sleep calls
 - You want to eliminate Python event loop overhead
-- Building ASGI handlers that need efficient sleep
+- Building async handlers that need efficient sleep
 - Your app is running inside erlang_python
 
 **Use standard `asyncio.run()` when:**
 - You're running outside the Erlang VM
 - Testing Python code in isolation
 
-### Integration with ASGI Frameworks
-
-For ASGI applications (FastAPI, Starlette, etc.), you can use the Erlang event loop for better performance:
-
-```python
-from fastapi import FastAPI
-import asyncio
-
-app = FastAPI()
-
-@app.get("/delay")
-async def delay_endpoint(ms: int = 100):
-    # When running via py_asgi, uses Erlang timer
-    await asyncio.sleep(ms / 1000.0)
-    return {"slept_ms": ms}
-```
-
 ## Async Worker Backend (Internal)
 
 The `py:async_call/3,4` and `py:await/1,2` APIs use an event-driven backend based on `py_event_loop`.

docs/buffer.md

@@ -1,20 +1,20 @@
 # Buffer API
 
-The Buffer API provides a zero-copy WSGI input buffer for streaming HTTP request bodies from Erlang to Python. Buffers use shared memory with GIL-released blocking reads for efficient data transfer.
+The Buffer API provides a zero-copy streaming buffer for transferring data from Erlang to Python. Buffers use shared memory with GIL-released blocking reads for efficient data transfer.
 
 ## Overview
 
-Buffers are designed for WSGI/ASGI `wsgi.input` scenarios where Erlang receives HTTP body chunks and Python needs to consume them:
+Buffers are designed for scenarios where Erlang produces data chunks and Python needs to consume them:
 
 - Zero-copy access via Python's buffer protocol (`memoryview`)
 - File-like interface (`read`, `readline`, `readlines`)
 - Blocking reads that release the GIL while waiting
 - Fast substring search using `memchr`/`memmem`
 
 Use buffers when you need:
-- WSGI input for HTTP request bodies
 - Streaming data from Erlang to Python
 - Zero-copy access to binary data
+- Blocking reads with GIL release
 
 ## Quick Start
 
@@ -34,25 +34,23 @@ ok = py_buffer:write(Buf, <<"chunk2">>),
 %% Signal end of data
 ok = py_buffer:close(Buf),
 
-%% Pass to WSGI app
-py:call(Ctx, myapp, handle_request, [#{<<"wsgi.input">> => Buf}]).
+%% Pass to Python handler
+py:call(Ctx, myapp, handle_request, [Buf]).
 ```
 
 ### Python Side
 
 ```python
-def handle_request(environ):
-    wsgi_input = environ['wsgi.input']
-
+def handle_request(buf):
     # Read all data
-    body = wsgi_input.read()
+    body = buf.read()
 
     # Or read line by line
-    for line in wsgi_input:
+    for line in buf:
         process(line)
 
     # Or read specific amount
-    chunk = wsgi_input.read(1024)
+    chunk = buf.read(1024)
 ```
 
 ## Erlang API
@@ -348,25 +346,16 @@ py_buffer_resource_t
 
 ## Examples
 
-### WSGI Input Simulation
+### Basic Streaming
 
 ```erlang
-%% Simulate receiving HTTP body
+%% Create buffer and write data
 {ok, Buf} = py_buffer:new(byte_size(Body)),
 ok = py_buffer:write(Buf, Body),
 ok = py_buffer:close(Buf),
 
-%% Build WSGI environ
-Environ = #{
-    <<"REQUEST_METHOD">> => <<"POST">>,
-    <<"PATH_INFO">> => <<"/api/data">>,
-    <<"CONTENT_TYPE">> => <<"application/json">>,
-    <<"CONTENT_LENGTH">> => integer_to_binary(byte_size(Body)),
-    <<"wsgi.input">> => Buf
-},
-
-%% Call WSGI app
-{ok, Response} = py:call(myapp, handle, [Environ]).
+%% Pass to Python handler
+{ok, Response} = py:call(myapp, handle, [Buf]).
 ```
 
 ### Chunked Transfer
@@ -443,10 +432,8 @@ async def read_buffer_async(buf):
 
     return b''.join(chunks)
 
-async def process_wsgi_body_async(environ):
-    """Process WSGI body in async context."""
-    buf = environ['wsgi.input']
-
+async def process_body_async(buf):
+    """Process buffer in async context."""
     # Read body without blocking
     body = await read_buffer_async(buf)
     return json.loads(body)

docs/getting-started.md

@@ -8,7 +8,7 @@ Add to your `rebar.config`:
 
 ```erlang
 {deps, [
-    {erlang_python, "2.2.0"}
+    {erlang_python, "3.0.0"}
 ]}.
 ```
 
@@ -424,7 +424,7 @@ async def main():
 erlang.run(main())
 ```
 
-This is especially useful in ASGI handlers where sleep operations are common. See [Asyncio](asyncio.md) for the full API reference.
+This is especially useful in async handlers where sleep operations are common. See [Asyncio](asyncio.md) for the full API reference.
 
 ## Security Considerations
 
@@ -471,28 +471,28 @@ This prevents slow HTTP requests from blocking quick math operations. See [Pool
 
 ## Zero-Copy Buffers
 
-For WSGI/ASGI applications that need to stream HTTP request bodies, use `py_buffer`:
+For streaming data from Erlang to Python, use `py_buffer`:
 
 ```erlang
-%% Create buffer for HTTP body
+%% Create buffer for streaming data
 {ok, Buf} = py_buffer:new(ContentLength),
 
-%% Write body chunks as they arrive
+%% Write chunks as they arrive
 ok = py_buffer:write(Buf, Chunk1),
 ok = py_buffer:write(Buf, Chunk2),
 ok = py_buffer:close(Buf),
 
-%% Pass to WSGI app as wsgi.input
-py:call(Ctx, myapp, handle, [#{<<"wsgi.input">> => Buf}]).
+%% Pass to Python handler
+py:call(Ctx, myapp, handle, [Buf]).
 ```
 
 Python sees it as a file-like object with blocking reads:
 
 ```python
-def handle(environ):
-    body = environ['wsgi.input'].read()  # Blocks until data ready
+def handle(buf):
+    body = buf.read()  # Blocks until data ready
     # Or iterate lines
-    for line in environ['wsgi.input']:
+    for line in buf:
         process(line)
 ```
 
@@ -509,7 +509,7 @@ See [Buffer API](buffer.md) for zero-copy memoryview access and fast substring s
 - See [Logging and Tracing](logging.md) for Python logging and distributed tracing
 - See [AI Integration](ai-integration.md) for ML/AI examples
 - See [Asyncio Event Loop](asyncio.md) for the Erlang-native asyncio implementation with TCP and UDP support
-- See [Buffer API](buffer.md) for zero-copy WSGI input buffers
+- See [Buffer API](buffer.md) for zero-copy streaming buffers
 - See [Reactor](reactor.md) for FD-based protocol handling
 - See [Security](security.md) for sandbox and blocked operations
 - See [Distributed Execution](distributed.md) for running Python across Erlang nodes

docs/migration.md

@@ -16,16 +16,17 @@ This guide covers breaking changes and migration steps when upgrading from erlan
 
 ## Python Version Compatibility
 
-| Python Version | GIL Mode | Notes |
-|---------------|----------|-------|
-| 3.9 - 3.11 | Shared GIL | Multi-executor mode, `py:execution_mode()` returns `multi_executor` |
-| 3.12 - 3.13 | OWN_GIL subinterpreters | True parallelism, `py:execution_mode()` returns `subinterp` |
+| Python Version | Mode | Notes |
+|---------------|------|-------|
+| 3.9 - 3.11 | Multi-executor | Shared GIL, `py:execution_mode()` returns `multi_executor` |
+| 3.12+ | Multi-executor or Parallel | With `ENABLE_PARALLEL_PYTHON=ON`, uses internal parallel pool |
 | 3.13t | Free-threaded | No GIL, `py:execution_mode()` returns `free_threaded` |
-| 3.14+ | SHARED_GIL subinterpreters | Subinterpreters with shared GIL for C extension compatibility |
+
+**Note:** Subinterpreter/OWN_GIL modes are now internal implementation details used by the parallel pool build. Users don't need to select these modes directly.
 
 **Python 3.14 Support**: Full support for Python 3.14 including:
-- SHARED_GIL subinterpreter mode for C extension compatibility
-- Proper `sys.path` initialization in subinterpreters
+- Parallel pool build for true parallelism
+- Proper `sys.path` initialization
 - All asyncio features work correctly
 
 **FreeBSD Support**: Improved fd handling on FreeBSD/kqueue platforms:
@@ -34,18 +35,18 @@ This guide covers breaking changes and migration steps when upgrading from erlan
 
 ## Architecture Changes
 
-### OWN_GIL Subinterpreter Thread Pool (Python 3.12+)
+### Parallel Pool Build
 
-The most significant change in v2.0 is the new execution model. On Python 3.12+, erlang_python now uses **OWN_GIL subinterpreters** for true parallelism:
+The most significant change in v2.0 is the new execution model. When built with `ENABLE_PARALLEL_PYTHON=ON`, erlang_python uses an internal parallel pool for true parallelism:
 
 **v1.8.x Architecture:**
 - Single Python interpreter with shared GIL
 - Worker pool with round-robin dispatch
 - All workers share global state
 
-**v2.0 Architecture:**
-- N subinterpreters, each in its own thread with its own GIL
-- Each subinterpreter has isolated state (no shared globals)
+**v2.0 Architecture (with parallel build):**
+- Internal pool provides true parallelism
+- Each context has isolated state (no shared globals)
 - True parallel execution without GIL contention
 - 25-30% faster cast operations
 
@@ -85,11 +86,10 @@ Check which mode is active:
 ```erlang
 %% Check execution mode
 py:execution_mode().
-%% => subinterp     (Python 3.12+ with OWN_GIL)
-%% => free_threaded (Python 3.13t with --disable-gil)
-%% => multi_executor (Python < 3.12)
+%% => multi_executor (default worker mode)
+%% => free_threaded  (Python 3.13t with --disable-gil)
 
-%% Check if subinterpreters are supported
+%% Check if parallel execution is available
 py:subinterp_supported().
 %% => true | false
 ```