Merge pull request #129 from bgilbert/cache

Support OpenSlide cache management API

Author: bgilbert

doc/index.rst

@@ -177,11 +177,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
@@ -259,6 +283,11 @@ Exceptions
    OpenSlide does not support the requested file.  Subclass of
    :exc:`OpenSlideError`.
 
+.. exception:: OpenSlideVersionError
+
+   This version of OpenSlide does not support the requested functionality.
+   Subclass of :exc:`OpenSlideError`.
+
 
 Wrapping a PIL Image
 ====================

examples/deepzoom/deepzoom_multiserver.py

@@ -3,6 +3,7 @@
 # deepzoom_multiserver - Example web application for viewing multiple slides
 #
 # Copyright (c) 2010-2015 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
@@ -43,11 +44,12 @@
 else:
     import openslide
 
-from openslide import OpenSlide, OpenSlideError
+from openslide import OpenSlide, OpenSlideCache, OpenSlideError
 from openslide.deepzoom import DeepZoomGenerator
 
 SLIDE_DIR = '.'
 SLIDE_CACHE_SIZE = 10
+SLIDE_TILE_CACHE_MB = 128
 DEEPZOOM_FORMAT = 'jpeg'
 DEEPZOOM_TILE_SIZE = 254
 DEEPZOOM_OVERLAP = 1
@@ -60,11 +62,13 @@
 
 
 class _SlideCache:
-    def __init__(self, cache_size, dz_opts):
+    def __init__(self, cache_size, tile_cache_mb, dz_opts):
         self.cache_size = cache_size
         self.dz_opts = dz_opts
         self._lock = Lock()
         self._cache = OrderedDict()
+        # Share a single tile cache among all slide handles
+        self._tile_cache = OpenSlideCache(tile_cache_mb * 1024 * 1024)
 
     def get(self, path):
         with self._lock:
@@ -75,6 +79,7 @@ def get(self, path):
                 return slide
 
         osr = OpenSlide(path)
+        osr.set_cache(self._tile_cache)
         slide = DeepZoomGenerator(osr, **self.dz_opts)
         try:
             mpp_x = osr.properties[openslide.PROPERTY_NAME_MPP_X]
@@ -121,7 +126,9 @@ def _setup():
         'DEEPZOOM_LIMIT_BOUNDS': 'limit_bounds',
     }
     opts = {v: app.config[k] for k, v in config_map.items()}
-    app.cache = _SlideCache(app.config['SLIDE_CACHE_SIZE'], opts)
+    app.cache = _SlideCache(
+        app.config['SLIDE_CACHE_SIZE'], app.config['SLIDE_TILE_CACHE_MB'], opts
+    )
 
 
 def _get_slide(path):

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
@@ -30,7 +31,11 @@
 
 # For the benefit of library users
 from openslide._version import __version__  # noqa: F401  module-imported-but-unused
-from openslide.lowlevel import OpenSlideError, OpenSlideUnsupportedFormatError
+from openslide.lowlevel import (  # noqa: F401  module-imported-but-unused
+    OpenSlideError,
+    OpenSlideUnsupportedFormatError,
+    OpenSlideVersionError,
+)
 
 __library_version__ = lowlevel.get_version()
 
@@ -119,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.
 
@@ -226,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):
@@ -266,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."""
 
@@ -378,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

@@ -2,7 +2,7 @@
 # openslide-python - Python bindings for the OpenSlide library
 #
 # Copyright (c) 2010-2013 Carnegie Mellon University
-# 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
@@ -37,6 +37,7 @@
     c_double,
     c_int32,
     c_int64,
+    c_size_t,
     c_uint32,
     c_void_p,
     cdll,
@@ -90,6 +91,17 @@ class OpenSlideError(Exception):
     """
 
 
+class OpenSlideVersionError(OpenSlideError):
+    """This version of OpenSlide does not support the requested functionality.
+
+    Import this from openslide rather than from openslide.lowlevel.
+    """
+
+    def __init__(self, minimum_version):
+        super().__init__(f'OpenSlide >= {minimum_version} required')
+        self.minimum_version = minimum_version
+
+
 class OpenSlideUnsupportedFormatError(OpenSlideError):
     """OpenSlide does not support the requested file.
 
@@ -125,6 +137,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."""
 
@@ -138,6 +171,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)
@@ -160,6 +205,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:
@@ -189,8 +239,18 @@ def _check_name_list(result, func, args):
 
 
 # resolve and return an OpenSlide function with the specified properties
-def _func(name, restype, argtypes, errcheck=_check_error):
-    func = getattr(_lib, name)
+def _func(name, restype, argtypes, errcheck=_check_error, minimum_version=None):
+    try:
+        func = getattr(_lib, name)
+    except AttributeError:
+        if minimum_version is None:
+            raise
+
+        # optional function doesn't exist; fail at runtime
+        def function_unavailable(*_args):
+            raise OpenSlideVersionError(minimum_version)
+
+        return function_unavailable
     func.argtypes = argtypes
     func.restype = restype
     if errcheck is not None:
@@ -201,7 +261,7 @@ def _func(name, restype, argtypes, errcheck=_check_error):
 try:
     detect_vendor = _func('openslide_detect_vendor', c_char_p, [_utf8_p], _check_string)
 except AttributeError:
-    raise OpenSlideError('OpenSlide >= 3.4.0 required')
+    raise OpenSlideVersionError('3.4.0')
 
 open = _func('openslide_open', c_void_p, [_utf8_p], _check_open)
 
@@ -295,3 +355,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