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