Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.eclipse.core.runtime.jobs
Interface IJobManager

public interface IJobManager

The job manager provides facilities for scheduling, querying, and maintaining jobs and locks. In particular, the job manager provides the following services:

- Maintains a queue of jobs that are waiting to be run. Items can be added to the queue using the `schedule` method.
- Allows manipulation of groups of jobs called job families. Job families can be canceled, put to sleep, or woken up atomically. There is also a mechanism for querying the set of known jobs in a given family.
- Allows listeners to find out about progress on running jobs, and to find out when jobs have changed states.
- Provides a factory for creating lock objects. Lock objects are smart monitors that have strategies for avoiding deadlock.
- Provide feedback to a client that is waiting for a given job or family of jobs to complete.

This interface is not intended to be implemented by clients.

Since:
  3.0
See Also:
  `Job`, `ILock`

Method Summary
`void` | `addJobChangeListener(IJobChangeListener listener)` Registers a job listener with the job manager.
`void` | `beginRule(ISchedulingRule rule, IProgressMonitor monitor)` Begins applying this rule in the calling thread.
`void` | `cancel(Object family)` Cancels all jobs in the given job family.
`IProgressMonitor` | `createProgressGroup()` Returns a progress monitor that can be used to provide aggregated progress feedback on a set of running jobs.
`Job` | `currentJob()` Returns the job that is currently running in this thread, or null if there is no currently running job.
`void` | `endRule(ISchedulingRule rule)` Ends the application of a rule to the calling thread.
`Job[]` | `find(Object family)` Returns all waiting, executing and sleeping jobs belonging to the given family.
`void` | `join(Object family, IProgressMonitor monitor)` Waits until all jobs of the given family are finished.
`ILock` | `newLock()` Creates a new lock object.
`void` | `removeJobChangeListener(IJobChangeListener listener)` Removes a job listener from the job manager.
`void` | `resume()` Resumes execution of jobs after a previous `suspend`.
`void` | `resume(ISchedulingRule rule)` Resumes execution of jobs after a previous `suspend`.
`void` | `setLockListener(LockListener listener)` Provides a hook that is notified whenever a thread is about to wait on a lock, or when a thread is about to release a lock.
`void` | `setProgressProvider(ProgressProvider provider)` Registers a progress provider with the job manager.
`void` | `sleep(Object family)` Requests that all jobs in the given job family be suspended.
`void` | `suspend()` Suspends execution of all jobs.
`void` | `suspend(ISchedulingRule rule, IProgressMonitor monitor)` Defers execution of all jobs with scheduling rules that conflict with the given rule.
`void` | `wakeUp(Object family)` Resumes scheduling of all sleeping jobs in the given family.

Method Detail

### addJobChangeListener

    public void addJobChangeListener(IJobChangeListener listener)

  Registers a job listener with the job manager. Has no effect if an identical listener is already registered.

  Parameters:
    `listener` - the listener to be added
  See Also:
    `removeJobChangeListener(IJobChangeListener)`, `IJobChangeListener`

### beginRule

    public void beginRule(ISchedulingRule rule,
                          IProgressMonitor monitor)

  Begins applying this rule in the calling thread. If the rule conficts with another rule currently running in another thread, this method blocks until there are no conflicting rules. Calls to `beginRule` must eventually be followed by a matching call to `endRule` in the same thread and with the identical rule instance.

  Rules can be nested only if the rule for the inner `beginRule` is contained within the rule for the outer `beginRule`. Rule containment is tested with the API method `ISchedulingRule.contains`. Also, begin/end pairs must be strictly nested. Only the rule that has most recently begun can be ended at any given time.

  A rule of `null` can be used, but will be ignored for scheduling purposes. The outermost non-null rule in the thread will be used for scheduling. A `null` rule that is begun must still be ended.

  If this method is called from within a job that has a scheduling rule, the given rule must also be contained within the rule for the running job.

  Note that `endRule` must be called even if `beginRule` fails. The recommended usage is:

       final ISchedulingRule rule = ...;
       try {
       	manager.beginRule(rule, monitor);
       } finally {
       	manager.endRule(rule);
       }

  Parameters:
    `rule` - the rule to begin applying in this thread, or `null`
    `monitor` - a progress monitor, or `null` if progress reporting and cancellation are not desired
  Throws:
    `IllegalArgumentException` - if the rule is not strictly nested within all other rules currently active for this thread
    `OperationCanceledException` - if the supplied monitor reports cancelation before the rule becomes available
  See Also:
    `ISchedulingRule.contains(ISchedulingRule)`

### cancel

    public void cancel(Object family)

  Cancels all jobs in the given job family. Jobs in the family that are currently waiting will be removed from the queue. Sleeping jobs will be discarded without having a chance to wake up. Currently executing jobs will be asked to cancel but there is no guarantee that they will do so.

  Parameters:
    `family` - the job family to cancel, or `null` to cancel all jobs
  See Also:
    `Job.belongsTo(Object)`

### createProgressGroup

    public IProgressMonitor createProgressGroup()

  Returns a progress monitor that can be used to provide aggregated progress feedback on a set of running jobs. A user interface will typically group all jobs in a progress group together, providing progress feedback for individual jobs as well as aggregrated progress for the entire group. Jobs in the group may be run sequentially, in parallel, or some combination of the two.

  Recommended usage (this snippet runs two jobs in sequence in a single progress group):

          Job parseJob, compileJob;
          IProgressMonitor pm = Platform.getJobManager().createProgressGroup();
          try {
             pm.beginTask("Building", 10);
             parseJob.setProgressGroup(pm, 5);
             parseJob.schedule();
             compileJob.setProgressGroup(pm, 5);
             compileJob.schedule();
             parseJob.join();
             compileJob.join();
          } finally {
             pm.done();
          }

  Returns:
    a progress monitor
  See Also:
    `Job.setProgressGroup(IProgressMonitor, int)`, `IProgressMonitor`

### currentJob

    public Job currentJob()

  Returns the job that is currently running in this thread, or null if there is no currently running job.

  Returns:
    the job or `null`

### endRule

    public void endRule(ISchedulingRule rule)

  Ends the application of a rule to the calling thread. Calls to `endRule` must be preceded by a matching call to `beginRule` in the same thread with an identical rule instance.

  Rules can be nested only if the rule for the inner `beginRule` is contained within the rule for the outer `beginRule`. Also, begin/end pairs must be strictly nested. Only the rule that has most recently begun can be ended at any given time.

  Parameters:
    `rule` - the rule to end applying in this thread
  Throws:
    `IllegalArgumentException` - if this method is called on a rule for which there is no matching begin, or that does not match the most recent begin.
  See Also:
    `ISchedulingRule.contains(ISchedulingRule)`

### find

    public Job[] find(Object family)

  Returns all waiting, executing and sleeping jobs belonging to the given family. If no jobs are found, an empty array is returned.

  Parameters:
    `family` - the job family to find, or `null` to find all jobs
  Returns:
    the job array
  See Also:
    `Job.belongsTo(Object)`

### join

    public void join(Object family,
                     IProgressMonitor monitor)
              throws InterruptedException,
                     OperationCanceledException

  Waits until all jobs of the given family are finished. This method will block the calling thread until all such jobs have finished executing, or until this thread is interrupted. If there are no jobs in the family that are currently waiting, running, or sleeping, this method returns immediately. Feedback on how the join is progressing is provided to a progress monitor.

  Note that there is a deadlock risk when using join. If the calling thread owns a lock or object monitor that the joined thread is waiting for, deadlock will occur. This method can also result in starvation of the current thread if another thread continues to add jobs of the given family, or if a job in the given family reschedules itself in an infinite loop.

  Parameters:
    `family` - the job family to join, or `null` to join all jobs.
    `monitor` - Progress monitor for reporting progress on how the wait is progressing, or `null` if no progress monitoring is required.
  Throws:
    `InterruptedException` - if this thread is interrupted while waiting
    `OperationCanceledException` - if the progress monitor is canceled while waiting
  See Also:
    `Job.belongsTo(Object)`

### newLock

    public ILock newLock()

  Creates a new lock object. All lock objects supplied by the job manager know about each other and will always avoid circular deadlock amongst themselves.

  Returns:
    the new lock object

### removeJobChangeListener

    public void removeJobChangeListener(IJobChangeListener listener)

  Removes a job listener from the job manager. Has no effect if an identical listener is not already registered.

  Parameters:
    `listener` - the listener to be removed
  See Also:
    `addJobChangeListener(IJobChangeListener)`, `IJobChangeListener`

### resume

    public void resume(ISchedulingRule rule)

  Resumes execution of jobs after a previous `suspend`. All jobs that were sleeping or waiting prior to the suspension, or that were scheduled while the job manager was suspended, will now be elligible for execution.

  Calling this method on a rule that is not suspended has no effect. If another thread also owns the rule at the time this method is called, then the rule will not be resumed until all threads have released the rule.

  See Also:
    `suspend(ISchedulingRule, IProgressMonitor)`

### resume

    public void resume()

  Resumes execution of jobs after a previous `suspend`. All jobs that were sleeping or waiting prior to the suspension, or that were scheduled while the job manager was suspended, will now be elligible for execution.

  Calling `resume` when the job manager is not suspended has no effect.

  See Also:
    `suspend()`

### setLockListener

    public void setLockListener(LockListener listener)

  Provides a hook that is notified whenever a thread is about to wait on a lock, or when a thread is about to release a lock. This hook must only be set once.

  This method is for internal use by the platform-related plug-ins. Clients should not call this method.

  See Also:
    `LockListener`

### setProgressProvider

    public void setProgressProvider(ProgressProvider provider)

  Registers a progress provider with the job manager. If there was a provider already registered, it is replaced.

  This method is for internal use by the platform-related plug-ins. Clients should not call this method.

  Parameters:
    `provider` - the new provider, or `null` if no progress is needed

### suspend

    public void suspend()

  Suspends execution of all jobs. Jobs that are already running when this method is invoked will complete as usual, but all sleeping and waiting jobs will not be executed until the job manager is resumed.

  The job manager will remain suspended until a subsequent call to `resume`. Further calls to `suspend` when the job manager is already suspended are ignored.

  All attempts to join sleeping and waiting jobs while the job manager is suspended will return immediately.

  Note that this very powerful function should be used with extreme caution. Suspending the job manager will prevent all jobs in the system from executing, which may have adverse affects on components that are relying on execution of jobs. The job manager should never be suspended without intent to resume execution soon afterwards.

  See Also:
    `resume()`

### suspend

    public void suspend(ISchedulingRule rule,
                        IProgressMonitor monitor)

  Defers execution of all jobs with scheduling rules that conflict with the given rule. The caller will be blocked until all currently executing jobs with conflicting rules are completed. Conflicting jobs that are sleeping or waiting at the time this method is called will not be executed until the rule is resumed.

  While a rule is suspended, all calls to `beginRule` and `endRule` on a suspended rule will not block the caller. The rule remains suspended until a subsequent call to `resume(ISchedulingRule)` with the identical rule instance. Further calls to `suspend` with an identical rule prior to calling `resume` are ignored.

  This method is long-running; progress and cancelation are provided by the given progress monitor. In the case of cancelation, the rule will not be suspended.

  Note: this very powerful function should be used with extreme caution. Suspending rules will prevent jobs in the system from executing, which may have adverse effects on components that are relying on execution of jobs. The job manager should never be suspended without intent to resume execution soon afterwards. Deadlock will result if the thread responsible for resuming the rule attempts to join a suspended job.

  Parameters:
    `rule` - The scheduling rule to suspend. Must not be `null`.
    `monitor` - a progress monitor, or `null` if progress reporting is not desired
  Throws:
    `OperationCanceledException` - if the operation is canceled. Cancelation can occur even if no progress monitor is provided.
  See Also:
    `resume(ISchedulingRule)`

### sleep

    public void sleep(Object family)

  Requests that all jobs in the given job family be suspended. Jobs currently waiting to be run will be removed from the queue and moved into the `SLEEPING` state. Jobs that have been put to sleep will remain in that state until either resumed or canceled. This method has no effect on jobs that are not currently waiting to be run.

  Sleeping jobs can be resumed using `wakeUp`.

  Parameters:
    `family` - the job family to sleep, or `null` to sleep all jobs.
  See Also:
    `Job.belongsTo(Object)`

### wakeUp

    public void wakeUp(Object family)

  Resumes scheduling of all sleeping jobs in the given family. This method has no effect on jobs in the family that are not currently sleeping.

  Parameters:
    `family` - the job family to wake up, or `null` to wake up all jobs
  See Also:
    `Job.belongsTo(Object)`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Eclipse Platform Release 3.0
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2004. All rights reserved.