javax.media.jai
Interface TileScheduler

public interface TileScheduler

A class implementing a mechanism for scheduling tile calculation. In various implementations tile computation may make use of multithreading and multiple simultaneous network connections for improved performance.

If multithreading is used then the implementation of the interface must be thread-safe. In particular it must be possible to invoke any of the tile scheduling methods on the same image simultaneously from different threads and obtain the same results as if all invocations had been from the same thread.

Errors and exceptions which occur within the scheduler and which prevent tile computation will be thrown via the usual mechanism for all blocking methods, i.e., those which perform the computations while the invoking thread blocks. Failure conditions encountered in computations effected via non-blocking methods will be indicated by notifying any listeners. In neither case is it expected that the tiles will be re-scheduled for computation this instead being left to the application.

Method Summary

void	cancelTiles(TileRequest request, Point[] tileIndices) Issues an advisory cancellation request to the TileScheduler stating that the indicated tiles of the specified request should not be processed.
int	getParallelism() Returns the degree of parallelism of the scheduler.
int	getPrefetchParallelism() Identical to getParallelism() but applies only to prefetchTiles().
int	getPrefetchPriority() Identical to getPriority() but applies only to prefetchTiles().
int	getPriority() Returns the priority of scheduleTiles() processing.
void	prefetchTiles(PlanarImage target, Point[] tileIndices) Hints to the TileScheduler that the specified tiles from the given PlanarImage might be needed in the near future.
Raster	scheduleTile(OpImage target, int tileX, int tileY) Schedules a tile for computation.
Raster[]	scheduleTiles(OpImage target, Point[] tileIndices) Schedules a list of tiles for computation.
TileRequest	scheduleTiles(PlanarImage target, Point[] tileIndices, TileComputationListener[] tileListeners) Schedule a list of tiles for computation.
void	setParallelism(int parallelism) Suggests to the scheduler the degree of parallelism to use in processing invocations of scheduleTiles().
void	setPrefetchParallelism(int parallelism) Identical to setParallelism() but applies only to prefetchTiles().
void	setPrefetchPriority(int priority) Identical to setPriority() but applies only to prefetchTiles().
void	setPriority(int priority) Suggests to the scheduler the priority to assign to processing effected by scheduleTiles().

Method Detail

scheduleTile

public Raster scheduleTile(OpImage target,
                           int tileX,
                           int tileY)

Schedules a tile for computation. Called by OpImage.getTile(), this method makes OpImage.computeTile() calls to calculate the destination tile. This will provoke the computation of any required source tiles as well.

Parameters:

target - An OpImage whose tile is to be computed.

tileX - The X index of the tile to be computed.

tileY - The Y index of the tile to be computed.

Returns:

A Raster containing the contents of the tile.

Throws:

IllegalArgumentException - if target is null.

scheduleTiles

public Raster[] scheduleTiles(OpImage target,
                              Point[] tileIndices)

Schedules a list of tiles for computation. Called by OpImage.getTiles, this method makes OpImage.computeTile() calls to calculate the destination tiles. This will provoke the computation of any required source tiles as well.

Parameters:

target - An OpImage whose tiles are to be computed.

tileIndices - A list of tile indices indicating which tiles to schedule for computation.

Returns:

An array of Rasters containing a computed raster for every tile index passed in.

Throws:

IllegalArgumentException - if target or tileIndices is null.

scheduleTiles

public TileRequest scheduleTiles(PlanarImage target,
                                 Point[] tileIndices,
                                 TileComputationListener[] tileListeners)

Schedule a list of tiles for computation. The supplied listeners will be notified of the status of each tile, i.e., when each tile is computed, cancelled, or encounters an error. This method ideally should be non-blocking. If the TileScheduler implementation uses multithreading, it is at the discretion of the implementation which thread invokes the TileComputationListener methods. The event source parameter passed to each listener will be the TileScheduler itself and the image parameter will be the specified target image.

In the Sun Microsystems reference implementation of TileScheduler the TileComputationListener methods are invoked by the thread which performs the actual tile computation. This will be the primary thread if the parallelism is zero, or a worker thread if it is positive.

Parameters:

target - A PlanarImage whose tiles are to be computed.

tileIndices - A list of tile indices indicating which tiles to schedule for computation.

