This is an automated email from the ASF dual-hosted git repository.
desruisseaux pushed a commit to branch geoapi-4.0
in repository https://gitbox.apache.org/repos/asf/sis.git
The following commit(s) were added to refs/heads/geoapi-4.0 by this push:
new 7bc9a9e Document better the rational about `SoftReference` in caches,
and replace one `SoftReference` by `WeakReference` for reducing memory
retention.
7bc9a9e is described below
commit 7bc9a9e91bffa6257bc8be7d64d42747e80ae289
Author: Martin Desruisseaux <[email protected]>
AuthorDate: Thu Jan 28 23:08:43 2021 +0100
Document better the rational about `SoftReference` in caches, and replace
one `SoftReference` by `WeakReference` for reducing memory retention.
---
.../main/java/org/apache/sis/image/TileCache.java | 24 ++++++++++++++--------
.../referencing/provider/DatumShiftGridFile.java | 11 +++++++---
.../apache/sis/internal/netcdf/GridCacheKey.java | 4 ++--
3 files changed, 25 insertions(+), 14 deletions(-)
diff --git a/core/sis-feature/src/main/java/org/apache/sis/image/TileCache.java
b/core/sis-feature/src/main/java/org/apache/sis/image/TileCache.java
index f381bd3..3d4fead 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/image/TileCache.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/image/TileCache.java
@@ -30,6 +30,13 @@ import org.apache.sis.internal.feature.Resources;
* Tiles are kept by strong references until a memory usage limit is reached,
in which case
* the references of oldest tiles become soft references.
*
+ * <h2>Design note</h2>
+ * The use of a common cache for all images makes easier to set an
application-wide limit
+ * (for example 25% of available memory). The use of soft reference does not
cause as much
+ * memory retention as it may seem because those references are hold only as
long as the
+ * image exist. When an image is garbage collected, the corresponding soft
references are
+ * {@linkplain Key#dispose() cleaned}.
+ *
* @author Martin Desruisseaux (Geomatys)
* @version 1.1
* @since 1.1
@@ -43,15 +50,13 @@ final class TileCache extends Cache<TileCache.Key, Raster> {
static final TileCache GLOBAL = new TileCache();
/**
- * Creates a new tile cache.
+ * Creates a new tile cache. We put an arbitrary limit of 25% of available
memory.
+ * If more tiles are created, some strong references will become soft
references.
+ * Because strong references may be kept by the JVM, the amount of memory
actually
+ * used may be greater than this limit. However those references are
cleaned when the
+ * image owning those tiles is {@linkplain ComputedTiles#dispose() garbage
collected}.
*/
private TileCache() {
- /*
- * We put an arbitrary limit of 25% of available memory. If more tiles
are created,
- * some strong references will become soft references. Since strong
references may
- * be kept by the JVM, the amount of memory actually used may be
greater than this
- * limit.
- */
super(100, Runtime.getRuntime().maxMemory() / 4, true);
}
@@ -119,8 +124,9 @@ final class TileCache extends Cache<TileCache.Key, Raster> {
}
/**
- * Removes the raster associated to this key. This method is invoked
- * for all tiles in an image being disposed.
+ * Removes the raster associated to this key. This method is invoked
for all tiles in an image being disposed.
+ * The disposal may happen either by an explicit call to {@link
ComputedImage#dispose()}, or because the image
+ * has been {@linkplain ComputedTiles#dispose() garbage collected}.
*/
final void dispose() {
GLOBAL.remove(this);
diff --git
a/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/DatumShiftGridFile.java
b/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/DatumShiftGridFile.java
index be13d1a..f32f1fb 100644
---
a/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/DatumShiftGridFile.java
+++
b/core/sis-referencing/src/main/java/org/apache/sis/internal/referencing/provider/DatumShiftGridFile.java
@@ -80,9 +80,14 @@ abstract class DatumShiftGridFile<C extends Quantity<C>, T
extends Quantity<T>>
private static final long serialVersionUID = -5801692909082130314L;
/**
- * Cache of grids loaded so far. Those grids will be stored by soft
references until the amount of
- * data exceed 32768 (about 128 kilobytes if the values use the {@code
float} type). in which case
- * the oldest grids will be replaced by weak references.
+ * Cache of grids loaded so far. The keys are typically {@link
java.nio.file.Path}s or a tuple of paths.
+ * Values are grids stored by hard references until the amount of data
exceed 32768 (about 128 kilobytes
+ * if the values use the {@code float} type), in which case the oldest
grids will be replaced by soft references.
+ *
+ * <h2>Memory consumption</h2>
+ * The use of soft references instead than weak references is on the
assumption that users typically use
+ * the same few Coordinate Reference Systems for their work. Consequently
we presume that users will not
+ * load a lot of grids and are likely to reuse the already loaded grids.
*/
static final Cache<Object, DatumShiftGridFile<?,?>> CACHE = new
Cache<Object, DatumShiftGridFile<?,?>>(4, 32*1024, true) {
@Override protected int cost(final DatumShiftGridFile<?,?> grid) {
diff --git
a/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/GridCacheKey.java
b/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/GridCacheKey.java
index 5d14b2a..c69df17 100644
---
a/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/GridCacheKey.java
+++
b/storage/sis-netcdf/src/main/java/org/apache/sis/internal/netcdf/GridCacheKey.java
@@ -116,9 +116,9 @@ class GridCacheKey {
*/
static final class Global extends GridCacheKey {
/**
- * The global cache shared by all netCDF files. All grids are retained
by soft references.
+ * The global cache shared by all netCDF files. All grids are retained
by weak references.
*/
- private static final Cache<GridCacheKey,MathTransform> CACHE = new
Cache<>(12, 0, true);
+ private static final Cache<GridCacheKey,MathTransform> CACHE = new
Cache<>(12, 0, false);
/**
* The algorithms tried for making the localization grids more linear.
