sis-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From desruisse...@apache.org
Subject [sis] branch geoapi-4.0 updated: Documentation update, in particular about WritableRenderedImage synchronization issue. https://issues.apache.org/jira/browse/SIS-487
Date Wed, 08 Jan 2020 11:44:44 GMT
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 0773330  Documentation update, in particular about WritableRenderedImage synchronization
issue. https://issues.apache.org/jira/browse/SIS-487
0773330 is described below

commit 077333025a1d2fcf0a554aee37687b241a3f53cc
Author: Martin Desruisseaux <martin.desruisseaux@geomatys.com>
AuthorDate: Wed Jan 8 12:38:35 2020 +0100

    Documentation update, in particular about WritableRenderedImage synchronization issue.
    https://issues.apache.org/jira/browse/SIS-487
---
 .../java/org/apache/sis/image/ComputedImage.java   | 33 +++++++++++++---------
 .../java/org/apache/sis/image/PlanarImage.java     | 14 +++++----
 .../factory/MultiAuthoritiesFactory.java           |  2 +-
 3 files changed, 30 insertions(+), 19 deletions(-)

diff --git a/core/sis-feature/src/main/java/org/apache/sis/image/ComputedImage.java b/core/sis-feature/src/main/java/org/apache/sis/image/ComputedImage.java
index af6b96d..62bcd15 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/image/ComputedImage.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/image/ComputedImage.java
@@ -93,16 +93,22 @@ import org.apache.sis.internal.feature.Resources;
  *
  * <h2>Writable computed images</h2>
  * {@code ComputedImage} can itself be a {@link WritableRenderedImage} if subclasses decide