tileListeners - TileComputationListeners to be informed of tile computation status; may be null.

Returns:

The TileRequest for this set of tiles.

Throws:

IllegalArgumentException - if target or tileIndices is null.

Since:

JAI 1.1

cancelTiles

public void cancelTiles(TileRequest request,
                        Point[] tileIndices)

Issues an advisory cancellation request to the TileScheduler stating that the indicated tiles of the specified request should not be processed. The handling of cancellation is at the discretion of the scheduler which may cancel tile processing in progress and remove tiles from its internal queue, remove tiles from the queue but not terminate current processing, or simply do nothing.

In the Sun Microsystems reference implementation of TileScheduler the second tile cancellation option is implemented, i.e., tiles are removed from the internal queue but computation already in progress is not terminated. If there is at least one worker thread this method should be non-blocking. Any tiles allowed to complete computation subsequent to this call are complete and will be treated as if they had not been cancelled, e.g., with respect to caching, notification of registered listeners, etc. Furthermore, cancelling a tile request in no way invalidates the tile as a candidate for future recomputation.

Parameters:

request - The request for which tiles are to be cancelled.

tileIndices - The tiles to be cancelled; may be null. Any tiles not actually in the TileRequest will be ignored.

Throws:

IllegalArgumentException - if request is null.

Since:

JAI 1.1

prefetchTiles

public void prefetchTiles(PlanarImage target,
                          Point[] tileIndices)

Hints to the TileScheduler that the specified tiles from the given PlanarImage might be needed in the near future. Some TileScheduler implementations may spawn a low priority thread to compute the tiles while others may ignore the hint.

Parameters:

target - The OpImage from which to prefetch tiles.

tileIndices - A list of tile indices indicating which tiles to prefetch.

Throws:

IllegalArgumentException - if target or tileIndices is null.

setParallelism

public void setParallelism(int parallelism)

Suggests to the scheduler the degree of parallelism to use in processing invocations of scheduleTiles(). For example, this might set the number of threads to spawn. It is legal to implement this method as a no-op.

In the Sun Microsystems reference implementation of TileScheduler this method sets the number of worker threads actually used for tile computation. Ideally this number should equal the number of processors actually available on the system. It is the responsibility of the application to set this value as the number of processors is not available via the virtual machine. A parallelism value of zero indicates that all tile computation will be effected in the primary thread. A parallelism value of N indicates that there will be N worker threads in addition to the primary scheduler thread. In JAI the parallelism defaults to a value of 2 unless explicity set by the application.

Parameters:

parallelism - The suggested degree of parallelism.

Throws:

IllegalArgumentException - if parallelism is negative.

Since:

JAI 1.1

getParallelism

public int getParallelism()

Returns the degree of parallelism of the scheduler.

Since:

JAI 1.1

setPrefetchParallelism

public void setPrefetchParallelism(int parallelism)

Identical to setParallelism() but applies only to prefetchTiles().

Since:

JAI 1.1

getPrefetchParallelism

public int getPrefetchParallelism()

Identical to getParallelism() but applies only to prefetchTiles().

Since:

JAI 1.1

setPriority

public void setPriority(int priority)

Suggests to the scheduler the priority to assign to processing effected by scheduleTiles(). For example, this might set thread priority. Values outside of the accepted priority range will be clamped to the nearest extremum. An implementation may clamp the prefetch priority to less than the scheduling priority. It is legal to implement this method as a no-op.

In the Sun Microsystems reference implementation of TileScheduler this method sets the priority of the worker threads used for tile computation. Its initial value is Thread.NORM_PRIORITY.

Parameters:

priority - The suggested priority.

Since:

JAI 1.1

getPriority

public int getPriority()

Returns the priority of scheduleTiles() processing.

Since:

JAI 1.1

setPrefetchPriority

public void setPrefetchPriority(int priority)

Identical to setPriority() but applies only to prefetchTiles().

In the Sun Microsystems reference implementation of TileScheduler, this method sets the priority of any threads spawned to prefetch tiles. Its initial value is Thread.MIN_PRIORITY.

Since:

JAI 1.1

getPrefetchPriority

public int getPrefetchPriority()

Identical to getPriority() but applies only to prefetchTiles().

Since:

JAI 1.1