From d1c9724760989dd8fc8ffc0d62932ad25f379a3e Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Fri, 14 Nov 2014 08:59:50 -0600
Subject: [PATCH] Improve docs on buffer/buffer obj ambiguity
---
doc/runtime.rst | 9 +++++++++
pyopencl/__init__.py | 9 +++++++++
2 files changed, 18 insertions(+)
diff --git a/doc/runtime.rst b/doc/runtime.rst
index b809211b..52d2a521 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 9ca61fe7..ec948cc3 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
.. ------------------------------------------------------------------------
--
GitLab