IJobManager


1   /*******************************************************************************
2    * Copyright (c) 2003, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.core.runtime.jobs;
12  
13  import org.eclipse.core.runtime.IProgressMonitor;
14  import org.eclipse.core.runtime.OperationCanceledException;
15  
16  /**
17   * The job manager provides facilities for scheduling, querying, and maintaining jobs
18   * and locks.  In particular, the job manager provides the following services:
19   * <ul>
20   * <li>Maintains a queue of jobs that are waiting to be run.  Items can be added to
21   * the queue using the <code>schedule</code> method.</li>
22   * <li>Allows manipulation of groups of jobs called job families.  Job families can
23   * be canceled, put to sleep, or woken up atomically.  There is also a mechanism
24   * for querying the set of known jobs in a given family.</li>
25   * <li>Allows listeners to find out about progress on running jobs, and to find out
26   * when jobs have changed states.</li>
27   * <li>Provides a factory for creating lock objects.  Lock objects are smart monitors
28   * that have strategies for avoiding deadlock.</li>
29   * <li>Provide feedback to a client that is waiting for a given job or family of jobs
30   * to complete.</li>
31   * </ul>
32   * <p>
33   * This interface is not intended to be implemented by clients.
34   * </p>
35   * 
36   * @see Job
37   * @see ILock
38   * @since 3.0
39   */
40  public interface IJobManager {
41      /**
42       * A system property key indicating whether the job manager should create
43       * job threads as daemon threads.  Set to <code>true</code> to force all worker 
44       * threads to be created as daemon threads. Set to <code>false</code> to force 
45       * all worker threads to be created as non-daemon threads.
46       * @since 3.3
47       */
48      public static final String   PROP_USE_DAEMON_THREADS = "eclipse.jobs.daemon"; //$NON-NLS-1$
49  
50      /**
51       * Registers a job listener with the job manager.  
52       * Has no effect if an identical listener is already registered.
53       * 
54       * @param listener the listener to be added
55       * @see #removeJobChangeListener(IJobChangeListener)
56       * @see IJobChangeListener
57       */
58      public void addJobChangeListener(IJobChangeListener listener);
59  
60      /**
61       * Begins applying this rule in the calling thread.  If the rule conflicts with another
62       * rule currently running in another thread, this method blocks until there are
63       * no conflicting rules.  Calls to <tt>beginRule</tt> must eventually be followed
64       * by a matching call to <tt>endRule</tt> in the same thread and with the identical
65       * rule instance. 
66       * <p>
67       * Rules can be nested only if the rule for the inner <tt>beginRule</tt>
68       * is contained within the rule for the outer <tt>beginRule</tt>.  Rule containment
69       * is tested with the API method <tt>ISchedulingRule.contains</tt>.  Also, begin/end
70       * pairs must be strictly nested.  Only the rule that has most recently begun
71       * can be ended at any given time.
72       * <p>
73       * A rule of <code>null</code> can be used, but will be ignored for scheduling 
74       * purposes.  The outermost non-null rule in the thread will be used for scheduling. A
75       * <code>null</code> rule that is begun must still be ended.
76       * <p>
77       * If this method is called from within a job that has a scheduling rule, the
78       * given rule must also be contained within the rule for the running job.
79       * <p>
80       * Note that <tt>endRule</tt> must be called even if <tt>beginRule</tt> fails.
81       * The recommended usage is:
82       * <pre>
83       * final ISchedulingRule rule = ...;
84       * try {
85       *  manager.beginRule(rule, monitor);
86       * } finally {
87       *  manager.endRule(rule);
88       * }
89       * </pre>
90       * 
91       * @param rule the rule to begin applying in this thread, or <code>null</code>
92       * @param monitor a progress monitor, or <code>null</code> if progress
93       *    reporting and cancellation are not desired
94       * @throws IllegalArgumentException if the rule is not strictly nested within
95       *  all other rules currently active for this thread
96       * @throws OperationCanceledException if the supplied monitor reports cancelation
97       *  before the rule becomes available
98       * @see ISchedulingRule#contains(ISchedulingRule)
99       */
100     public void beginRule(ISchedulingRule rule, IProgressMonitor monitor);
101 
102     /**
103      * Cancels all jobs in the given job family.  Jobs in the family that are currently waiting
104      * will be removed from the queue.  Sleeping jobs will be discarded without having 
105      * a chance to wake up.  Currently executing jobs will be asked to cancel but there 
106      * is no guarantee that they will do so.
107      * 
108      * @param family the job family to cancel, or <code>null</code> to cancel all jobs
109      * @see Job#belongsTo(Object)
110      */
111     public void cancel(Object   family);
112 
113     /**
114      * Returns a progress monitor that can be used to provide
115      * aggregated progress feedback on a set of running jobs. A user
116      * interface will typically group all jobs in a progress group together,
117      * providing progress feedback for individual jobs as well as aggregated
118      * progress for the entire group.  Jobs in the group may be run sequentially,
119      * in parallel, or some combination of the two.
120      * <p>
121      * Recommended usage (this snippet runs two jobs in sequence in a 
122      * single progress group):
123      * <pre>
124      *    Job parseJob, compileJob;
125      *    IProgressMonitor pm = Platform.getJobManager().createProgressGroup();
126      *    try {
127      *       pm.beginTask("Building", 10);
128      *       parseJob.setProgressGroup(pm, 5);
129      *       parseJob.schedule();
130      *       compileJob.setProgressGroup(pm, 5);
131      *       compileJob.schedule();
132      *       parseJob.join();
133      *       compileJob.join();
134      *    } finally {
135      *       pm.done();
136      *    }
137      * </pre>
138      * 
139      * @see Job#setProgressGroup(IProgressMonitor, int)
140      * @see IProgressMonitor
141      * @return a progress monitor
142      */
143     public IProgressMonitor createProgressGroup();
144 
145     /**
146      * Returns the job that is currently running in this thread, or <code>null</code> if there
147      * is no currently running job.
148      * 
149      * @return the job or <code>null</code>
150      */
151     public Job currentJob();
152 
153     /**
154      * Ends the application of a rule to the calling thread.  Calls to <tt>endRule</tt> 
155      * must be preceded by a matching call to <tt>beginRule</tt> in the same thread
156      * with an identical rule instance.
157      * <p>
158      * Rules can be nested only if the rule for the inner <tt>beginRule</tt>
159      * is contained within the rule for the outer <tt>beginRule</tt>.  Also, begin/end
160      * pairs must be strictly nested.  Only the rule that has most recently begun
161      * can be ended at any given time.
162      * 
163      * @param rule the rule to end applying in this thread
164      * @throws IllegalArgumentException if this method is called on a rule for which
165      * there is no matching begin, or that does not match the most recent begin.
166      * @see ISchedulingRule#contains(ISchedulingRule)
167      */
168     public void endRule(ISchedulingRule rule);
169 
170     /**
171      * Returns all waiting, executing and sleeping jobs belonging
172      * to the given family. If no jobs are found, an empty array is returned.
173      * 
174      * @param family the job family to find, or <code>null</code> to find all jobs
175      * @return the job array
176      * @see Job#belongsTo(Object)
177      */
178     public Job[] find(Object   family);
179 
180     /**
181      * Returns whether the job manager is currently idle.  The job manager is
182      * idle if no jobs are currently running or waiting to run.
183      * 
184      * @return <code>true</code> if the job manager is idle, and 
185      * <code>false</code> otherwise
186      * @since 3.1
187      */
188     public boolean isIdle();
189 
190     /**
191      * Waits until all jobs of the given family are finished.  This method will block the 
192      * calling thread until all such jobs have finished executing, or until this thread is
193      * interrupted.   If there are no jobs in 
194      * the family that are currently waiting, running, or sleeping, this method returns 
195      * immediately.  Feedback on how the join is progressing is provided to a  progress 
196      * monitor.
197      * <p>
198      * If this method is called while the job manager is suspended, only jobs
199      * that are currently running will be joined; Once there are no jobs
200      * in the family in the {@link Job#RUNNING} state, this method returns.
201      * </p>
202      * <p>
203      * Note that there is a deadlock risk when using join.  If the calling thread owns
204      * a lock or object monitor that the joined thread is waiting for, deadlock 
205      * will occur. This method can also result in starvation of the current thread if
206      * another thread continues to add jobs of the given family, or if a
207      * job in the given family reschedules itself in an infinite loop.
208      * </p>
209      * 
210      * @param family the job family to join, or <code>null</code> to join all jobs.
211      * @param monitor Progress monitor for reporting progress on how the
212      * wait is progressing, or <code>null</code> if no progress monitoring is required.
213      * @exception InterruptedException if this thread is interrupted while waiting
214      * @exception OperationCanceledException if the progress monitor is canceled while waiting
215      * @see Job#belongsTo(Object)
216      * @see #suspend()
217      */
218     public void join(Object   family, IProgressMonitor monitor) throws InterruptedException  , OperationCanceledException;
219 
220     /**
221      * Creates a new lock object.  All lock objects supplied by the job manager
222      * know about each other and will always avoid circular deadlock amongst
223      * themselves.
224      * 
225      * @return the new lock object
226      */
227     public ILock newLock();
228 
229     /**
230      * Removes a job listener from the job manager.  
231      * Has no effect if an identical listener is not already registered.
232      * 
233      * @param listener the listener to be removed
234      * @see #addJobChangeListener(IJobChangeListener)
235      * @see IJobChangeListener
236      */
237     public void removeJobChangeListener(IJobChangeListener listener);
238 
239     /**
240      * Resumes execution of jobs after a previous <code>suspend</code>.  All
241      * jobs that were sleeping or waiting prior to the suspension, or that were
242      * scheduled while the job manager was suspended, will now be eligible
243      * for execution.
244      * <p>
245      * Calling this method on a rule that is not suspended  has no effect.  If another 
246      * thread also owns the rule at the time this method is called, then the rule will 
247      * not be resumed until all threads have released the rule.
248      * 
249      * @deprecated This method is not safe and should not be used.
250      * Suspending a scheduling rule violates the thread safety
251      * of clients that use scheduling rules as a mutual exclusion mechanism,
252      * and can result in concurrency problems in all clients that use the suspended rule.
253      * @see #suspend(ISchedulingRule, IProgressMonitor)
254      */
255     public void resume(ISchedulingRule rule);
256 
257     /**
258      * Resumes execution of jobs after a previous <code>suspend</code>.  All
259      * jobs that were sleeping or waiting prior to the suspension, or that were
260      * scheduled while the job manager was suspended, will now be eligible
261      * for execution.
262      * <p>
263      * Calling <code>resume</code> when the job manager is not suspended
264      * has no effect.
265      * 
266      * @see #suspend()
267      */
268     public void resume();
269 
270     /**
271      * Provides a hook that is notified whenever a thread is about to wait on a lock,
272      * or when a thread is about to release a lock.  This hook must only be set once.
273      * <p>
274      * This method is for internal use by the platform-related plug-ins.  
275      * Clients should not call this method.
276      * </p>
277      * @see LockListener
278      */
279     public void setLockListener(LockListener listener);
280 
281     /**
282      * Registers a progress provider with the job manager.  If there was a
283      * provider already registered, it is replaced.
284      * <p>
285      * This method is intended for use by the currently executing Eclipse application.
286      * Plug-ins outside the currently running application should not call this method.
287      * </p>
288      * 
289      * @param provider the new provider, or <code>null</code> if no progress
290      * is needed
291      */
292     public void setProgressProvider(ProgressProvider provider);
293 
294     /**
295      * Suspends execution of all jobs.  Jobs that are already running
296      * when this method is invoked will complete as usual, but all sleeping and
297      * waiting jobs will not be executed until the job manager is resumed.
298      * <p>
299      * The job manager will remain suspended until a subsequent call to
300      * <code>resume</code>.  Further calls to <code>suspend</code>
301      * when the job manager is already suspended are ignored.
302      * <p>
303      * All attempts to join sleeping and waiting jobs while the job manager is
304      * suspended will return immediately.
305      * <p>
306      * Note that this very powerful function should be used with extreme caution.
307      * Suspending the job manager will prevent all jobs in the system from executing,
308      * which may have adverse affects on components that are relying on
309      * execution of jobs. The job manager should never be suspended without intent
310      * to resume execution soon afterwards.
311      * 
312      * @see #resume()
313      * @see #join(Object, IProgressMonitor)
314      */
315     public void suspend();
316 
317     /**
318      * Defers execution of all jobs with scheduling rules that conflict with the
319      * given rule. The caller will be blocked until all currently executing jobs with
320      * conflicting rules are completed.  Conflicting jobs that are sleeping or waiting at
321      * the time this method is called will not be executed until the rule is resumed.
322      * <p>
323      * While a rule is suspended, all calls to <code>beginRule</code> and 
324      * <code>endRule</code> on a suspended rule will not block the caller.
325      * The rule remains suspended until a subsequent call to
326      * <code>resume(ISchedulingRule)</code> with the identical rule instance.  
327      * Further calls to <code>suspend</code> with an identical rule prior to calling
328      * <code>resume</code> are ignored.
329      * </p>
330      * <p>
331      * This method is long-running; progress and cancelation are provided by
332      * the given progress monitor. In the case of cancelation, the rule will
333      * not be suspended.
334      * </p>
335      * Note: this very powerful function should be used with extreme caution.
336      * Suspending rules will prevent jobs in the system from executing, which may 
337      * have adverse effects on components that are relying on execution of jobs. 
338      * The job manager should never be suspended without intent to resume 
339      * execution soon afterwards. Deadlock will result if the thread responsible
340      * for resuming the rule attempts to join a suspended job.
341      * 
342      * @deprecated This method is not safe and should not be used.
343      * Suspending a scheduling rule violates the thread safety
344      * of clients that use scheduling rules as a mutual exclusion mechanism,
345      * and can result in concurrency problems in all clients that use the suspended rule.
346      * @param rule The scheduling rule to suspend. Must not be <code>null</code>.
347      * @param monitor a progress monitor, or <code>null</code> if progress
348      * reporting is not desired
349      * @exception OperationCanceledException if the operation is canceled. 
350      * Cancelation can occur even if no progress monitor is provided.
351      * @see #resume(ISchedulingRule)
352      */
353     public void suspend(ISchedulingRule rule, IProgressMonitor monitor);
354 
355     /**
356      * Requests that all jobs in the given job family be suspended.  Jobs currently 
357      * waiting to be run will be removed from the queue and moved into the 
358      * <code>SLEEPING</code> state.  Jobs that have been put to sleep
359      * will remain in that state until either resumed or canceled.  This method has
360      * no effect on jobs that are not currently waiting to be run.
361      * <p>
362      * Sleeping jobs can be resumed using <code>wakeUp</code>.
363      * 
364      * @param family the job family to sleep, or <code>null</code> to sleep all jobs.
365      * @see Job#belongsTo(Object)
366      */
367     public void sleep(Object   family);
368 
369     /**
370      * Transfers ownership of a scheduling rule to another thread.  The identical
371      * scheduling rule must currently be owned by the calling thread as a result of 
372      * a previous call to <code>beginRule</code>.  The destination thread must
373      * not already own a scheduling rule.
374      * <p>
375      * Calling this method is equivalent to atomically calling <code>endRule</code> 
376      * in the calling thread followed by an immediate <code>beginRule</code> in 
377      * the destination thread.  The destination thread is responsible for subsequently 
378      * calling <code>endRule</code> when it is finished using the rule.
379      * <p>
380      * This method has no effect when the destination thread is the same as the
381      * calling thread.
382      * 
383      * @param rule The scheduling rule to transfer
384      * @param destinationThread The new owner for the transferred rule.
385      * @since 3.1
386      */
387     public void transferRule(ISchedulingRule rule, Thread   destinationThread);
388 
389     /**
390      * Resumes scheduling of all sleeping jobs in the given family.  This method
391      * has no effect on jobs in the family that are not currently sleeping.
392      * 
393      * @param family the job family to wake up, or <code>null</code> to wake up all jobs
394      * @see Job#belongsTo(Object)
395      */
396     public void wakeUp(Object   family);
397 }
398
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags