Add channel reference round-trip conversion support

- Add PyCapsule conversion for channel resources in py_convert.c
- Channel refs are wrapped in PyCapsule when passed to Python
- PyCapsule is unwrapped back to channel resource when returned to Erlang
- Add test_channel_ref.py module for testing py:call with channel refs
- Add channel_ref_roundtrip_test to validate basic eval conversion
- Add channel_ref_call_test to validate py:call with channel ref args

Author: benoitc

c_src/py_convert.c

@@ -49,6 +49,22 @@
 /* Stack allocation threshold for small tuples/maps to avoid heap allocation */
 #define SMALL_CONTAINER_THRESHOLD 16
 
+/* Capsule name for channel references */
+#define CHANNEL_CAPSULE_NAME "erlang.channel_ref"
+
+/**
+ * @brief PyCapsule destructor for channel references
+ *
+ * Called when a PyCapsule wrapping a channel resource is garbage collected.
+ * Releases the resource reference that was kept when the capsule was created.
+ */
+static void channel_capsule_destructor(PyObject *capsule) {
+    void *ptr = PyCapsule_GetPointer(capsule, CHANNEL_CAPSULE_NAME);
+    if (ptr != NULL) {
+        enif_release_resource(ptr);
+    }
+}
+
 /* ============================================================================
  * Python to Erlang Conversion
  * ============================================================================ */
@@ -334,6 +350,18 @@ static ERL_NIF_TERM py_to_term(ErlNifEnv *env, PyObject *obj) {
         PyErr_Clear();
     }
 
+    /* Handle PyCapsule containing channel reference */
+    if (PyCapsule_CheckExact(obj)) {
+        void *ptr = PyCapsule_GetPointer(obj, CHANNEL_CAPSULE_NAME);
+        if (ptr != NULL) {
+            /* This is a channel reference capsule - convert back to resource term */
+            py_channel_t *channel = (py_channel_t *)ptr;
+            return enif_make_resource(env, channel);
+        }
+        /* Not a channel capsule, clear error and fall through */
+        PyErr_Clear();
+    }
+
     /*
      * Fallback: convert any other object to its string representation.
      * This handles custom classes, functions, modules, etc.
@@ -552,6 +580,21 @@ static PyObject *term_to_py(ErlNifEnv *env, ERL_NIF_TERM term) {
         return wrapper->obj;
     }
 
+    /* Check for channel resource - wrap in PyCapsule for round-trip */
+    py_channel_t *channel;
+    if (enif_get_resource(env, term, CHANNEL_RESOURCE_TYPE, (void **)&channel)) {
+        /* Create a PyCapsule wrapping the channel pointer.
+         * We increment the resource refcount so it stays valid while Python holds it.
+         * The destructor will decrement it when the capsule is garbage collected. */
+        enif_keep_resource(channel);
+        PyObject *capsule = PyCapsule_New(channel, CHANNEL_CAPSULE_NAME, channel_capsule_destructor);
+        if (capsule == NULL) {
+            enif_release_resource(channel);
+            return NULL;
+        }
+        return capsule;
+    }
+
     /* Fallback: return None for unknown types */
     Py_RETURN_NONE;
 }

priv/test_channel_ref.py

@@ -0,0 +1,14 @@
+# Test module for channel reference passing via py:call
+
+def identity(x):
+    """Return the argument unchanged."""
+    return x
+
+def get_channel_type(ch_ref):
+    """Return the type name of the channel reference."""
+    return type(ch_ref).__name__
+
+def store_and_return(ch_ref):
+    """Store in a list and return."""
+    container = [ch_ref]
+    return container[0]

test/py_channel_SUITE.erl

@@ -29,7 +29,9 @@
     async_receive_immediate_test/1,
     async_receive_wait_test/1,
     async_iteration_test/1,
-    async_closed_channel_test/1
+    async_closed_channel_test/1,
+    channel_ref_roundtrip_test/1,
+    channel_ref_call_test/1
 ]).
 
 all() -> [
@@ -48,7 +50,9 @@ all() -> [
     async_receive_immediate_test,
     async_receive_wait_test,
     async_iteration_test,
-    async_closed_channel_test
+    async_closed_channel_test,
+    channel_ref_roundtrip_test,
+    channel_ref_call_test
 ].
 
 init_per_suite(Config) ->
@@ -287,3 +291,56 @@ async_closed_channel_test(_Config) ->
     {ok, true} = py:eval(Ctx, <<"issubclass(ChannelClosed, Exception)">>),
 
     ok.
+
+%% @doc Test that channel references can be passed to Python and back via eval
+channel_ref_roundtrip_test(_Config) ->
+    {ok, Ch} = py_channel:new(),
+
+    %% Pass channel ref to Python via NIF and get it back
+    %% This tests the PyCapsule conversion in py_convert.c
+    {ok, ReturnedRef} = py:eval(<<"ch_ref">>, #{<<"ch_ref">> => Ch}),
+
+    %% The returned ref should be usable as a channel
+    %% Send data through original channel
+    ok = py_channel:send(Ch, <<"test_data">>),
+
+    %% Receive using the returned ref (should be the same channel)
+    {ok, <<"test_data">>} = py_nif:channel_try_receive(ReturnedRef),
+
+    %% Verify channel info works on returned ref
+    Info = py_channel:info(ReturnedRef),
+    false = maps:get(closed, Info),
+
+    ok = py_channel:close(Ch).
+
+%% @doc Test that channel references can be passed via py:call
+channel_ref_call_test(_Config) ->
+    {ok, Ch} = py_channel:new(),
+
+    %% Test passing channel ref through py:call to a Python function
+    %% The test_channel_ref module has identity, get_channel_type, store_and_return
+    {ok, ReturnedRef} = py:call(test_channel_ref, identity, [Ch]),
+
+    %% The returned ref should be usable as a channel
+    ok = py_channel:send(Ch, <<"identity_data">>),
+    {ok, <<"identity_data">>} = py_nif:channel_try_receive(ReturnedRef),
+
+    %% Test that Python sees it as a PyCapsule
+    {ok, <<"PyCapsule">>} = py:call(test_channel_ref, get_channel_type, [Ch]),
+
+    %% Test storing in a container and returning
+    {ok, StoredRef} = py:call(test_channel_ref, store_and_return, [Ch]),
+
+    ok = py_channel:send(Ch, <<"stored_data">>),
+    {ok, <<"stored_data">>} = py_nif:channel_try_receive(StoredRef),
+
+    %% Also test passing through containers via eval
+    {ok, [Ref1, Ref2]} = py:eval(<<"[a, b]">>, #{<<"a">> => Ch, <<"b">> => Ch}),
+
+    ok = py_channel:send(Ch, <<"ref1_data">>),
+    {ok, <<"ref1_data">>} = py_nif:channel_try_receive(Ref1),
+
+    ok = py_channel:send(Ch, <<"ref2_data">>),
+    {ok, <<"ref2_data">>} = py_nif:channel_try_receive(Ref2),
+
+    ok = py_channel:close(Ch).