Add threading.Thread support and documentation

Verify and document that erlang.call() works from any Python thread,
not just ThreadPoolExecutor workers. The thread worker mechanism already
supported this, but it wasn't documented or tested.

- Add tests for simple threading.Thread calling erlang.call()
- Update C code comments to mention all supported thread types
- Update CHANGELOG to reflect broader thread support
- Add docs/threading.md with usage examples and architecture

Author: benoitc

CHANGELOG.md

@@ -4,14 +4,15 @@
 
 ### Added
 
-- **ThreadPoolExecutor Support** - Python threads spawned via `concurrent.futures.ThreadPoolExecutor`
-  can now call `erlang.call()` without blocking
+- **Python Thread Support** - Any spawned Python thread can now call `erlang.call()` without blocking
+  - Supports `threading.Thread`, `concurrent.futures.ThreadPoolExecutor`, and any other Python threads
   - Each spawned thread lazily acquires a dedicated "thread worker" channel
   - One lightweight Erlang process per Python thread handles callbacks
   - Automatic cleanup when Python thread exits via `pthread_key_t` destructor
   - New module: `py_thread_handler.erl` - Coordinator and per-thread handlers
   - New C file: `py_thread_worker.c` - Thread worker pool management
   - New test suite: `test/py_thread_callback_SUITE.erl`
+  - New documentation: `docs/threading.md` - Threading support guide
 
 - **Reentrant Callbacks** - Python→Erlang→Python callback chains without deadlocks
   - Exception-based suspension mechanism interrupts Python execution cleanly

c_src/py_callback.c

