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:
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: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