so.
- * A writable computed image is an image which can retro-propagate changes of its values
to the source images.
+ * A writable computed image is an image which can retro-propagate sample value changes to
the source images.
  * This class provides {@link #hasTileWriters()}, {@link #getWritableTileIndices()}, {@link
#isTileWritable(int, int)}
- * and {@link #markTileWritable(int, int, boolean)} methods for making {@link WritableRenderedImage}
implementations easier.
+ * and {@link #markTileWritable(int, int, boolean)} methods for {@link WritableRenderedImage}
implementations convenience.
  *
- * <p>If this {@code ComputedImage} is writable, then it is subclass responsibility
to manage synchronization between
- * {@link #getTile(int, int) getTile(…)} method (e.g. with a {@linkplain java.util.concurrent.locks.ReadWriteLock#readLock()
read lock}) and
- * {@link WritableRenderedImage#getWritableTile getWritableTile}/{@link WritableRenderedImage#releaseWritableTile
releaseWritableTile(…)}
- * methods (e.g. with a {@linkplain java.util.concurrent.locks.ReadWriteLock#writeLock()
write lock}).
- * Users should invoke the {@code getWritableTile(…)} and {@code releaseWritableTile(…)}
methods in
- * {@code try ... finally} blocks for ensuring proper release of locks.</p>
+ * <p>Apache SIS <a href="https://issues.apache.org/jira/browse/SIS-487">does
not yet define a synchronization policy</a>
+ * between {@link #getTile(int, int) getTile(…)} method and {@link WritableRenderedImage#getWritableTile(int,
int)
+ * WritableRenderedImage​.getWritableTile}/{@link WritableRenderedImage#releaseWritableTile
releaseWritableTile(…)} methods.
+ * For example if a call to {@code getTile(tileX, tileY)} is followed by a call to {@code
getWritableTile(tileX, tileY)}
+ * in another thread, there is no guarantees about whether or not the sample values seen
in the {@link Raster} would be
+ * isolated from the write operations done concurrently in the {@link WritableRaster}.
+ * A future SIS version may define a policy (possibly based on {@link java.util.concurrent.locks.ReadWriteLock}).</p>
+ *
+ * <p>Note that despite above-cited issue, all methods in this {@code ComputedImage}
class are thread-safe.
+ * What is not thread-safe is writing into a {@link WritableRaster} from outside the {@link
#computeTile
+ * computeTile(…)} method, or reading a {@link Raster} after it {@linkplain #markDirtyTiles
became dirty}
+ * if the change to dirty state happened after the call to {@link #getTile(int, int) getTile(…)}.</p>
  *
  * @author  Martin Desruisseaux (Geomatys)
  * @version 1.1
@@ -330,7 +336,8 @@ public abstract class ComputedImage extends PlanarImage {
      * If this image implements the {@link WritableRenderedImage} interface, then a user
may acquire the same
      * tile for a write operation after this method returned. In such case there is no consistency
guarantees
      * on sample values: the tile returned by this method may show data in an unspecified
stage during the
-     * write operation.
+     * write operation. A synchronization policy <a href="https://issues.apache.org/jira/browse/SIS-487">may
+     * be defined in a future Apache SIS version</a>.
      *
      * @param  tileX  the column index of the tile to get.
      * @param  tileY  the row index of the tile to get.
@@ -396,11 +403,11 @@ public abstract class ComputedImage extends PlanarImage {
      * }
      *
      * <h4>Error handling</h4>
-     * If this method throws an exception or return {@code null}, then {@link #getTile(int,
int) getTile(…)}
+     * If this method throws an exception or returns {@code null}, then {@link #getTile(int,
int) getTile(…)}
      * will set an error flag on the tile and throw an {@link ImagingOpException} with the
exception thrown
      * by {@code computeTile(…)} as its cause. Future invocations of {@code getTile(tileX,
tileY)} with the
      * same tile indices will cause an {@link ImagingOpException} to be thrown immediately
without invocation
-     * of {@code compute(tileX, tileY)}. If the cause of the error has been fixed, then users
should invoke
+     * of {@code compute(tileX, tileY)}. If the error has been fixed, then users can invoke
      * {@link #clearErrorFlags(Rectangle)} for allowing the tile to be computed again.
      *
      * @param  tileX     the column index of the tile to compute.
@@ -519,8 +526,8 @@ public abstract class ComputedImage extends PlanarImage {
      * @param  tileY    the Y index of the tile to acquire or release.
      * @param  writing  {@code true} for acquiring the tile, or {@code false} for releasing
it.
      * @return {@code true} if the tile goes from having no writers to having one writer
-     *         (may happen if {@code writing} is {@code true}), or from having one writer
-     *         to no writers (may happen if {@code writing} is {@code false}).
+     *         (may happen if {@code writing} is {@code true}), or goes from having one
+     *         writer to no writers (may happen if {@code writing} is {@code false}).
      *
      * @see WritableRenderedImage#getWritableTile(int, int)
      * @see WritableRenderedImage#releaseWritableTile(int, int)
diff --git a/core/sis-feature/src/main/java/org/apache/sis/image/PlanarImage.java b/core/sis-feature/src/main/java/org/apache/sis/image/PlanarImage.java
index 4c838d9..6b0a741 100644
--- a/core/sis-feature/src/main/java/org/apache/sis/image/PlanarImage.java
+++ b/core/sis-feature/src/main/java/org/apache/sis/image/PlanarImage.java
@@ -75,9 +75,10 @@ import org.apache.sis.internal.coverage.j2d.ColorModelFactory;
  * in terms of above methods.
  *
  * <h2>Writable images</h2>
- * Some subclasses may implement the {@link WritableRenderedImage} interface. If this image
is writable, then the
- * {@link WritableRenderedImage#getWritableTile getWritableTile(…)} and {@link WritableRenderedImage#releaseWritableTile
- * releaseWritableTile(…)} methods <strong>must</strong> be invoked in {@code
try ... finally} block like below:
+ * Some subclasses may implement the {@link WritableRenderedImage} interface. If this image
is writable,
+ * then the {@link WritableRenderedImage#getWritableTile WritableRenderedImage​.getWritableTile(…)}
and
+ * {@link WritableRenderedImage#releaseWritableTile releaseWritableTile(…)} methods should
be invoked in
+ * {@code try ... finally} blocks like below:
  *
  * {@preformat java
  *     WritableRenderedImage image = ...;
@@ -89,8 +90,11 @@ import org.apache.sis.internal.coverage.j2d.ColorModelFactory;
  *     }
  * }
  *
- * The reason is because some implementations may acquire and release synchronization locks
in the
- * {@code getWritableTile(…)} and {@code releaseWritableTile(…)} methods.
+ * This is recommended because implementations may count the number of acquisitions and releases
for deciding
+ * when to notify the {@link java.awt.image.TileObserver}s. Some implementations may also
acquire and release
+ * synchronization locks in the {@code getWritableTile(…)} and {@code releaseWritableTile(…)}
methods.
+ * Apache SIS <a href="https://issues.apache.org/jira/browse/SIS-487">does not yet
define a synchronization policy</a>
+ * for {@link WritableRenderedImage}, but such policy may be defined in a future version.
  *
  * @author  Johann Sorel (Geomatys)
  * @author  Martin Desruisseaux (Geomatys)
diff --git a/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/MultiAuthoritiesFactory.java
b/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/MultiAuthoritiesFactory.java
index 0000450..62a7f78 100644
--- a/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/MultiAuthoritiesFactory.java
+++ b/core/sis-referencing/src/main/java/org/apache/sis/referencing/factory/MultiAuthoritiesFactory.java
@@ -1508,7 +1508,7 @@ public class MultiAuthoritiesFactory extends GeodeticAuthorityFactory
implements
         }
         /*
          * No coordinate operation because of mismatched factories. This is not illegal (the
result is an empty set)
-         * but it is worth to notify the user because this case has some chances to be an
user error.
+         * but it is worth to notify the user because this case has some chances to be a
user error.
          */
         final LogRecord record = Resources.forLocale(null).getLogRecord(Level.WARNING,
                 Resources.Keys.MismatchedOperationFactories_2, sourceCRS, targetCRS);


Mime
View raw message