com.sun.electric.tool
Class Job

java.lang.Object
  extended by com.sun.electric.tool.Job
All Implemented Interfaces:
java.io.Serializable
Direct Known Subclasses:
AddCellJob, AddFlagAnnotationJob, AddLibraryJob, AddRemove.AddRemoveJob, AddRemove.UndoAddRemoveJob, AllSchemNamesToLay.RenameJob, AnnularRing.MakeAnnulus, CancelCheckOutJob, CellChangeJobs.DeleteCell, CellChangeJobs.DeleteCellGroup, CellChangeJobs.DeleteManyCells, CellChangeJobs.DuplicateCell, CellChangeJobs.ExtractCellInstances, CellChangeJobs.GraphCells, CellChangeJobs.NewCellVersion, CellChangeJobs.PackageCell, CellChangeJobs.RenameCell, CellChangeJobs.RenameCellGroup, CellMenu.DeleteMultiPageJob, CellMenu.SetMultiPageJob, CheckInJob, CheckOutJob, CircuitChangeJobs.AlignNodes, CircuitChangeJobs.AlignObjects, CircuitChangeJobs.ChangeArcProperties, CircuitChangeJobs.CheckAndRepairJob, CircuitChangeJobs.CleanupChanges, CircuitChangeJobs.ClearCellLocked, CircuitChangeJobs.ClearNodeLocked, CircuitChangeJobs.DeleteArcs, CircuitChangeJobs.DeleteSelected, CircuitChangeJobs.DeleteSelectedGeometry, CircuitChangeJobs.ManyMove, CircuitChangeJobs.ReloadLibraryJob, CircuitChangeJobs.RenameLibrary, CircuitChangeJobs.RenameTechnology, CircuitChangeJobs.RipTheBus, CircuitChangeJobs.RotateSelected, CircuitChangeJobs.ShortenArcs, CircuitChangeJobs.ToggleNegationJob, CrossLibCopy.CrossLibraryCopyJob, DeleteCellJob, DRC.CheckDRCJob, Edit.EditConsistencyCheckJob, Edit.ListEditorsJob, Edit.MarkForEditJob, ExportChanges.FollowExport, ExportChanges.ReExportPorts, ExportChanges.RenumberNumericExports, FileMenu.ClearCellDate, FileMenu.ImportLibrary, FileMenu.QuitJob, FileMenu.ReadLibrary, FileMenu.SaveAllLibrariesInFormatJob, FillGenJob, FlagJob, FlagLibraryCheckerJob, GateLayoutGenerator.GenerateFromSchematicsJob, GateRegression, J3DClientApp, LETool.AnalyzeCell, LETool.ClearStoredSizes, LETool.ClearStoredSizesLibrary, Log.RevertToVersion, MultiTaskJob, NccJob, Output.OutputCellInfo, Output.WriteJELIB, PaletteFrame.PlaceNewNode, ProjSettings.ImportSettingsJob, Router.CreateRouteJob, SchemNamesToLay.RenameJob, SkewTreeJob, StitchFillJob, Undo.UndoJob, UniversalJob, UpdateJob, ViewChanges.CreateAndViewCell

public abstract class Job
extends java.lang.Object
implements java.io.Serializable

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.

Author:
gainsley
See Also:
Serialized Form

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

BATCHMODE

public static boolean BATCHMODE

LOCALDEBUGFLAG

public static boolean LOCALDEBUGFLAG

startTime

protected long startTime
job start time


endTime

protected long endTime
job end time

Constructor Detail

Job

public Job(java.lang.String jobName,
           Tool tool,
           Job.Type jobType,
           Cell upCell,
           Cell downCell,
           Job.Priority priority)
Constructor creates a new instance of Job.

Parameters:
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

getDebug

public static boolean getDebug()
Method to tell whether Electric is running in "debug" mode. If the program is started with the "-debug" switch, debug mode is enabled.

Returns:
true if running in debug mode.

setDebug

public static void setDebug(boolean f)

setThreadMode

public static void setThreadMode(Job.Mode mode,
                                 AbstractUserInterface userInterface)

initJobManager

public static void initJobManager(int numThreads,
                                  Job initDatabaseJob,
                                  java.lang.Object mode,
                                  java.lang.String serverMachineName)

getRunMode

public static Job.Mode getRunMode()

getNumThreads

public static int getNumThreads()

startJob

public void startJob()
Start a job. By default displays Job on Job List UI, and delete Job when done. Jobs that have state the user would like to use after the Job finishes (like DRC, NCC, etc) should call startJob(true, true).


startJobOnMyResult

public void startJobOnMyResult()
Start a job on snapshot obtained at the end of current job. By default displays Job on Job List UI, and delete Job when done.


startJob

public void startJob(boolean display,
                     boolean deleteWhenDone)
Start the job by placing it on the JobThread queue. If 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)

Parameters:
deleteWhenDone - delete when job is done if true, otherwise leave it around

fieldVariableChanged

protected void fieldVariableChanged(java.lang.String variableName)
Method to remember that a field variable of the Job has been changed by the doIt() method.

Parameters:
variableName - the name of the variable that changed.

doIt

public abstract boolean doIt()
                      throws JobException
This is the main work method. This method should perform all needed tasks.

Throws:
JobException - TODO

terminateIt

public void terminateIt(java.lang.Throwable jobException)
This method executes in the Client side after termination of doIt method. This method should perform all needed termination actions.

Parameters:
jobException - null if doIt terminated normally, otherwise exception thrown by doIt.

terminateOK

public void terminateOK()
This method executes in the Client side after normal termination of doIt method. This method should perform all needed termination actions.


terminateFail

public void terminateFail(java.lang.Throwable jobException)
This method executes in the Client side after exceptional termination of doIt method.

Parameters:
jobException - null exception thrown by doIt.

setReportExecutionFlag

protected void setReportExecutionFlag(boolean flag)
Set reportExecution flag on/off


setProgress

protected void setProgress(java.lang.String progress)

isFinished

public boolean isFinished()
Return run status


abort

public void abort()
Tell thread to abort. Extending class should check abort when/where applicable


getScheduledToAbort

protected boolean getScheduledToAbort()
get scheduled to abort status


getDisplay

public boolean getDisplay()
get display status


getDeleteWhenDone

public boolean getDeleteWhenDone()
get deleteWhenDone status


checkAbort

public boolean checkAbort()
Check if we are scheduled to abort. If so, print msg if non null and return true. This is because setAbort and getScheduledToAbort are protected in Job.

Returns:
true on abort, false otherwise. If job is scheduled for abort or aborted. and it will report it to std output

getAllJobs

public static java.util.Iterator<Job> getAllJobs()
get all jobs iterator


getRunningJob

public static Job getRunningJob()
If this current thread is a EThread running a Job return the Job. Return null otherwise.

Returns:
a running Job or null

getStatus

public java.lang.String getStatus()
get status


remove

public boolean remove()
Remove job from Job list if it is done


acquireExamineLock

public 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. The suggested format is as follows:


 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.

Parameters:
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.
Returns:
true if lock acquired, false otherwise. If block is true, the return value is always true.
See Also:
releaseExamineLock(), invokeExamineLater(Runnable, Object)

releaseExamineLock

public static void releaseExamineLock()
Release the lock to examine the database. The lock is the lock associated with the current thread. This should only be called if a lock was acquired for the current thread.

See Also:
acquireExamineLock(boolean), invokeExamineLater(Runnable, Object)

invokeExamineLater

public 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. In this case the GUI can call invokeExamineLater to have the specified SwingExamineTask run in the context of the swing thread where it will be *guaranteed* that it will be able to acquire an Examine Lock via acquireExamineLock().

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).

Parameters:
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.
See Also:
for a common pattern using this method, acquireExamineLock(boolean), releaseExamineLock()

getUserInterface

public static UserInterface getUserInterface()

getExtendedUserInterface

public static AbstractUserInterface getExtendedUserInterface()
Low-level method.


threadDatabase

public static EDatabase threadDatabase()

getDatabase

public EDatabase getDatabase()

wantUpdateGui

public static void wantUpdateGui()

updateNetworkErrors

public static void updateNetworkErrors(Cell cell,
                                       java.util.List<ErrorLogger.MessageLog> errors)

updateIncrementalDRCErrors

public static void updateIncrementalDRCErrors(Cell cell,
                                              java.util.List<ErrorLogger.MessageLog> newErrors,
                                              java.util.List<ErrorLogger.MessageLog> delErrors)

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

getInfo

public java.lang.String getInfo()
Get info on Job