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 or WritableRenderedImage.
A - type of the thread-local object (the accumulator) for holding intermediate results.
All Implemented Interfaces:
Serializable
Enclosing class:
TileOpExecutor

private final class TileOpExecutor.Cursor<RI extends RenderedImage,A> extends AtomicInteger
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 Details

  • Constructor Details

    • Cursor

      Cursor(RI image, Collector<?,A,?> collector, boolean stopOnError)
      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

      final boolean next(TileOpExecutor.Worker<RI,?,A> indices)
      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 in TileOpExecutor.Cursor javadoc.
      Parameters:
      indices - the worker where to update TileOpExecutor.Worker.tx and TileOpExecutor.Worker.ty indices.
      Returns:
      true if the tile at the updated indices should be processed, or false if there are no more tiles to process.
    • intersectAOI

      final boolean intersectAOI(TileOpExecutor.Worker<RI,?,A> indices)
      Returns true if current tile of given worker intersects the area of interest. This is a finer check than the AOI specified at TileOpExecutor 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

      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. This method does nothing if the given result is null.
      Parameters:
      result - the result computed in current thread (may be null).
    • finish

      final <R> R finish(Future<?>[] workers, Collector<?,A,R> collector, TileErrorHandler errorHandler)
      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, or TileErrorHandler.THROW for throwing them.
      Returns:
      the final result computed by finisher (may be null).
      Throws:
      ImagingOpException - if an exception occurred during TileOpExecutor.Worker.executeOnCurrentTile() and the errorHandler is THROW.
      RuntimeException - if an exception occurred elsewhere (for example in the combiner or finisher).
    • recordError

      final void recordError(Point tile, Throwable ex)
      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 the ErrorHandler; 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, or null if unknown.
      ex - the exception that occurred.
      See Also:
    • toString

      public String toString()
      Returns a string representation of this cursor for debugging purposes.
      Overrides:
      toString in class AtomicInteger