001: /*
002: * $RCSfile: TileScheduler.java,v $
003: *
004: * Copyright (c) 2005 Sun Microsystems, Inc. All rights reserved.
005: *
006: * Use is subject to license terms.
007: *
008: * $Revision: 1.1 $
009: * $Date: 2005/02/11 04:57:22 $
010: * $State: Exp $
011: */
012: package javax.media.jai;
013:
014: import java.awt.image.Raster;
015: import java.awt.Point;
016:
017: /**
018: * A class implementing a mechanism for scheduling tile calculation.
019: * In various implementations tile computation may make use of multithreading
020: * and multiple simultaneous network connections for improved performance.
021: *
022: * <p> If multithreading is used then the implementation of the interface
023: * must be thread-safe. In particular it must be possible to invoke any of
024: * the tile scheduling methods on the same image simultaneously from different
025: * threads and obtain the same results as if all invocations had been from
026: * the same thread.
027: *
028: * <p> Errors and exceptions which occur within the scheduler and which prevent
029: * tile computation will be thrown via the usual mechanism for all blocking
030: * methods, i.e., those which perform the computations while the invoking
031: * thread blocks. Failure conditions encountered in computations effected
032: * via non-blocking methods will be indicated by notifying any listeners.
033: * In neither case is it expected that the tiles will be re-scheduled for
034: * computation this instead being left to the application.
035: */
036: public interface TileScheduler {
037:
038: /**
039: * Schedules a tile for computation. Called by
040: * <code>OpImage.getTile()</code>, this method makes
041: * <code>OpImage.computeTile()</code> calls to calculate
042: * the destination tile. This will provoke the computation
043: * of any required source tiles as well.
044: *
045: * @param target An <code>OpImage</code> whose tile is to be computed.
046: * @param tileX The X index of the tile to be computed.
047: * @param tileY The Y index of the tile to be computed.
048: * @return A <code>Raster</code> containing the contents of the tile.
049: *
050: * @throws IllegalArgumentException if <code>target</code> is
051: * <code>null</code>.
052: */
053: Raster scheduleTile(OpImage target, int tileX, int tileY);
054:
055: /**
056: * Schedules a list of tiles for computation. Called by
057: * <code>OpImage.getTiles</code>, this method makes
058: * <code>OpImage.computeTile()</code> calls to calculate
059: * the destination tiles. This will provoke the computation
060: * of any required source tiles as well.
061: *
062: * @param target An <code>OpImage</code> whose tiles are to be computed.
063: * @param tileIndices A list of tile indices indicating which tiles
064: * to schedule for computation.
065: * @return An array of <code>Raster</code>s containing a computed
066: * raster for every tile index passed in.
067: *
068: * @throws IllegalArgumentException if <code>target</code> or
069: * <code>tileIndices</code> is <code>null</code>.
070: */
071: Raster[] scheduleTiles(OpImage target, Point tileIndices[]);
072:
073: /**
074: * Schedule a list of tiles for computation. The supplied listeners
075: * will be notified of the status of each tile, i.e., when each tile
076: * is computed, cancelled, or encounters an error. This
077: * method ideally should be non-blocking. If the <code>TileScheduler</code>
078: * implementation uses multithreading, it is at the discretion of the
079: * implementation which thread invokes the
080: * <code>TileComputationListener</code> methods. The event source
081: * parameter passed to each listener will be the <code>TileScheduler</code>
082: * itself and the image parameter will be the specified target image.
083: *
084: * <p> In the Sun Microsystems reference implementation of
085: * <code>TileScheduler</code> the <code>TileComputationListener</code>
086: * methods are invoked by the thread which performs the actual
087: * tile computation. This will be the primary thread if the
088: * parallelism is zero, or a worker thread if it is positive.
089: *
090: * @param target A <code>PlanarImage</code> whose tiles are to be computed.
091: * @param tileIndices A list of tile indices indicating which tiles
092: * to schedule for computation.
093: * @param tileListeners <code>TileComputationListener</code>s to be
094: * informed of tile computation status; may be <code>null</code>.
095: * @return The <code>TileRequest</code> for this set of tiles.
096: * @throws IllegalArgumentException if <code>target</code> or
097: * <code>tileIndices</code> is <code>null</code>.
098: *
099: * @since JAI 1.1
100: */
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: */
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: */
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: */
174: void setParallelism(int parallelism);
175:
176: /**
177: * Returns the degree of parallelism of the scheduler.
178: *
179: * @since JAI 1.1
180: */
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: */
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: */
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: */
215: void setPriority(int priority);
216:
217: /**
218: * Returns the priority of <code>scheduleTiles()</code> processing.
219: *
220: * @since JAI 1.1
221: */
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: */
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: */
243: int getPrefetchPriority();
244: }
|