Class TileOpExecutor.Cursor<RI extends RenderedImage,A>
java.lang.Object
java.lang.Number
java.util.concurrent.atomic.AtomicInteger
org.apache.sis.internal.coverage.j2d.TileOpExecutor.Cursor<RI,A>
- Type Parameters:
RI
-RenderedImage
orWritableRenderedImage
.A
- type of the thread-local object (the accumulator) for holding intermediate results.
- All Implemented Interfaces:
Serializable
- Enclosing class:
- TileOpExecutor
Tile indices of the next tile to process in a multi-threaded computation. When a computation is splitted
between many threads, all workers will share a reference to the same
TileOpExecutor.Cursor
instance for fetching
the indices of the next tile in iteration order no matter if requested by the same or different threads.
We do that on the assumption that if calls to RenderedImage.getTile(int, int)
causes read operations
from a file, iteration order corresponds to consecutive tiles in the file and those tiles are loaded more
efficiently with sequential read operations.
Current implementation uses row major iteration. A future version could use an image property giving the preferred iteration order (possibly as a list or an array of tile indices). When there is no indication about the preferred iteration order, a future version could possible uses Hilbert iterator for processing nearby tiles together (assuming they are more likely to have been computed at a near instant).
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate A
The cumulated result of all threads.private final BinaryOperator<A>
The operation to execute after a thread finished to process all its tiles, for combining its result with the result of another thread.private final ErrorHandler.Report
The errors that occurred while computing a tile.(package private) final RI
The image from which to read tiles or where to write tiles.private final int
The number of tiles in a row of the area of interest.private final boolean
Whether to stop of the first error. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescription(package private) final void
accumulate
(A result) Invoked when a thread finished to process all its tiles for combining its result with the result of previous threads.(package private) final <R> R
finish
(Future<?>[] workers, Collector<?, A, R> collector, TileErrorHandler errorHandler) Invoked after the current thread finished to process all its tiles.(package private) final int
Returns the suggested number of worker threads to create, excluding the current thread.(package private) final boolean
intersectAOI
(TileOpExecutor.Worker<RI, ?, A> indices) Returnstrue
if current tile of given worker intersects the area of interest.(package private) final boolean
next
(TileOpExecutor.Worker<RI, ?, A> indices) Sets the given worker to the indices of the next tile.(package private) final void
recordError
(Point tile, Throwable ex) Stores the given exception in a log record.toString()
Returns a string representation of this cursor for debugging purposes.Methods inherited from class java.util.concurrent.atomic.AtomicInteger
accumulateAndGet, addAndGet, compareAndExchange, compareAndExchangeAcquire, compareAndExchangeRelease, compareAndSet, decrementAndGet, doubleValue, floatValue, get, getAcquire, getAndAccumulate, getAndAdd, getAndDecrement, getAndIncrement, getAndSet, getAndUpdate, getOpaque, getPlain, incrementAndGet, intValue, lazySet, longValue, set, setOpaque, setPlain, setRelease, updateAndGet, weakCompareAndSet, weakCompareAndSetAcquire, weakCompareAndSetPlain, weakCompareAndSetRelease, weakCompareAndSetVolatile
Methods inherited from class java.lang.Number
byteValue, shortValue
-
Field Details
-
image
The image from which to read tiles or where to write tiles. In the latter case, must be an instance ofWritableRenderedImage
. -
numXTiles
private final int numXTilesThe number of tiles in a row of the area of interest.- See Also:
-
combiner
The operation to execute after a thread finished to process all its tiles, for combining its result with the result of another thread.- See Also:
-
accumulator
The cumulated result of all threads. Every time a thread finishes its work, it callsaccumulate(Object)
for combining its result with previous value that may exist in this field.- See Also:
-
errors
The errors that occurred while computing a tile. If this report is empty, then it will be ignored. Otherwise it contains a log record with level, message and exception properties set. But the source class name, source method name and logger name will be undefined.If the report is non-empty, it will be given to the error handler after all computation finished.
- See Also:
-
stopOnError
private final boolean stopOnErrorWhether to stop of the first error. Iftrue
the error will be reported as soon as possible. Iffalse
, processing of all tiles will be completed before the error is reported.- See Also:
-
-
Constructor Details
-
Cursor
Creates a new cursor initialized to the indices of the first tile.- Parameters:
image
- the image to read or the image where to write.collector
- provides the combiner of thread-local objects of type A.stopOnError
- whether to stop of the first error or to process all tiles before to report the error.
-
-
Method Details
-
getNumWorkers
final int getNumWorkers()Returns the suggested number of worker threads to create, excluding the current thread. This method always returns a value at least one 1 less than the number of tiles because the current thread will be itself a worker. -
next
Sets the given worker to the indices of the next tile. This method is invoked by all worker thread before each new tile to process. We return tiles in iteration order, regardless which thread is requesting for next tile, for the reasons documented inTileOpExecutor.Cursor
javadoc.- Parameters:
indices
- the worker where to updateTileOpExecutor.Worker.tx
andTileOpExecutor.Worker.ty
indices.- Returns:
true
if the tile at the updated indices should be processed, orfalse
if there are no more tiles to process.
-
intersectAOI
Returnstrue
if current tile of given worker intersects the area of interest. This is a finer check than the AOI specified atTileOpExecutor
construction time, because the AOI tested here can be an irregular shape.- Parameters:
indices
- the worker to test.- Returns:
- whether current worker tile intersect the area of interest.
- See Also:
-
accumulate
Invoked when a thread finished to process all its tiles for combining its result with the result of previous threads. This method does nothing if the given result is null.- Parameters:
result
- the result computed in current thread (may benull
).
-
finish
Invoked after the current thread finished to process all its tiles. If some other threads are still computing their tiles, this method waits for those threads to complete (each thread has at most one tile to complete). After all threads completed, this method computes the final result and reports the errors if any.- Type Parameters:
R
- the final type of the result. This is often the same type than A.- Parameters:
workers
- handlers of all worker threads other than the current threads. Content of this array may be modified by this method.collector
- provides the finisher to use for computing final result of type R.errorHandler
- where to report exceptions, orTileErrorHandler.THROW
for throwing them.- Returns:
- the final result computed by finisher (may be
null
). - Throws:
ImagingOpException
- if an exception occurred duringTileOpExecutor.Worker.executeOnCurrentTile()
and theerrorHandler
isTHROW
.RuntimeException
- if an exception occurred elsewhere (for example in the combiner or finisher).
-
recordError
Stores the given exception in a log record. We use a log record in order to initialize the timestamp and thread ID to the values they had at the time the first error occurred. The error is not notified immediately to theErrorHandler
; we wait for other errors in order to aggregate them in a single record. So the given error is recorded but not yet reported.- Parameters:
tile
- indices of the tile where an error occurred, ornull
if unknown.ex
- the exception that occurred.- See Also:
-
toString
Returns a string representation of this cursor for debugging purposes.- Overrides:
toString
in classAtomicInteger
-