Support OpenSlide cache management API

Author: bgilbert

doc/index.rst

@@ -138,11 +138,35 @@ OpenSlide objects
       :param tuple size: the maximum size of the thumbnail as a
          ``(width, height)`` tuple
 
+   .. method:: set_cache(cache)
+
+      Use the specified :class:`OpenSlideCache` to store recently decoded
+      slide tiles.  By default, the :class:`OpenSlide` has a private cache
+      with a default size.
+
+      :param OpenSlideCache cache: a cache object
+      :raises OpenSlideVersionError: if OpenSlide is older than version 3.5.0
+
    .. method:: close()
 
       Close the OpenSlide object.
 
 
+Caching
+-------
+
+.. class:: OpenSlideCache(capacity)
+
+   An in-memory tile cache.
+
+   Tile caches can be attached to one or more :class:`OpenSlide` objects
+   with :meth:`OpenSlide.set_cache` to cache recently-decoded tiles.  By
+   default, each :class:`OpenSlide` has its own cache with a default size.
+
+   :param int capacity: the cache capacity in bytes
+   :raises OpenSlideVersionError: if OpenSlide is older than version 3.5.0
+
+
 .. _standard-properties:
 
 Standard properties

openslide/__init__.py

@@ -2,6 +2,7 @@
 # openslide-python - Python bindings for the OpenSlide library
 #
 # Copyright (c) 2010-2014 Carnegie Mellon University
+# Copyright (c) 2021      Benjamin Gilbert
 #
 # This library is free software; you can redistribute it and/or modify it
 # under the terms of version 2.1 of the GNU Lesser General Public License
@@ -123,6 +124,12 @@ def read_region(self, location, level, size):
         size:     (width, height) tuple giving the region size."""
         raise NotImplementedError
 
+    def set_cache(self, cache):
+        """Use the specified cache to store recently decoded slide tiles.
+
+        cache: an OpenSlideCache object."""
+        raise NotImplementedError
+
     def get_thumbnail(self, size):
         """Return a PIL.Image containing an RGB thumbnail of the image.
 
@@ -230,6 +237,18 @@ def read_region(self, location, level, size):
             self._osr, location[0], location[1], level, size[0], size[1]
         )
 
+    def set_cache(self, cache):
+        """Use the specified cache to store recently decoded slide tiles.
+
+        By default, the object has a private cache with a default size.
+
+        cache: an OpenSlideCache object."""
+        try:
+            llcache = cache._openslide_cache
+        except AttributeError:
+            raise TypeError('Not a cache object')
+        lowlevel.set_cache(self._osr, llcache)
+
 
 class _OpenSlideMap(Mapping):
     def __init__(self, osr):
@@ -270,6 +289,23 @@ def __getitem__(self, key):
         return lowlevel.read_associated_image(self._osr, key)
 
 
+class OpenSlideCache:
+    """An in-memory tile cache.
+
+    Tile caches can be attached to one or more OpenSlide objects with
+    OpenSlide.set_cache() to cache recently-decoded tiles.  By default,
+    each OpenSlide object has its own cache with a default size.
+    """
+
+    def __init__(self, capacity):
+        """Create a tile cache with the specified capacity in bytes."""
+        self._capacity = capacity
+        self._openslide_cache = lowlevel.cache_create(capacity)
+
+    def __repr__(self):
+        return f'{self.__class__.__name__}({self._capacity!r})'
+
+
 class ImageSlide(AbstractSlide):
     """A wrapper for a PIL.Image that provides the OpenSlide interface."""
 
@@ -382,6 +418,14 @@ def read_region(self, location, level, size):
             tile.paste(crop, tile_offset)
         return tile
 
