BackgroundTask Class Reference

This class implements a framework for providing administrators with status and control of long-running tasks/utilities/operations that set to run in the background. More...

Inheritance diagram for BackgroundTask:

Collaboration diagram for BackgroundTask:

Public Member Functions
_.Library.Status	Cancel ()
	Request cancellation.
_.Library.Status	Pause ()
	Request pause.
_.Library.Status	Resume ()
	Request to resume from pause.

Static Public Member Functions
_.Library.ObjectHandle	Start (args)
	Starts this task in the background and returns on oref for monitoring and control. More...

Public Attributes
	CancelIsAvailable
	True if cancel is allowed for this task and the state (as of load time) More...
	Class
	The subclass name of the task; accessible via SQL where oref. More...
	DisplayType
	A text string to display as the type of background task as defined by its subclass. More...
	FinalStatus
	Status code when finished. More...
	HasEnded
	True if the <PROPERTY>RunningState</PROPERTY> is one that will not progress. More...
	Namespace
	Namespace in which the task is run. More...
	PID
	PID of job performing the work, available once the "Running" state has been entered. More...
	PauseIsAvailable
	True if pause is allowed for this task and the state (as of load time) More...
	ProgressCurrent
	The current amount of progress made. More...
	ProgressTotal
	The total amount of progress that must be made to complete. More...
	ProgressUnits
	The units in which progress is measured. More...
	Request
	Request to the running task. More...
	ResumeIsAvailable
	True if pause is allowed and the utility is paused. More...
	RunningState
	Information about whether the task is running or not. More...
	StartTime
	Start time of run. More...

Static Public Attributes
	CANCELDISPOSITION = None
	Disposition for cancel requests. More...
	PAUSEDISPOSITION = None
	Disposition for pause requests. More...

Detailed Description

This class implements a framework for providing administrators with status and control of long-running tasks/utilities/operations that set to run in the background.

These are typically (but not necessarily) tasks that are started interactively, but run in the background because they may run for a long time (e.g. some database management utilities). Note that this framework is separate from the "Task Manager" frameword which can be used to schedule activity.

There are subclasses for each type of operation that uses this infrastructure and objects of those subclasses represent instances that are running or have run since the system started up.

To use this framework for progress and control of a background task, you simply open or query objects the objects through this class or the relevant subclass. The properties represent a snapshot of the state and progress of the task. You can periodically check for changes by rerunning the query or reloading the object via standard object interfaces <METHOD>OpenId</METHOD> and <METHOD>Reload</METHOD>.

<PROPERTY>RunningState</PROPERTY> contains information about whether the task is running or not (as of the time the object was last loaded or queried). Progress information may be available via <PROPERTY>ProgressCurrent</PROPERTY>, <PROPERTY>ProgressTotal</PROPERTY> and <PROPERTY>ProgressUnits</PROPERTY>. When complete, the Status is available in <PROPERY>FinalStatus</PROPERTY>. Subclasses may expose other properties that are germain to that particular type of operation.

<METHOD>Pause</METHOD>, <METHOD>Resume</METHOD>, and <METHOD>Cancel</METHOD> are enabled for some subclasses

Users should not modify properties or save these objects.

To start a job running the task in the background, you can use class method <METHOD>Start</METHOD> in the desired subclass. The arguments are unique to each subclass. <METHOD>Start</METHOD> returns an oref to use for monitor and control.

Member Function Documentation

Start()

_.Library.ObjectHandle Start (   args )

static

Starts this task in the background and returns on oref for monitoring and control.

Returns null on error, with error status available in objlasterror. The meaning of the arguments are specific to each subclass.

Member Data Documentation

CANCELDISPOSITION

CANCELDISPOSITION = None

static

Disposition for cancel requests.

0 - not allowed
1 - polls for cancel requests
-1 - directly terminate the process

PAUSEDISPOSITION

PAUSEDISPOSITION = None

static

Disposition for pause requests.

0 - not allowed
1 - polls for pause requests
-1 - directly pause the process

CancelIsAvailable

CancelIsAvailable

True if cancel is allowed for this task and the state (as of load time)

is such that it can be paused. Used by user interface code to determine whether to enable a "cancel" control.  

Class

Class

The subclass name of the task; accessible via SQL where oref.

ClassName(1) is not be available.

 

DisplayType

DisplayType

A text string to display as the type of background task as defined by its subclass.

 

FinalStatus

FinalStatus

Status code when finished.

 

HasEnded

HasEnded

True if the <PROPERTY>RunningState</PROPERTY> is one that will not progress.

any further. Used by monitoring interfaces to determine whether monitoring should continue.  

Namespace

Namespace

Namespace in which the task is run.

 

PID

PID

PID of job performing the work, available once the "Running" state has been entered.

 

PauseIsAvailable

PauseIsAvailable

True if pause is allowed for this task and the state (as of load time)

is such that it can be paused. Used by user interface code to determine whether to enable a "pause" control.  

ProgressCurrent

ProgressCurrent

The current amount of progress made.

To be interpreted, along with <PROPERTY>ProgressTotal</PROPERTY>

and <PROPERTY>ProgressUnits</PROPERTY> as follows: non-zero total and non-null units: current and total values are to be displayed with the unit string.
non-zero total and null units: current / total is to be displayed as a percentage.
zero total, non-zero current, and non-null units: current is displayed with the unit string (without reference to the total). otherwise numeric progress not available.  

ProgressTotal

ProgressTotal

The total amount of progress that must be made to complete.

This value may

change while running as more accurate estimates become available. See <PROPERTY>ProgressCurrent</PROPERTY> for more detail.  

ProgressUnits

ProgressUnits

The units in which progress is measured.

Used to display progress to the

user. Null is allowed, treating progress as dimensionless. See <PROPERTY>ProgressCurrent</PROPERTY> for more details.  

Request

Request

Request to the running task.

1 is request to pause. 2 is request to cancel.

 

ResumeIsAvailable

ResumeIsAvailable

True if pause is allowed and the utility is paused.

Used by user

interface code to determine whether to enable a "resume" control.  

RunningState

RunningState

Information about whether the task is running or not.

Values are constants, defined for convenience in syBackgroundTask.inc "Starting" ($$$BGTaskStarting) - Object has been created but has not started working yet. "Running" ($$$BGTaskRunning) - Task is running "Done" ($$$BGTaskDone) - Task has completed successfully "Error" ($$$BGTaskError) - Task has returned an error - see <PROPERTY>FinalStatus</PROPERTY> "Paused" ($$$BGTaskPaused) - Task has been pasued "Cancelled" ($$$BGTaskCancelled) - Task has been cancelled "Exited" ($$$BGTaskExited) - Task exited unexpectedly and did not complete normally  

StartTime

StartTime

Start time of run.