Medical Imaging Interaction Toolkit  2023.04.00
Medical Imaging Interaction Toolkit
berry::Job Class Referenceabstract

#include <berryJob.h>

Inheritance diagram for berry::Job:
Collaboration diagram for berry::Job:

Public Member Functions

 berryObjectMacro (Job)
 
 Job (const QString &name)
 
void AddJobChangeListener (IJobChangeListener *listener)
 
bool BelongsTo (Object::Pointer family) override
 
bool Cancel ()
 
void Done (IStatus::Pointer result)
 
QString GetName () const
 
int GetPriority () const
 
IStatus::Pointer GetResult () const
 
ISchedulingRule::Pointer GetRule () const
 
int GetState () const
 
Poco::Thread * GetThread () const
 
bool IsBlocking ()
 
bool IsSystem () const
 
bool IsUser () const
 
void RemoveJobChangeListener (IJobChangeListener *listener)
 
void Schedule ()
 
void Schedule (Poco::Timestamp::TimeDiff delay)
 
void SetName (const QString &name)
 
void SetPriority (int priority)
 
void SetProgressGroup (IProgressMonitor::Pointer group, int ticks)
 
void SetRule (ISchedulingRule::Pointer rule)
 
void SetSystem (bool value)
 
void SetUser (bool value)
 
void SetThread (Poco::Thread *thread)
 
virtual bool ShouldRun ()
 
bool ShouldSchedule () override
 
bool Sleep ()
 
void WakeUp ()
 
void WakeUp (long delay)
 

Static Public Member Functions

static const IJobManagerGetJobManager ()
 

Static Public Attributes

static const IStatus::Pointer ASYNC_FINISH
 
static const int INTERACTIVE
 
static const int SHORT
 
static const int LONG
 
static const int BUILD
 
static const int DECORATE
 
static const int NONE
 
static const int SLEEPING
 
static const int WAITING
 
static const int RUNNING
 

Protected Member Functions

void Canceling () override
 
IStatus::Pointer Run (IProgressMonitor::Pointer myProgressMonitor) override=0
 

Detailed Description

Jobs are units of runnable work that can be scheduled to be run with the job manager. Once a job has completed, it can be scheduled to run again (jobs are reusable).

Jobs have a state that indicates what they are currently doing. When constructed, jobs start with a state value of NONE. When a job is scheduled to be run, it moves into the WAITING state. When a job starts running, it moves into the RUNNING state. When execution finishes (either normally or through cancellation), the state changes back to NONE.

A job can also be in the SLEEPING state. This happens if a user calls Job.sleep() on a waiting job, or if a job is scheduled to run after a specified delay. Only jobs in the WAITING state can be put to sleep. Sleeping jobs can be woken at any time using Job.wakeUp(), which will put the job back into the WAITING state.

Jobs can be assigned a priority that is used as a hint about how the job should be scheduled. There is no guarantee that jobs of one priority will be run before all jobs of lower priority. The documentation of the various priority constants provide more detail about what each priority means. By default, jobs start in the LONG priority class.

See also
IJobManager

Definition at line 58 of file berryJob.h.

Constructor & Destructor Documentation

◆ Job()

berry::Job::Job ( const QString &  name)

Creates a new job with the specified name. The job 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.

Parameters
namethe name of the job.

Member Function Documentation

◆ AddJobChangeListener()

void berry::Job::AddJobChangeListener ( IJobChangeListener listener)

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

Parameters
listenerthe listener to be added.

◆ BelongsTo()

bool berry::Job::BelongsTo ( Object::Pointer  family)
override

Returns whether this job belongs to the given family. Job families are represented as objects that are not interpreted or specified in any way by the job manager. Thus, a job can choose to belong to any number of families.

Clients may override this method. This default implementation always returns false. Overriding implementations must return false for families they do not recognize.

Parameters
familythe job family identifier
Returns
true if this job belongs to the given family, and false otherwise.

◆ berryObjectMacro()

berry::Job::berryObjectMacro ( Job  )

◆ Cancel()

bool berry::Job::Cancel ( )

Stops the job. If the job is currently waiting, it will be removed from the queue. If the job is sleeping, it will be discarded without having a chance to resume and its sleeping state will be cleared. If the job is currently executing, it will be asked to stop but there is no guarantee that it will do so.

Returns
false if the job is currently running (and thus may not respond to cancellation), and true in all other cases.

◆ Canceling()

void berry::Job::Canceling ( )
overrideprotected

A hook method indicating that this job is running and Cancel() is being called for the first time.

Subclasses may override this method to perform additional work when a cancellation request is made. This default implementation does nothing.

◆ Done()

void berry::Job::Done ( IStatus::Pointer  result)

Jobs that complete their execution asynchronously must indicate when they are finished by calling this method. This method must not be called by a job that has not indicated that it is executing asynchronously.

This method must not be called from within the scope of a job's run method. Jobs should normally indicate completion by returning an appropriate status from the run method. Jobs that return a status of ASYNC_FINISH from their run method must later call done to indicate completion.

Parameters
resulta status object indicating the result of the job's execution.
See also
ASYNC_FINISH
Run(IProgressMonitor::Pointer)

◆ GetJobManager()

static const IJobManager* berry::Job::GetJobManager ( )
static

Returns the job manager.

Returns
the job manager

◆ GetName()

QString berry::Job::GetName ( ) const

Returns the human readable name of this job. The name is never null.

Returns
the name of this job

◆ GetPriority()

int berry::Job::GetPriority ( ) const

Returns the priority of this job. The priority is used as a hint when the job is scheduled to be run.

Returns
the priority of the job. One of INTERACTIVE, SHORT, LONG, BUILD, or DECORATE.

◆ GetResult()

IStatus::Pointer berry::Job::GetResult ( ) const

Returns the result of this job's last run.

Returns
the result of this job's last run, or null if this job has never finished running.

◆ GetRule()

ISchedulingRule::Pointer berry::Job::GetRule ( ) const

Returns the scheduling rule for this job. Returns null if this job has no scheduling rule.

Returns
the scheduling rule for this job, or null.
See also
ISchedulingRule
SetRule(ISchedulingRule::Pointer)

◆ GetState()

int berry::Job::GetState ( ) const

Returns the state of the job. Result will be one of:

Note that job 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 RUNNING, the job may have actually completed by the time the getState method returns. All clients can infer from invoking this method is that the job was recently in the returned state.

Returns
the job state

◆ GetThread()

Poco::Thread* berry::Job::GetThread ( ) const

Returns the thread that this job is currently running in.

Returns
the thread this job is running in, or null if this job is not running or the thread is unknown.

◆ IsBlocking()

bool berry::Job::IsBlocking ( )

Returns whether this job is blocking a higher priority non-system job from starting due to a conflicting scheduling rule. Returns false if this job is not running, or is not blocking a higher priority non-system job.

Returns
true if this job is blocking a higher priority non-system job, and false otherwise.
See also
GetRule()
IsSystem()

◆ IsSystem()

bool berry::Job::IsSystem ( ) const

Returns whether this job is a system job. System jobs are typically not revealed to users in any UI presentation of jobs. Other than their UI presentation, system jobs act exactly like other jobs. If this value is not explicitly set, jobs are treated as non-system jobs. The default value is false.

Returns
true if this job is a system job, and false otherwise.
See also
SetSystem(bool)

◆ IsUser()

bool berry::Job::IsUser ( ) const

Returns whether this job has been directly initiated by a UI end user. These jobs may be presented differently in the UI. The default value is false.

Returns
true if this job is a user-initiated job, and false otherwise.
See also
SetUser(bool)

◆ RemoveJobChangeListener()

void berry::Job::RemoveJobChangeListener ( IJobChangeListener listener)

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

Parameters
listenerthe listener to be removed

◆ Run()

IStatus::Pointer berry::Job::Run ( IProgressMonitor::Pointer  myProgressMonitor)
overrideprotectedpure virtual

Executes this job. Returns the result of the execution.

The provided monitor can be used to report progress and respond to cancellation. If the progress monitor has been canceled, the job should finish its execution at the earliest convenience and return a result status of severity IStatus.CANCEL . The singleton cancel status Status#CANCEL_STATUS can be used for this purpose. The monitor is only valid for the duration of the invocation of this method.

This method must not be called directly by clients. Clients should call schedule, which will in turn cause this method to be called.

Jobs can optionally finish their execution asynchronously (in another thread) by returning a result status of ASYNC_FINISH. Jobs that finish asynchronously must specify the execution thread by calling setThread, and must indicate when they are finished by calling the method done.