@@ -542,12 +542,15 @@ static PyObject *erlang_call_impl(PyObject *self, PyObject *args) {
 
     /*
      * Check if this is a call from an executor thread (normal path) or
-     * from a spawned thread like ThreadPoolExecutor (thread worker path).
+     * from a spawned thread (thread worker path).
      */
     if (tl_current_worker == NULL || !tl_current_worker->has_callback_handler) {
         /*
-         * Not an executor thread - try thread worker path.
-         * This enables ThreadPoolExecutor threads to call erlang.call().
+         * Not an executor thread - use thread worker path.
+         * This enables any spawned Python thread to call erlang.call():
+         * - threading.Thread instances
+         * - concurrent.futures.ThreadPoolExecutor workers
+         * - Any other Python threads
          */
         Py_ssize_t nargs = PyTuple_Size(args);
         if (nargs < 1) {

c_src/py_thread_worker.c

@@ -16,12 +16,17 @@
 
 /**
  * @file py_thread_worker.c
- * @brief Thread worker pool for ThreadPoolExecutor support
+ * @brief Thread worker pool for Python thread support
  * @author Benoit Chesneau
  *
- * This module enables Python threads spawned via concurrent.futures.ThreadPoolExecutor
- * to call erlang.call() without blocking. Each spawned thread lazily acquires a
- * dedicated "thread worker" channel for communicating with Erlang.
+ * This module enables any spawned Python thread to call erlang.call() without
+ * blocking. Supported thread types include:
+ * - threading.Thread instances
+ * - concurrent.futures.ThreadPoolExecutor workers
+ * - Any other Python threads
+ *
+ * Each spawned thread lazily acquires a dedicated "thread worker" channel
+ * for communicating with Erlang.
  *
  * @par Architecture
  *

docs/threading.md

@@ -0,0 +1,176 @@
+# Threading Support
+
+erlang_python supports calling `erlang.call()` from Python threads, enabling
+concurrent Erlang callbacks from multithreaded Python code.
+
+## Supported Thread Types
+
+- `threading.Thread` - Standard Python threads
+- `concurrent.futures.ThreadPoolExecutor` - Thread pool workers
+- Any other spawned Python threads
+
+## Usage
+
+### With threading.Thread
+
+```python
+import threading
+import erlang
+
+def worker():
+    result = erlang.call('my_function', arg1, arg2)
+    print(f"Got: {result}")
+
+thread = threading.Thread(target=worker)
+thread.start()
+thread.join()
+```
+
+### With ThreadPoolExecutor
+
+```python
+from concurrent.futures import ThreadPoolExecutor
+import erlang
+
+def call_erlang(x):
+    return erlang.call('double_it', x)
+
+with ThreadPoolExecutor(max_workers=4) as executor:
+    results = list(executor.map(call_erlang, range(10)))
+```
+
+### Multiple Calls from Same Thread
+
+A single thread can make multiple sequential `erlang.call()` invocations:
+
+```python
+import threading
+import erlang
+
+def worker():
+    # Chain multiple Erlang calls
+    x = erlang.call('add_one', 0)
+    x = erlang.call('add_one', x)
+    x = erlang.call('add_one', x)
+    return x  # Returns 3
+
+thread = threading.Thread(target=worker)
+thread.start()
+thread.join()
+```
+
+## Architecture
+
+Each Python thread that calls `erlang.call()` gets:
+
+1. **A dedicated response pipe** - For receiving results from Erlang
+2. **A lightweight Erlang process** - Handles callbacks for that thread
+3. **Automatic cleanup** - Resources released when the thread exits
+
+This allows multiple Python threads to make concurrent Erlang calls without
+blocking each other.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Python Process                           │
+├─────────────────────────────────────────────────────────────────┤
+│  Thread 1           Thread 2           Thread 3                 │
+│  ┌─────────┐        ┌─────────┐        ┌─────────┐             │
+│  │ Worker  │        │ Worker  │        │ Worker  │             │
+│  │  Pipe   │        │  Pipe   │        │  Pipe   │             │
+│  └────┬────┘        └────┬────┘        └────┬────┘             │
+│       │                  │                  │                   │
+└───────┼──────────────────┼──────────────────┼───────────────────┘
+        │                  │                  │
+        ▼                  ▼                  ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Erlang VM (BEAM)                             │
+├─────────────────────────────────────────────────────────────────┤
+│  Handler 1          Handler 2          Handler 3               │
+│  (process)          (process)          (process)               │
+│       │                  │                  │                   │
+│       └──────────────────┼──────────────────┘                   │
+│                          │                                      │
+│                   ┌──────▼──────┐                               │
+│                   │ Coordinator │                               │
+│                   │  (process)  │                               │
+│                   └─────────────┘                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Thread Safety
+
+- **Isolated state** - Each thread has its own worker channel, no locks needed
+- **Concurrent calls** - Multiple threads can call `erlang.call()` simultaneously
+- **Correct delivery** - Results are delivered to the correct thread via per-thread pipes
+
+## Lifecycle
+
+1. **First call** - When a Python thread first calls `erlang.call()`:
+   - A thread worker is acquired from the pool (or created if none available)
+   - An Erlang handler process is spawned for this worker
+   - The worker is associated with the thread via `pthread_key_t`
+
+2. **Subsequent calls** - The same worker is reused for all calls from that thread
+
+3. **Thread exit** - When the Python thread terminates:
+   - The `pthread_key_t` destructor is invoked automatically
+   - The worker is released back to the pool
+   - The Erlang handler process continues to exist for potential reuse
+
+## Performance Considerations
+
+- **Worker reuse** - Workers are pooled and reused across thread lifetimes
+- **Lazy initialization** - Handlers are only spawned when first needed
+- **No GIL blocking** - The GIL is released while waiting for Erlang responses
+- **Lightweight processes** - Each Erlang handler is a lightweight BEAM process
+
+## Limitations
+
+- Threads must be Python threads (not C threads that don't hold the GIL)
+- The thread coordinator must be started (happens automatically with application start)
+
+## Registering Erlang Functions
+
+Before Python threads can call Erlang functions, register them:
+
+```erlang
+%% In Erlang
+py:register_function(double_it, fun([X]) -> X * 2 end).
+py:register_function(add_one, fun([X]) -> X + 1 end).
+```
+
+Then call from Python threads:
+
+```python
+import threading
+import erlang
+
+def worker(n):
+    return erlang.call('double_it', n)
+
+threads = [threading.Thread(target=worker, args=(i,)) for i in range(10)]
+for t in threads:
+    t.start()
+for t in threads:
+    t.join()
+```
+
+## Error Handling
+
+Errors from Erlang functions are raised as Python exceptions:
+
+```python
+import threading
+import erlang
+
+def worker():
+    try:
+        result = erlang.call('maybe_fail', 42)
+    except RuntimeError as e:
+        print(f"Erlang error: {e}")
+
+thread = threading.Thread(target=worker)
+thread.start()
+thread.join()
+```

test/py_thread_callback_SUITE.erl

@@ -1,6 +1,6 @@
-%%% @doc Common Test suite for Python ThreadPoolExecutor callback support.
+%%% @doc Common Test suite for Python thread callback support.
 %%%
-%%% Tests that Python threads spawned via concurrent.futures.ThreadPoolExecutor
+%%% Tests that Python threads (both threading.Thread and ThreadPoolExecutor)
 %%% can call erlang.call() without blocking.
 -module(py_thread_callback_SUITE).
 
@@ -20,7 +20,10 @@
     threadpool_multiple_calls_test/1,
     threadpool_nested_callback_test/1,
     threadpool_error_handling_test/1,
-    threadpool_thread_reuse_test/1
+    threadpool_thread_reuse_test/1,
+    simple_thread_basic_test/1,
+    simple_thread_multiple_calls_test/1,
+    simple_thread_concurrent_test/1
 ]).
 
 all() ->
@@ -30,7 +33,10 @@ all() ->
         threadpool_multiple_calls_test,
         threadpool_nested_callback_test,
         threadpool_error_handling_test,
-        threadpool_thread_reuse_test
+        threadpool_thread_reuse_test,
+        simple_thread_basic_test,
+        simple_thread_multiple_calls_test,
+        simple_thread_concurrent_test
     ].
 
 init_per_suite(Config) ->
@@ -132,3 +138,64 @@ threadpool_thread_reuse_test(_Config) ->
     {ok, ThreadCount} = py:eval(Code),
     true = (ThreadCount =< 2),
     ok.
+
+%%% ============================================================================
+%%% Simple threading.Thread Test Cases
+%%% ============================================================================
+
+%% @doc Simple thread calling erlang.call()
+simple_thread_basic_test(_Config) ->
+    py:register_function(double_it, fun([X]) -> X * 2 end),
+
+    %% Create a threading.Thread subclass that stores its result
+    Code = <<"
+(lambda: (
+    __import__('threading').Thread(target=lambda: setattr(__import__('sys').modules[__name__], '_result', __import__('erlang').call('double_it', 5))).start() or
+    __import__('time').sleep(0.1) or
+    getattr(__import__('sys').modules[__name__], '_result', None)
+))()
+">>,
+    {ok, Result} = py:eval(Code),
+    10 = Result,
+    ok.
+
+%% @doc Same simple thread makes multiple erlang.call() invocations
+simple_thread_multiple_calls_test(_Config) ->
+    py:register_function(add_one, fun([X]) -> X + 1 end),
+
+    %% Thread that makes 3 sequential calls: add_one(add_one(add_one(0)))
+    Code = <<"
+(lambda: (
+    __import__('threading').Thread(target=lambda: setattr(
+        __import__('sys').modules[__name__], '_result',
+        __import__('erlang').call('add_one',
+            __import__('erlang').call('add_one',
+                __import__('erlang').call('add_one', 0)))
+    )).start() or
+    __import__('time').sleep(0.1) or
+    getattr(__import__('sys').modules[__name__], '_result', None)
+))()
+">>,
+    {ok, Result} = py:eval(Code),
+    3 = Result,
+    ok.
+
+%% @doc Multiple simple threads calling erlang.call() concurrently
+simple_thread_concurrent_test(_Config) ->
+    py:register_function(double_it, fun([X]) -> X * 2 end),
+
+    %% Create 5 threads, each calling double_it with different values
+    Code = <<"
+(lambda: (
+    (threads := [__import__('threading').Thread(target=lambda x=x: setattr(t, 'result', __import__('erlang').call('double_it', x))) for x in range(5) for t in [type('T', (), {'result': None})()]]),
+    [setattr(threads[i], 'obj', type('T', (), {'result': None})()) for i in range(5)],
+    (workers := []),
+    [workers.append(type('Worker', (__import__('threading').Thread,), {'result': None, 'run': lambda self, x=x: setattr(self, 'result', __import__('erlang').call('double_it', x))})()) for x in range(5)],
+    [w.start() for w in workers],
+    [w.join() for w in workers],
+    [w.result for w in workers]
+)[-1])()
+">>,
+    {ok, Results} = py:eval(Code),
+    [0, 2, 4, 6, 8] = Results,
+    ok.