diff --git a/doc/runtime.rst b/doc/runtime.rst index b809211b86a89fe8d54373b335f9cc54eaa1b69a..52d2a5210888e0a2f5c17e8ce22d552358436cf3 100644 --- a/doc/runtime.rst +++ b/doc/runtime.rst @@ -386,6 +386,15 @@ Buffers :class:`Buffer` inherits from :class:`MemoryObject`. + .. note:: + + Python also defines a type of `buffer object + <https://docs.python.org/3.4/c-api/buffer.html>`_, + and PyOpenCL interacts with those, too, as the host-side + target of :func:`enqueue_copy`. Make sure to always be + clear on whether a :class:`Buffer` or a Python buffer + object is needed. + Note that actual memory allocation in OpenCL may be deferred. Buffers are attached to a :class:`Context` and are only moved to a device once the buffer is used on that device. diff --git a/pyopencl/__init__.py b/pyopencl/__init__.py index 9ca61fe7785043b2ba18a92aeb3c73384fd424b3..ec948cc31ab64f9162e52209c8cd377bb141163a 100644 --- a/pyopencl/__init__.py +++ b/pyopencl/__init__.py @@ -954,6 +954,15 @@ def enqueue_copy(queue, dest, src, **kwargs): :return: A :class:`NannyEvent` if the transfer involved a host-side buffer, otherwise an :class:`Event`. + .. note:: + + Two types of 'buffer' occur in the arguments to this function, + :class:`Buffer` and 'host-side buffers'. The latter are + defined by Python and commonly called `buffer objects + <https://docs.python.org/3.4/c-api/buffer.html>`_. + Make sure to always be clear on whether a :class:`Buffer` or a + Python buffer object is needed. + .. ------------------------------------------------------------------------ .. rubric :: Transfer :class:`Buffer` ↔ host .. ------------------------------------------------------------------------