You are viewing a plain text version of this content. The canonical link for it is here.
Posted to discuss-archive@tvm.apache.org by "tqchen (via GitHub)" <gi...@apache.org> on 2026/06/16 13:13:14 UTC

[PR] [DOCS] Document Python FFI conversion protocols [tvm-ffi]

tqchen opened a new pull request, #622:
URL: https://github.com/apache/tvm-ffi/pull/622

   This documents the Python argument conversion protocols recognized when calling TVM-FFI functions.
   
   Summary:
   - Add a Python guide subsection for argument conversion protocols.
   - Document the supported `__tvm_ffi_*` hooks and `__cuda_stream__` in a protocol table.
   - Point DLPack-compatible objects to the DLPack protocol documentation.
   - Add a cross-reference from the Function and Module concept page.
   
   Validation:
   - `pre-commit run --files docs/guides/python_lang_guide.md docs/concepts/func_module.rst`
   - `uv run --group docs sphinx-build -M html docs docs/_build`


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] [DOCS] Document Python FFI conversion protocols [tvm-ffi]

Posted by "gemini-code-assist[bot] (via GitHub)" <gi...@apache.org>.
gemini-code-assist[bot] commented on code in PR #622:
URL: https://github.com/apache/tvm-ffi/pull/622#discussion_r3420980635


##########
docs/guides/python_lang_guide.md:
##########
@@ -110,6 +110,59 @@ def add_one(a):
 assert tvm_ffi.get_global_func("example.add_one")(1) == 2
 ```
 
+(python-argument-conversion-protocols)=
+
+### Argument conversion protocols
+
+When Python calls a {py:class}`tvm_ffi.Function`, each argument is converted into the
+TVM FFI `Any` calling convention. Most common Python values are handled directly:
+`int`, `float`, `str`, `bytes`, `list`, `tuple`, `dict`, Python callables,
+{py:class}`tvm_ffi.Object`, {py:class}`tvm_ffi.Tensor`, DLPack-compatible tensors,
+and exceptions all have built-in conversions.
+
+Function calls also recognize the following special protocols that define
+argument conversion behavior. {py:func}`tvm_ffi.convert` also recognizes some
+of them, but it may preserve protocol objects whose final target type is only
+known when a function is called.
+
+For DLPack-compatible objects, TVM-FFI follows the
+[DLPack protocol](https://dmlc.github.io/dlpack/latest/).
+
+| Protocol | Expected return | Behavior |
+| -------- | --------------- | -------- |
+| `__tvm_ffi_object__(self)` | A {py:class}`tvm_ffi.Object` instance | Passes the returned FFI object handle directly. Use this for wrapper classes that own or expose an existing FFI object. |
+| `__tvm_ffi_value__(self)` | Another Python value | Recursively converts the returned value. This is useful for lightweight wrappers around values such as strings, arrays, maps, objects, or scalars. Conversion detects recursive cycles and reports them as conversion/type errors. |
+| `__tvm_ffi_opaque_ptr__(self)` | An integer pointer value | Passes the value as an opaque pointer. This is for low-level interop with raw memory structs. |
+| `__tvm_ffi_int__(self)` | An integer | Passes the value as an FFI integer. |
+| `__tvm_ffi_float__(self)` | A float | Passes the value as an FFI float. |
+| `__tvm_ffi_env_stream__(self)` | An integer stream handle | Used with non-CPU tensor inputs that expose DLPack. The stream is recorded in the FFI call context so the callee can observe the producer framework's current stream. |
+| `__cuda_stream__(self)` | A CUDA stream protocol object | Passes the stream as an opaque pointer. |

Review Comment:
   ![medium](https://www.gstatic.com/codereviewagent/medium-priority.svg)
   
   The `__cuda_stream__(self)` protocol method is expected to return the raw stream pointer as an integer, similar to `__tvm_ffi_env_stream__(self)`. Describing the expected return as "A CUDA stream protocol object" is misleading because the object implementing the protocol is `self`, whereas the method itself returns the integer pointer value.
   
   ```suggestion
   | `__cuda_stream__(self)` | An integer stream pointer | Passes the stream as an opaque pointer. |
   ```



-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org


Re: [PR] [DOCS] Document Python FFI conversion protocols [tvm-ffi]

Posted by "junrushao (via GitHub)" <gi...@apache.org>.
junrushao merged PR #622:
URL: https://github.com/apache/tvm-ffi/pull/622


-- 
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.

To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


---------------------------------------------------------------------
To unsubscribe, e-mail: discuss-archive-unsubscribe@tvm.apache.org
For additional commands, e-mail: discuss-archive-help@tvm.apache.org