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 <[email protected]>
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);
