|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.sun.electric.tool.Job
public abstract class Job
Jobs are processes that will run in the background, such as DRC, NCC, Netlisters, etc. Each Job gets placed in a Job window, and reports its status. A job can be cancelled.
To start a new job, do:
Job job = new Job(name);
job.start();
Job subclass must implement "doIt" method, it may override "terminateOK" method.
Job subclass is activated by "Job.startJob()". In case of exception in constructor it is not activated. Hence "doIt" and "terminateOK" method are not called.
Job subclass must be serializable for CHANGE and REMOTE_EXAMINE mode. Serialization occurs at the moment when "Job.startJob()" is called. Fields that are not needed on the server are escaped from serialization by "transient" keyword. "doIt" is executed on serverDatabase for CHANGE and REMOTE_EXAMINE mode. "doIt" is executed on clientDatabase for EXAMINE mode, Job subclass need not be serializable.
"doIt" may return true, may return false, may throw JobException or any other Exception/Error. Return true is considered normal termination. Return false and throwing any Exception/Throwable are failure terminations.
On normal termination in CHANGE or REMOTE_EXAMINE mode "fieldVariableChanged" variables are serialized. In case of REMOTE_EXAMINE they are serialized on read-only database state. In case of CHANGE they are serialized on database state after Constraint propagation. In case of EXAMINE they are not serialized, but they are checked for valid field names. Some time later the changed variables are deserialized on client database. If serialization on server and deserialization on client was OK then terminateOK method is called on client database for all three modes CHANGE, REMOTE_EXAMINE, EXAMINE. If serialization/deserialization failed then terminateOK is not called, error message is issued.
In case of failure termination no terminateOK is called, error message is issued,
The extendig class may override getProgress(), which returns a string indicating the current status. Job also contains boolean abort, which gets set when the user decides to abort the Job. The extending class' code should check abort when/where applicable.
Note that if your Job calls methods outside of this thread that access shared data, those called methods should be synchronized.
Nested Class Summary | |
---|---|
static class |
Job.Mode
Mode of Job manager |
static class |
Job.Priority
Priority is a typesafe enum class that describes the priority of a job. |
static class |
Job.Type
Type is a typesafe enum class that describes the type of job (CHANGE or EXAMINE). |
Field Summary | |
---|---|
static boolean |
BATCHMODE
|
protected long |
endTime
job end time |
static boolean |
LOCALDEBUGFLAG
|
protected long |
startTime
job start time |
Constructor Summary | |
---|---|
Job(java.lang.String jobName,
Tool tool,
Job.Type jobType,
Cell upCell,
Cell downCell,
Job.Priority priority)
Constructor creates a new instance of Job. |
Method Summary | |
---|---|
void |
abort()
Tell thread to abort. |
static boolean |
acquireExamineLock(boolean block)
Unless you need to code to execute quickly (such as in the GUI thread) you should be using a Job to examine the database instead of this method. |
boolean |
checkAbort()
Check if we are scheduled to abort. |
abstract boolean |
doIt()
This is the main work method. |
protected void |
fieldVariableChanged(java.lang.String variableName)
Method to remember that a field variable of the Job has been changed by the doIt() method. |
static java.util.Iterator<Job> |
getAllJobs()
get all jobs iterator |
EDatabase |
getDatabase()
|
static boolean |
getDebug()
Method to tell whether Electric is running in "debug" mode. |
boolean |
getDeleteWhenDone()
get deleteWhenDone status |
boolean |
getDisplay()
get display status |
static AbstractUserInterface |
getExtendedUserInterface()
Low-level method. |
java.lang.String |
getInfo()
Get info on Job |
static int |
getNumThreads()
|
static Job.Mode |
getRunMode()
|
static Job |
getRunningJob()
If this current thread is a EThread running a Job return the Job. |
protected boolean |
getScheduledToAbort()
get scheduled to abort status |
java.lang.String |
getStatus()
get status |
static UserInterface |
getUserInterface()
|
static void |
initJobManager(int numThreads,
Job initDatabaseJob,
java.lang.Object mode,
java.lang.String serverMachineName)
|
static void |
invokeExamineLater(java.lang.Runnable task,
java.lang.Object singularKey)
A common pattern is that the GUI needs to examine the database, but does not want to wait if it cannot immediately get an Examine lock via acquireExamineLock. |
boolean |
isFinished()
Return run status |
static void |
releaseExamineLock()
Release the lock to examine the database. |
boolean |
remove()
Remove job from Job list if it is done |
static void |
setDebug(boolean f)
|
protected void |
setProgress(java.lang.String progress)
|
protected void |
setReportExecutionFlag(boolean flag)
Set reportExecution flag on/off |
static void |
setThreadMode(Job.Mode mode,
AbstractUserInterface userInterface)
|
void |
startJob()
Start a job. |
void |
startJob(boolean display,
boolean deleteWhenDone)
Start the job by placing it on the JobThread queue. |
void |
startJobOnMyResult()
Start a job on snapshot obtained at the end of current job. |
void |
terminateFail(java.lang.Throwable jobException)
This method executes in the Client side after exceptional termination of doIt method. |
void |
terminateIt(java.lang.Throwable jobException)
This method executes in the Client side after termination of doIt method. |
void |
terminateOK()
This method executes in the Client side after normal termination of doIt method. |
static EDatabase |
threadDatabase()
|
java.lang.String |
toString()
|
static void |
updateIncrementalDRCErrors(Cell cell,
java.util.List<ErrorLogger.MessageLog> newErrors,
java.util.List<ErrorLogger.MessageLog> delErrors)
|
static void |
updateNetworkErrors(Cell cell,
java.util.List<ErrorLogger.MessageLog> errors)
|
static void |
wantUpdateGui()
|
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static boolean BATCHMODE
public static boolean LOCALDEBUGFLAG
protected long startTime
protected long endTime
Constructor Detail |
---|
public Job(java.lang.String jobName, Tool tool, Job.Type jobType, Cell upCell, Cell downCell, Job.Priority priority)
jobName
- a string that describes this Job.tool
- the Tool that originated this Job.jobType
- the Type of this Job (EXAMINE or CHANGE).upCell
- the Cell at the bottom of a hierarchical "up cone" of change.
If this and "downCell" are null, the entire database is presumed.downCell
- the Cell at the top of a hierarchical "down tree" of changes/examinations.
If this and "upCell" are null, the entire database is presumed.priority
- the priority of this Job.Method Detail |
---|
public static boolean getDebug()
public static void setDebug(boolean f)
public static void setThreadMode(Job.Mode mode, AbstractUserInterface userInterface)
public static void initJobManager(int numThreads, Job initDatabaseJob, java.lang.Object mode, java.lang.String serverMachineName)
public static Job.Mode getRunMode()
public static int getNumThreads()
public void startJob()
startJob(true, true)
.
public void startJobOnMyResult()
public void startJob(boolean display, boolean deleteWhenDone)
display
is true, display job on Job List UI.
If deleteWhenDone
is true, Job will be deleted
after it is done (frees all data and references it stores/created)
deleteWhenDone
- delete when job is done if true, otherwise leave it aroundprotected void fieldVariableChanged(java.lang.String variableName)
variableName
- the name of the variable that changed.public abstract boolean doIt() throws JobException
JobException
- TODOpublic void terminateIt(java.lang.Throwable jobException)
jobException
- null if doIt terminated normally, otherwise exception thrown by doIt.public void terminateOK()
public void terminateFail(java.lang.Throwable jobException)
jobException
- null exception thrown by doIt.protected void setReportExecutionFlag(boolean flag)
protected void setProgress(java.lang.String progress)
public boolean isFinished()
public void abort()
protected boolean getScheduledToAbort()
public boolean getDisplay()
public boolean getDeleteWhenDone()
public boolean checkAbort()
public static java.util.Iterator<Job> getAllJobs()
public static Job getRunningJob()
public java.lang.String getStatus()
public boolean remove()
public static boolean acquireExamineLock(boolean block)
if (Job.acquireExamineLock(block)) {
try {
// do stuff
Job.releaseExamineLock(); // release lock
} catch (Error e) {
Job.releaseExamineLock(); // release lock if error/exception thrown
throw e; // rethrow error/exception
}
}
This method tries to acquire a lock to allow the current thread to safely examine the database. If "block" is true, this call blocks until a lock is acquired. If block is false, this call returns immediately, returning true if a lock was acquired, or false if not. You must call Job.releaseExamineLock when done if you acquired a lock.
Subsequent nested calls to this method from the same thread must have matching calls to releaseExamineLock.
block
- True to block (wait) until lock can be acquired. False to
return immediately with a return value that denotes if a lock was acquired.
releaseExamineLock()
,
invokeExamineLater(Runnable, Object)
public static void releaseExamineLock()
acquireExamineLock(boolean)
,
invokeExamineLater(Runnable, Object)
public static void invokeExamineLater(java.lang.Runnable task, java.lang.Object singularKey)
This method basically reserves a slot in the Job queue with an Examine Job, calls the runnable with SwingUtilities.invokeAndWait when the Job starts, and ends the Job only after the runnable finishes.
IMPORTANT! Note that this ties up both the Job queue and the Swing event queue. It is possible to deadlock if the SwingExamineJob waits on a Change Job thread (unlikely, but possible). Note that this also runs examines sequentially, because that is how the Swing event queue runs events. This is less efficient than the Job queue examines, but also maintains sequential ordering and process of events, which may be necessary if state is being shared/modified between events (such as between mousePressed and mouseReleased events).
task
- the Runnable to run in the swing thread. A call to
Job.acquireExamineLock from within run() is guaranteed to return true.singularKey
- if not null, this specifies a key by which
subsequent calls to this method using the same key will be consolidated into
one invocation instead of many. Only calls that have not already resulted in a
call back to the runnable will be ignored. Only the last runnable will be used.for a common pattern using this method
,
acquireExamineLock(boolean)
,
releaseExamineLock()
public static UserInterface getUserInterface()
public static AbstractUserInterface getExtendedUserInterface()
public static EDatabase threadDatabase()
public EDatabase getDatabase()
public static void wantUpdateGui()
public static void updateNetworkErrors(Cell cell, java.util.List<ErrorLogger.MessageLog> errors)
public static void updateIncrementalDRCErrors(Cell cell, java.util.List<ErrorLogger.MessageLog> newErrors, java.util.List<ErrorLogger.MessageLog> delErrors)
public java.lang.String toString()
toString
in class java.lang.Object
public java.lang.String getInfo()
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |