From 2dadfac73b7a70de632e196ca93a62c811036908 Mon Sep 17 00:00:00 2001
From: Andreas Kloeckner <inform@tiker.net>
Date: Sun, 7 Oct 2012 13:36:06 -0400
Subject: [PATCH] Deferred memory alloc doc updates.
---
doc/source/runtime.rst | 9 +++++++++
doc/source/tools.rst | 20 ++++++++++++++++----
2 files changed, 25 insertions(+), 4 deletions(-)
diff --git a/doc/source/runtime.rst b/doc/source/runtime.rst
index f3f84867..4dd2c14f 100644
--- a/doc/source/runtime.rst
+++ b/doc/source/runtime.rst
@@ -368,6 +368,15 @@ Buffers
:class:`Buffer` is a subclass of :class:`MemoryObject`.
+ 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.
+ That is also the point when out-of-memory errors will occur.
+ If you'd like to be sure that there's enough memory for
+ your allocation, either use :func:`enqueue_migrate_mem_objects`
+ (if available) or simply perform a small transfer to the
+ buffer. See also :class:`pyopencl.tools.ImmediateAllocator`.
+
.. method:: get_sub_region(origin, size, flags=0)
Only available in OpenCL 1.1 and newer.
diff --git a/doc/source/tools.rst b/doc/source/tools.rst
index f2f9b027..361882e7 100644
--- a/doc/source/tools.rst
+++ b/doc/source/tools.rst
@@ -35,8 +35,14 @@ the available memory.
*mem_flags* takes its values from :class:`pyopencl.mem_flags` and corresponds
to the *flags* argument of :class:`pyopencl.Buffer`. DeferredAllocator
has the same semantics as regular OpenCL buffer allocation, i.e. it may
- promise memory to be available that later on (in any call to a buffer-using
- CL function).
+ promise memory to be available that may (in any call to a buffer-using
+ CL function) turn out to not exist later on. (Allocations in CL are
+ bound to contexts, not devices, and memory availability depends on which
+ device the buffer is used with.)
+
+ .. versionchanged::
+ In version 2012.2, :class:`CLAllocator` was deprecated and replaced
+ by :class:`DeferredAllocator`.
.. method:: __call__(size)
@@ -50,13 +56,19 @@ the available memory.
promise memory to be available that later on (in any call to a buffer-using
CL function).
+ .. versionadded:: 2012.2
+
.. method:: __call__(size)
Allocate a :class:`pyopencl.Buffer` of the given *size*.
-.. class:: MemoryPool(allocator=CLAllocator())
+.. class:: MemoryPool(allocator)
- A memory pool for OpenCL device memory.
+ A memory pool for OpenCL device memory. *allocator* must be an instance of
+ one of the above classes, and should be an :class:`ImmediateAllocator`.
+ The memory pool assumes that allocation failures are reported
+ by the allocator immediately, and not in the OpenCL-typical
+ deferred manner.
.. attribute:: held_blocks
--
GitLab