Parameters
myProgressMonitorthe monitor to be used for reporting progress and responding to cancellation. The monitor is never null
Returns
resulting status of the run. The result must not be null
See also
ASYNC_FINISH

◆ Schedule() [1/2]

void berry::Job::Schedule ( )

Schedules this job to be run. The job is added to a queue of waiting jobs, and will be run when it arrives at the beginning of the queue.

This is a convenience method, fully equivalent to Schedule(0L).

◆ Schedule() [2/2]

void berry::Job::Schedule ( Poco::Timestamp::TimeDiff  delay)

Schedules this job to be run after a specified delay. The job is put in the SLEEPING state until the specified delay has elapsed, after which the job is added to a queue of WAITING jobs. Once the job arrives at the beginning of the queue, it will be run at the first available opportunity.

Jobs of equal priority and delay with conflicting scheduling rules are guaranteed to run in the order they are scheduled. No guarantees are made about the relative execution order of jobs with unrelated or null scheduling rules, or different priorities.

If this job is currently running, it will be rescheduled with the specified delay as soon as it finishes. If this method is called multiple times while the job is running, the job will still only be rescheduled once, with the most recent delay value that was provided.

Scheduling a job that is waiting or sleeping has no effect.

Parameters
delaya time delay in milliseconds before the job should run
See also
ISchedulingRule

◆ SetName()

void berry::Job::SetName ( const QString &  name)

Changes the name of this job. If the job is currently running, waiting, or sleeping, the new job name may not take effect until the next time the job is scheduled.

The job 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.

Parameters
namethe name of the job.

◆ SetPriority()

void berry::Job::SetPriority ( int  priority)

Sets the priority of the job. This will not affect the execution of a running job, but it will affect how the job is scheduled while it is waiting to be run.

Parameters
prioritythe new job priority. One of INTERACTIVE, SHORT, LONG, BUILD, or DECORATE.

◆ SetProgressGroup()

void berry::Job::SetProgressGroup ( IProgressMonitor::Pointer  group,
int  ticks 
)

Associates this job with a progress group. Progress feedback on this job's next execution will be displayed together with other jobs in that group. The provided monitor must be a monitor created by the method IJobManager.createProgressGroup and must have at least ticks units of available work.

The progress group must be set before the job is scheduled. The group will be used only for a single invocation of the job's run method, after which any association of this job to the group will be lost.

See also
IJobManager::createProgressGroup()
Parameters
groupThe progress group to use for this job
ticksthe number of work ticks allocated from the parent monitor, or IProgressMonitor#UNKNOWN

◆ SetRule()

void berry::Job::SetRule ( ISchedulingRule::Pointer  rule)

Sets the scheduling rule to be used when scheduling this job. This method must be called before the job is scheduled.

Parameters
rulethe new scheduling rule, or null if the job should have no scheduling rule
See also
GetRule()

◆ SetSystem()

void berry::Job::SetSystem ( bool  value)

Sets whether or not this job is a system job. System jobs are typically not revealed to users in any UI presentation of jobs. Other than their UI presentation, system jobs act exactly like other jobs. If this value is not explicitly set, jobs are treated as non-system jobs. This method must be called before the job is scheduled.

Parameters
valuetrue if this job should be a system job, and false otherwise.
See also
IsSystem()

◆ SetThread()

void berry::Job::SetThread ( Poco::Thread *  thread)

Sets the thread that this job is currently running in, or null if this job is not running or the thread is unknown.

Jobs that use the ASYNC_FINISH return code should tell the job what thread it is running in. This is used to prevent deadlocks.

Parameters
threadthe thread that this job is running in.
See also
ASYNC_FINISH
Run(IProgressMonitor::Pointer)

◆ SetUser()

void berry::Job::SetUser ( bool  value)

Sets whether or not this job has been directly initiated by a UI end user. These jobs may be presented differently in the UI. This method must be called before the job is scheduled.

Parameters
valuetrue if this job is a user-initiated job, and false otherwise.
See also
IsUser()

◆ ShouldRun()

virtual bool berry::Job::ShouldRun ( )
virtual

Returns whether this job should be run. If false is returned, this job will be discarded by the job manager without running.

This method is called immediately prior to calling the job's run method, so it can be used for last minute pre-condition checking before a job is run. This method must not attempt to schedule or change the state of any other job.

