Merge pull request #4013 from leofang/plan_cache_doc

Improve the plan cache documentation
cupy · Sep 28, 2020 · 5d13d79 · 5d13d79
2 parents 049909a + a473795
commit 5d13d79
Show file tree

Hide file tree

Showing 3 changed files with 17 additions and 6 deletions.
diff --git a/cupy/fft/_cache.pyx b/cupy/fft/_cache.pyx
@@ -192,7 +192,8 @@ cdef class PlanCache:
 
         2. This class can be instantiated by users, but it is discouraged.
            Instead, we expect the following canonical usage pattern to
-           retrieve a handle to the cache through :func:`get_plan_cache`:
+           retrieve a handle to the cache through
+           :func:`~cupy.fft.config.get_plan_cache`:
 
            .. code-block:: python
 
@@ -204,8 +205,8 @@ cdef class PlanCache:
                    cache = get_plan_cache()
                    cache.set_size(0)  # disable the cache
 
-           In particular, the cache for device n should be manipulated under
-           the device n's context.
+           In particular, the cache for device ``n`` should be manipulated
+           under device ``n``'s context.
 
         3. This class is thread-safe since by default it is created on a
            per-thread basis. When starting a new thread, a new cache is not
@@ -583,7 +584,7 @@ cpdef inline PlanCache get_plan_cache():
     """Get the per-thread, per-device plan cache, or create one if not found.
 
     .. seealso::
-        :class:`~cupy.fft.cache.PlanCache`
+        :class:`~cupy.fft._cache.PlanCache`
 
     """
     cdef _ThreadLocal tls = _ThreadLocal.get()
@@ -635,7 +636,7 @@ cpdef show_plan_cache_info():
     """Show all of the plan caches' info on this thread.
 
     .. seealso::
-        :class:`~cupy.fft.cache.PlanCache`
+        :class:`~cupy.fft._cache.PlanCache`
 
     """
 

diff --git a/docs/source/reference/fft.rst b/docs/source/reference/fft.rst
@@ -57,7 +57,6 @@ Helper routines
    cupy.fft.rfftfreq
    cupy.fft.fftshift
    cupy.fft.ifftshift
-   cupy.fft._cache.PlanCache
    cupy.fft.config.set_cufft_gpus
    cupy.fft.config.get_plan_cache
    cupy.fft.config.show_plan_cache_info
@@ -78,6 +77,8 @@ Internally, ``cupy.fft`` always generates a *cuFFT plan* (see the `cuFFT documen
 
 Moreover, the automatic plan generation can be suppressed by using an existing plan returned by :func:`cupyx.scipy.fftpack.get_fft_plan` as a context manager. This is again a deviation from NumPy.
 
+Finally, when using the high-level NumPy-like FFT APIs as listed above, internally the cuFFT plans are cached for possible reuse. The plan cache can be retrieved by :func:`~cupy.fft.config.get_plan_cache`, and its current status can be queried by :func:`~cupy.fft.config.show_plan_cache_info`. For finer control of the plan cache, see :doc:`plan_cache`.
+
 
 Multi-GPU FFT
 -------------

diff --git a/docs/source/reference/plan_cache.rst b/docs/source/reference/plan_cache.rst
@@ -0,0 +1,9 @@
+:orphan:
+
+
+cuFFT Plan Cache
+----------------
+
+.. autoclass:: cupy.fft._cache.PlanCache
+   :members:
+   :undoc-members: