public class JobGroup
extends org.eclipse.core.internal.jobs.InternalJobGroup
JobGroups maintain state for the collective status of the jobs belonging to the group.
When constructed, a job group starts with a state value of NONE
.
When any job belonging to the group is scheduled to run, the job group moves into the
ACTIVE
state. A job group enters the CANCELING
state
when cancellation of the whole group is requested. The group will be in this state
until all the jobs in the group have finished either through cancellation or
normal completion. When a job group is in the CANCELING
state,
newly scheduled jobs which are part of that group are immediately canceled.
When execution of all the jobs belonging to a job group finishes (either normally
or through cancellation), the job group state changes back to NONE
.
IJobManager
Modifier and Type | Field and Description |
---|---|
static int |
ACTIVE
JobGroup state code (value 1) indicating that at least one job belonging to
the group is running or scheduled to run.
|
static int |
CANCELING
JobGroup state code (value 2) indicating that cancellation of the whole group is requested.
|
static int |
NONE
JobGroup state code (value 0) indicating that none of the jobs belonging to
the group are running or scheduled to run.
|
Constructor and Description |
---|
JobGroup(String name,
int maxThreads,
int seedJobsCount)
Creates a new job group with the specified
name and maxThreads . |
Modifier and Type | Method and Description |
---|---|
void |
cancel()
Cancels all jobs belonging to this job group.
|
protected MultiStatus |
computeGroupResult(List<IStatus> jobResults)
This method is called by the JobManager when all the jobs belonging to the group
are completed.
|
List<Job> |
getActiveJobs()
Returns all waiting, executing and sleeping jobs belonging
to this job group.
|
int |
getMaxThreads()
Returns the maximum number of threads allowed to be scheduled by the jobs belonging
to the group at any given time, or
zero to indicate that no throttling
should be applied and all jobs should be allowed to run as soon as possible. |
String |
getName()
Returns the human readable name of this job group.
|
MultiStatus |
getResult()
Returns the result of this job group's last run.
|
int |
getState()
Returns the state of the job group.
|
boolean |
join(long timeoutMillis,
IProgressMonitor monitor)
Waits until either all jobs belonging to this job group have finished or
the given timeout has expired.
|
protected boolean |
shouldCancel(IStatus lastCompletedJobResult,
int numberOfFailedJobs,
int numberOfCanceledJobs)
This method is called by the JobManager after the completion of every job belonging
to this group, and is used to control the job group's cancellation policy.
|
public static final int NONE
getState()
,
Constant Field Valuespublic static final int ACTIVE
getState()
,
Constant Field Valuespublic static final int CANCELING
public JobGroup(String name, int maxThreads, int seedJobsCount)
name
and maxThreads
.
The job group name is a human-readable value that is displayed to users. The name does
not need to be unique, but it must not be null
. The maxThreads
indicates the maximum number of threads allowed to be concurrently scheduled by the
jobs belonging to the group at any given time, or zero
to indicate that
no throttling should be applied and all jobs should be allowed to run as soon as possible.name
- the name of the job group.maxThreads
- the maximum number of threads allowed to be concurrently scheduled,
or zero
to indicate that no throttling should be applied and all jobs
should be allowed to run as soon as possible.seedJobsCount
- the initial number of jobs that will be added to the job group.
This is the initial count of jobs with which the creator of the job group will "seed"
the job group. Those initial jobs may discover more work and add yet more jobs, but
those additional jobs should not be included in this initial "seed" count. If this
value is set too high, the job group will never transition to the done (NONE
)
state, join(long, IProgressMonitor)
calls will hang, and getResult()
calls will return invalid results. If this value is set too low, the job group may
transition to the (NONE
) state before all of the jobs have been scheduled,
causing a join(long, IProgressMonitor)
call to return too early.public final String getName()
null
.getName
in class org.eclipse.core.internal.jobs.InternalJobGroup
public final int getMaxThreads()
zero
to indicate that no throttling
should be applied and all jobs should be allowed to run as soon as possible.getMaxThreads
in class org.eclipse.core.internal.jobs.InternalJobGroup
public final MultiStatus getResult()
getResult
in class org.eclipse.core.internal.jobs.InternalJobGroup
null
if this
job group has never finished running.public final int getState()
JobGroup.NONE
- when the jobs belonging to the group are not yet scheduled to run.JobGroup.ACTIVE
- when the jobs belonging to the group are running or scheduled to run.JobGroup.CANCELING
- when the jobs belonging to the group are being canceled.Note that job group state is inherently volatile, and in most cases clients cannot rely on the result of this method being valid by the time the result is obtained. For example, if getState returns ACTIVE, the job group may have actually completed by the time the getState method returns. All that clients can infer from invoking this method is that the job group was recently in the returned state.
getState
in class org.eclipse.core.internal.jobs.InternalJobGroup
public final List<Job> getActiveJobs()
getActiveJobs
in class org.eclipse.core.internal.jobs.InternalJobGroup
Job.setJobGroup(JobGroup)
public final void cancel()
WAITING
state 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.
The job group will be placed into CANCELING
state and will be
in that state until all the jobs in the group have finished either through
cancellation or normal completion. When a job group is in the CANCELING
state, newly scheduled jobs which are part of the group are immediately canceled.
cancel
in class org.eclipse.core.internal.jobs.InternalJobGroup
Job.setJobGroup(JobGroup)
,
getState()
public final boolean join(long timeoutMillis, IProgressMonitor monitor) throws InterruptedException, OperationCanceledException
If this method is called while the job manager is suspended, only jobs
that are currently running will be joined. Once there are no jobs
belongs to the group in the Job.RUNNING
state, the method returns.
Jobs may be added to this job group after the initial set of jobs are scheduled, and this method will wait for all newly added jobs to complete (or the given timeout has expired), even if they are added to the group after this method is invoked.
Throws an OperationCanceledException
when the given progress monitor
is canceled. Canceling the monitor does not cancel the jobs belonging to the group and,
if required, the group may be canceled explicitly using the cancel()
method.
join
in class org.eclipse.core.internal.jobs.InternalJobGroup
timeoutMillis
- the maximum amount of time to wait for the join to complete,
or zero
for no timeout.monitor
- the progress monitor for reporting progress on how the wait is
progressing and to be able to cancel the join operation, or null
if no progress monitoring is required.true
when all the jobs in the group complete,
or false
when the operation is not completed within the given time.InterruptedException
- if the calling thread is interrupted while waitingOperationCanceledException
- if the progress monitor is canceled while waitingJob.setJobGroup(JobGroup)
,
cancel()
protected boolean shouldCancel(IStatus lastCompletedJobResult, int numberOfFailedJobs, int numberOfCanceledJobs)
true
from this function causes all remaining running and scheduled jobs
to be canceled.
The default implementation returns true
when numberOfFailedJobs > 0
.
Subclasses may override this method to implement a different cancellation strategy.
shouldCancel
in class org.eclipse.core.internal.jobs.InternalJobGroup
lastCompletedJobResult
- result of the last completed job belonging to this group.numberOfFailedJobs
- the total number of jobs belonging to this group that are
finished with status IStatus.ERROR
.numberOfCanceledJobs
- the total number of jobs belonging to this group that are
finished with status IStatus.CANCEL
.true
when the remaining jobs belonging to this group should be canceled.protected MultiStatus computeGroupResult(List<IStatus> jobResults)
The default implementation will return a MultiStatus
object containing
the returned statuses of the completed jobs. The results with IStatus.OK
are omitted from the result since those statuses usually do not contain valuable information.
Subclasses may override this method to implement custom status reporting,
but should never return null
.
computeGroupResult
in class org.eclipse.core.internal.jobs.InternalJobGroup
jobResults
- results of all the completed jobs belonging to this group.null
.getResult()
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.