Clients may override this method. This default implementation always returns true.

Returns
true if this job should be run and false otherwise

◆ ShouldSchedule()

bool berry::Job::ShouldSchedule ( )
override

Returns whether this job should be scheduled. If false is returned, this job will be discarded by the job manager without being added to the queue.

This method is called immediately prior to adding the job to the waiting job queue.,so it can be used for last minute pre-condition checking before a job is scheduled.

Clients may override this method. This default implementation always returns true.

Returns
true if the job manager should schedule this job and false otherwise

◆ Sleep()

bool berry::Job::Sleep ( )

Requests that this job be suspended. If the job is currently waiting to be run, it will be removed from the queue move into the SLEEPING state. The job will remain asleep until either resumed or canceled. If this job is not currently waiting to be run, this method has no effect.

Sleeping jobs can be resumed using wakeUp.

Returns
false if the job is currently running (and thus cannot be put to sleep), and true in all other cases
See also
WakeUp()

◆ WakeUp() [1/2]

void berry::Job::WakeUp ( )

Puts this job immediately into the WAITING state so that it is eligible for immediate execution. If this job is not currently sleeping, the request is ignored.

This is a convenience method, fully equivalent to wakeUp(0L).

See also
Sleep()

◆ WakeUp() [2/2]

void berry::Job::WakeUp ( long  delay)

Puts this job back into the WAITING state after the specified delay. This is equivalent to canceling the sleeping job and rescheduling with the given delay. If this job is not currently sleeping, the request is ignored.

Parameters
delaythe number of milliseconds to delay
See also
Sleep()

Member Data Documentation

◆ ASYNC_FINISH

const IStatus::Pointer berry::Job::ASYNC_FINISH
static

Job status return value that is used to indicate asynchronous job completion.

See also
Job::Run(IProgressMonitor::Pointer)
Job::Done(IStatus::Pointer)

Definition at line 70 of file berryJob.h.

◆ BUILD

const int berry::Job::BUILD
static

Job priority constant (value 40) for build jobs. Build jobs are generally run after all other background jobs complete.

See also
GetPriority()
SetPriority(int)

Definition at line 110 of file berryJob.h.

◆ DECORATE

const int berry::Job::DECORATE
static

Job priority constant (value 50) for decoration jobs. Decoration jobs have lowest priority. Decoration jobs generally compute extra information that the user may be interested in seeing but is generally not waiting for.

See also
GetPriority()
SetPriority(int)

Definition at line 121 of file berryJob.h.

◆ INTERACTIVE

const int berry::Job::INTERACTIVE
static

Job priority constant (value 10) for interactive jobs. Interactive jobs generally have priority over all other jobs. Interactive jobs should be either fast running or very low on CPU usage to avoid blocking other interactive jobs from running.

See also
GetPriority()
SetPriority(int)
Run(IProgressMonitor::Pointer)

Definition at line 83 of file berryJob.h.

◆ LONG

const int berry::Job::LONG
static

Job priority constant (value 30) for long-running background jobs.

See also
GetPriority()
SetPriority(int)
Run(IProgressMonitor::Pointer)

Definition at line 102 of file berryJob.h.

◆ NONE

const int berry::Job::NONE
static

Job state code (value 0) indicating that a job is not currently sleeping, waiting, or running (i.e., the job manager doesn't know anything about the job).

See also
GetState()

Definition at line 129 of file berryJob.h.

◆ RUNNING

const int berry::Job::RUNNING
static

Job state code (value 4) indicating that a job is currently running

See also
GetState()

Definition at line 147 of file berryJob.h.

◆ SHORT

const int berry::Job::SHORT
static

Job priority constant (value 20) for short background jobs. Short background jobs are jobs that typically complete within a second, but may take longer in some cases. Short jobs are given priority over all other jobs except interactive jobs.

See also
GetPriority()
SetPriority(int)
Run(IProgressMonitor::Pointer)

Definition at line 94 of file berryJob.h.

◆ SLEEPING

const int berry::Job::SLEEPING
static

Job state code (value 1) indicating that a job is sleeping.

See also
GetState()

Definition at line 135 of file berryJob.h.

◆ WAITING

const int berry::Job::WAITING
static

Job state code (value 2) indicating that a job is waiting to be run.

See also
GetState()

Definition at line 141 of file berryJob.h.


The documentation for this class was generated from the following file: