1 /* 2 * $RCSfile: TileScheduler.java,v $ 3 * 4 * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved. 5 * 6 * Use is subject to license terms. 7 * 8 * $Revision: 1.1 $ 9 * $Date: 2005/02/11 04:57:22 $ 10 * $State: Exp $ 11 */ 12 package com.lightcrafts.mediax.jai; 13 import java.awt.image.Raster; 14 import java.awt.Point; 15 16 17 /** 18 * A class implementing a mechanism for scheduling tile calculation. 19 * In various implementations tile computation may make use of multithreading 20 * and multiple simultaneous network connections for improved performance. 21 * 22 * <p> If multithreading is used then the implementation of the interface 23 * must be thread-safe. In particular it must be possible to invoke any of 24 * the tile scheduling methods on the same image simultaneously from different 25 * threads and obtain the same results as if all invocations had been from 26 * the same thread. 27 * 28 * <p> Errors and exceptions which occur within the scheduler and which prevent 29 * tile computation will be thrown via the usual mechanism for all blocking 30 * methods, i.e., those which perform the computations while the invoking 31 * thread blocks. Failure conditions encountered in computations effected 32 * via non-blocking methods will be indicated by notifying any listeners. 33 * In neither case is it expected that the tiles will be re-scheduled for 34 * computation this instead being left to the application. 35 */ 36 public interface TileScheduler { 37 38 /** 39 * Schedules a tile for computation. Called by 40 * <code>OpImage.getTile()</code>, this method makes 41 * <code>OpImage.computeTile()</code> calls to calculate 42 * the destination tile. This will provoke the computation 43 * of any required source tiles as well. 44 * 45 * @param target An <code>OpImage</code> whose tile is to be computed. 46 * @param tileX The X index of the tile to be computed. 47 * @param tileY The Y index of the tile to be computed. 48 * @return A <code>Raster</code> containing the contents of the tile. 49 * 50 * @throws IllegalArgumentException if <code>target</code> is 51 * <code>null</code>. 52 */ scheduleTile(OpImage target, int tileX, int tileY)53 Raster scheduleTile(OpImage target, int tileX, int tileY); 54 55 /** 56 * Schedules a list of tiles for computation. Called by 57 * <code>OpImage.getTiles</code>, this method makes 58 * <code>OpImage.computeTile()</code> calls to calculate 59 * the destination tiles. This will provoke the computation 60 * of any required source tiles as well. 61 * 62 * @param target An <code>OpImage</code> whose tiles are to be computed. 63 * @param tileIndices A list of tile indices indicating which tiles 64 * to schedule for computation. 65 * @return An array of <code>Raster</code>s containing a computed 66 * raster for every tile index passed in. 67 * 68 * @throws IllegalArgumentException if <code>target</code> or 69 * <code>tileIndices</code> is <code>null</code>. 70 */ scheduleTiles(OpImage target, Point tileIndices[])71 Raster[] scheduleTiles(OpImage target, Point tileIndices[]); 72 73 /** 74 * Schedule a list of tiles for computation. The supplied listeners 75 * will be notified of the status of each tile, i.e., when each tile 76 * is computed, cancelled, or encounters an error. This 77 * method ideally should be non-blocking. If the <code>TileScheduler</code> 78 * implementation uses multithreading, it is at the discretion of the 79 * implementation which thread invokes the 80 * <code>TileComputationListener</code> methods. The event source 81 * parameter passed to each listener will be the <code>TileScheduler</code> 82 * itself and the image parameter will be the specified target image. 83 * 84 * <p> In the Sun Microsystems reference implementation of 85 * <code>TileScheduler</code> the <code>TileComputationListener</code> 86 * methods are invoked by the thread which performs the actual 87 * tile computation. This will be the primary thread if the 88 * parallelism is zero, or a worker thread if it is positive. 89 * 90 * @param target A <code>PlanarImage</code> whose tiles are to be computed. 91 * @param tileIndices A list of tile indices indicating which tiles 92 * to schedule for computation. 93 * @param tileListeners <code>TileComputationListener</code>s to be 94 * informed of tile computation status; may be <code>null</code>. 95 * @return The <code>TileRequest</code> for this set of tiles. 96 * @throws IllegalArgumentException if <code>target</code> or 97 * <code>tileIndices</code> is <code>null</code>. 98 * 99 * @since JAI 1.1 100 */ scheduleTiles(PlanarImage target, Point[] tileIndices, TileComputationListener[] tileListeners)101 TileRequest scheduleTiles(PlanarImage target, Point[] tileIndices, 102 TileComputationListener[] tileListeners); 103 104 /** 105 * Issues an advisory cancellation request to the 106 * <code>TileScheduler</code> stating that the indicated tiles of the 107 * specified request should not be processed. The handling of cancellation 108 * is at the discretion of the scheduler which may cancel tile processing 109 * in progress and remove tiles from its internal queue, remove tiles from 110 * the queue but not terminate current processing, or simply do nothing. 111 * 112 * <p> In the Sun Microsystems reference implementation of 113 * <code>TileScheduler</code> the second tile cancellation option is 114 * implemented, i.e., tiles are removed from the internal queue but 115 * computation already in progress is not terminated. If there is at 116 * least one worker thread this method should be non-blocking. Any tiles 117 * allowed to complete computation subsequent to this call are complete 118 * and will be treated as if they had not been cancelled, e.g., with 119 * respect to caching, notification of registered listeners, etc. 120 * Furthermore, cancelling a tile request in no way invalidates the tile 121 * as a candidate for future recomputation. 122 * 123 * @param request The request for which tiles are to be cancelled. 124 * @param tileIndices The tiles to be cancelled; may be <code>null</code>. 125 * Any tiles not actually in the <code>TileRequest</code> will be 126 * ignored. 127 * 128 * @throws IllegalArgumentException if <code>request</code> is 129 * <code>null</code>. 130 * 131 * @since JAI 1.1 132 */ cancelTiles(TileRequest request, Point[] tileIndices)133 void cancelTiles(TileRequest request, Point[] tileIndices); 134 135 /** 136 * Hints to the <code>TileScheduler</code> that the specified tiles from 137 * the given <code>PlanarImage</code> might be needed in the near future. 138 * Some <code>TileScheduler</code> implementations may spawn a low 139 * priority thread to compute the tiles while others may ignore the hint. 140 * 141 * @param target The <code>OpImage</code> from which to prefetch tiles. 142 * @param tileIndices A list of tile indices indicating which tiles 143 * to prefetch. 144 * 145 * @throws IllegalArgumentException if <code>target</code> or 146 * <code>tileIndices</code> is <code>null</code>. 147 */ prefetchTiles(PlanarImage target, Point[] tileIndices)148 void prefetchTiles(PlanarImage target, Point[] tileIndices); 149 150 /** 151 * Suggests to the scheduler the degree of parallelism to use in 152 * processing invocations of <code>scheduleTiles()</code>. For 153 * example, this might set the number of threads to spawn. It is 154 * legal to implement this method as a no-op. 155 * 156 * <p> In the Sun Microsystems reference implementation of TileScheduler 157 * this method sets the number of worker threads actually used for tile 158 * computation. Ideally this number should equal the number of processors 159 * actually available on the system. It is the responsibility of the 160 * application to set this value as the number of processors is not 161 * available via the virtual machine. A parallelism value of zero 162 * indicates that all tile computation will be effected in the primary 163 * thread. A parallelism value of <i>N</i> indicates that there will be 164 * <i>N</i> worker threads in addition to the primary scheduler thread. 165 * In JAI the parallelism defaults to a value of 2 unless explicity set 166 * by the application. 167 * 168 * @param parallelism The suggested degree of parallelism. 169 * @throws IllegalArgumentException if <code>parallelism</code> 170 * is negative. 171 * 172 * @since JAI 1.1 173 */ setParallelism(int parallelism)174 void setParallelism(int parallelism); 175 176 /** 177 * Returns the degree of parallelism of the scheduler. 178 * 179 * @since JAI 1.1 180 */ getParallelism()181 int getParallelism(); 182 183 /** 184 * Identical to <code>setParallelism()</code> but applies only to 185 * <code>prefetchTiles()</code>. 186 * 187 * @since JAI 1.1 188 */ setPrefetchParallelism(int parallelism)189 void setPrefetchParallelism(int parallelism); 190 191 /** 192 * Identical to <code>getParallelism()</code> but applies only to 193 * <code>prefetchTiles()</code>. 194 * 195 * @since JAI 1.1 196 */ getPrefetchParallelism()197 int getPrefetchParallelism(); 198 199 /** 200 * Suggests to the scheduler the priority to assign to processing 201 * effected by <code>scheduleTiles()</code>. For example, this might 202 * set thread priority. Values outside of the accepted priority range 203 * will be clamped to the nearest extremum. An implementation may clamp 204 * the prefetch priority to less than the scheduling priority. It is 205 * legal to implement this method as a no-op. 206 * 207 * <p> In the Sun Microsystems reference implementation of TileScheduler 208 * this method sets the priority of the worker threads used for tile 209 * computation. Its initial value is <code>Thread.NORM_PRIORITY</code>. 210 * 211 * @param priority The suggested priority. 212 * 213 * @since JAI 1.1 214 */ setPriority(int priority)215 void setPriority(int priority); 216 217 /** 218 * Returns the priority of <code>scheduleTiles()</code> processing. 219 * 220 * @since JAI 1.1 221 */ getPriority()222 int getPriority(); 223 224 /** 225 * Identical to <code>setPriority()</code> but applies only to 226 * <code>prefetchTiles()</code>. 227 * 228 * <p> In the Sun Microsystems reference implementation of 229 * <code>TileScheduler</code>, this method sets the priority of any threads 230 * spawned to prefetch tiles. Its initial value is 231 * <code>Thread.MIN_PRIORITY</code>. 232 * 233 * @since JAI 1.1 234 */ setPrefetchPriority(int priority)235 void setPrefetchPriority(int priority); 236 237 /** 238 * Identical to <code>getPriority()</code> but applies only to 239 * <code>prefetchTiles()</code>. 240 * 241 * @since JAI 1.1 242 */ getPrefetchPriority()243 int getPrefetchPriority(); 244 } 245 246