+    def set_cache(self, cache):
+        """Use the specified cache to store recently decoded slide tiles.
+
+        ImageSlide does not support caching, so this method does nothing.
+
+        cache: an OpenSlideCache object."""
+        pass
+
 
 def open_slide(filename):
     """Open a whole-slide or regular image.

openslide/lowlevel.py

@@ -37,6 +37,7 @@
     c_double,
     c_int32,
     c_int64,
+    c_size_t,
     c_uint32,
     c_void_p,
     cdll,
@@ -122,6 +123,27 @@ def from_param(cls, obj):
         return obj
 
 
+class _OpenSlideCache:
+    """Wrapper class to make sure we correctly pass an OpenSlide cache."""
+
+    def __init__(self, ptr):
+        self._as_parameter_ = ptr
+        # Retain a reference to cache_release() to avoid GC problems during
+        # interpreter shutdown
+        self._cache_release = cache_release
+
+    def __del__(self):
+        self._cache_release(self)
+
+    @classmethod
+    def from_param(cls, obj):
+        if obj.__class__ != cls:
+            raise ValueError("Not an OpenSlide cache reference")
+        if not obj._as_parameter_:
+            raise ValueError("Passing undefined cache object")
+        return obj
+
+
 class _utf8_p:
     """Wrapper class to convert string arguments to bytes."""
 
@@ -135,6 +157,18 @@ def from_param(cls, obj):
             raise TypeError('Incorrect type')
 
 
+class _size_t:
+    """Wrapper class to convert size_t arguments to c_size_t."""
+
+    @classmethod
+    def from_param(cls, obj):
+        if not isinstance(obj, int):
+            raise TypeError('Incorrect type')
+        if obj < 0:
+            raise ValueError('Value out of range')
+        return c_size_t(obj)
+
+
 def _load_image(buf, size):
     '''buf must be a mutable buffer.'''
     _convert.argb2rgba(buf)
@@ -157,6 +191,11 @@ def _check_close(_result, _func, args):
     args[0].invalidate()
 
 
+# wrap the handle returned when creating a cache
+def _check_cache_create(result, _func, _args):
+    return _OpenSlideCache(c_void_p(result))
+
+
 # Convert returned byte array, if present, into a string
 def _check_string(result, func, _args):
     if func.restype is c_char_p and result is not None:
@@ -302,3 +341,23 @@ def read_associated_image(slide, name):
 
 
 get_version = _func('openslide_get_version', c_char_p, [], _check_string)
+
+cache_create = _func(
+    'openslide_cache_create',
+    c_void_p,
+    [_size_t],
+    _check_cache_create,
+    minimum_version='3.5.0',
+)
+
+set_cache = _func(
+    'openslide_set_cache',
+    None,
+    [_OpenSlide, _OpenSlideCache],
+    None,
+    minimum_version='3.5.0',
+)
+
+cache_release = _func(
+    'openslide_cache_release', None, [_OpenSlideCache], None, minimum_version='3.5.0'
+)

tests/__init__.py

@@ -1,7 +1,7 @@
 #
 # openslide-python - Python bindings for the OpenSlide library
 #
-# Copyright (c) 2016 Benjamin Gilbert
+# Copyright (c) 2016-2021 Benjamin Gilbert
 #
 # This library is free software; you can redistribute it and/or modify it
 # under the terms of version 2.1 of the GNU Lesser General Public License
@@ -17,6 +17,7 @@
 # Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 #
 
+from functools import wraps
 import os
 from pathlib import Path
 
@@ -42,6 +43,7 @@
 
             os.environ['PATH'] = _orig_path
 
+from openslide import OpenSlideVersionError
 
 # PIL.Image cannot have zero width or height on Pillow 3.4.0 - 3.4.2
 # https://github.com/python-pillow/Pillow/issues/2259
@@ -54,3 +56,17 @@
 
 def file_path(name):
     return Path(__file__).parent / name
+
+
+def maybe_supported(f):
+    '''Decorator to ignore test failures caused by an OpenSlide version that
+    doesn't support the tested functionality.'''
+
+    @wraps(f)
+    def wrapper(*args, **kwargs):
+        try:
+            return f(*args, **kwargs)
+        except OpenSlideVersionError:
+            pass
+
+    return wrapper

tests/test_imageslide.py

@@ -1,7 +1,7 @@
 #
 # openslide-python - Python bindings for the OpenSlide library
 #
-# Copyright (c) 2016 Benjamin Gilbert
+# Copyright (c) 2016-2021 Benjamin Gilbert
 #
 # This library is free software; you can redistribute it and/or modify it
 # under the terms of version 2.1 of the GNU Lesser General Public License
@@ -22,9 +22,9 @@
 
 from PIL import Image
 
-from openslide import ImageSlide, OpenSlideError
+from openslide import ImageSlide, OpenSlideCache, OpenSlideError
 
-from . import file_path, image_dimensions_cannot_be_zero
+from . import file_path, image_dimensions_cannot_be_zero, maybe_supported
 
 
 @contextmanager
@@ -118,3 +118,8 @@ def test_read_region_bad_size(self):
 
     def test_thumbnail(self):
         self.assertEqual(self.osr.get_thumbnail((100, 100)).size, (100, 83))
+
+    @maybe_supported
+    def test_set_cache(self):
+        self.osr.set_cache(OpenSlideCache(64 << 10))
+        self.assertEqual(self.osr.read_region((0, 0), 0, (400, 400)).size, (400, 400))

tests/test_openslide.py

@@ -1,7 +1,7 @@
 #
 # openslide-python - Python bindings for the OpenSlide library
 #
-# Copyright (c) 2016 Benjamin Gilbert
+# Copyright (c) 2016-2021 Benjamin Gilbert
 #
 # This library is free software; you can redistribute it and/or modify it
 # under the terms of version 2.1 of the GNU Lesser General Public License
@@ -24,9 +24,24 @@
 
 from PIL import Image
 
-from openslide import OpenSlide, OpenSlideError, OpenSlideUnsupportedFormatError
+from openslide import (
+    OpenSlide,
+    OpenSlideCache,
+    OpenSlideError,
+    OpenSlideUnsupportedFormatError,
+)
 
-from . import file_path, image_dimensions_cannot_be_zero
+from . import file_path, image_dimensions_cannot_be_zero, maybe_supported
+
+
+class TestCache(unittest.TestCase):
+    @maybe_supported
+    def test_create_cache(self):
+        OpenSlideCache(0)
+        OpenSlideCache(1)
+        OpenSlideCache(4 << 20)
+        self.assertRaises(ArgumentError, lambda: OpenSlideCache(-1))
+        self.assertRaises(ArgumentError, lambda: OpenSlideCache(1.3))
 
 
 class TestSlideWithoutOpening(unittest.TestCase):
@@ -138,6 +153,13 @@ def _test_read_region_2GB(self):
     def test_thumbnail(self):
         self.assertEqual(self.osr.get_thumbnail((100, 100)).size, (100, 83))
 
+    @maybe_supported
+    def test_set_cache(self):
+        self.osr.set_cache(OpenSlideCache(64 << 10))
+        self.assertEqual(self.osr.read_region((0, 0), 0, (400, 400)).size, (400, 400))
+        self.assertRaises(TypeError, lambda: self.osr.set_cache(None))
+        self.assertRaises(TypeError, lambda: self.osr.set_cache(3))
+
 
 class TestAperioSlide(_SlideTest, unittest.TestCase):
     FILENAME = 'small.svs'