public class ScanDriver
extends java.lang.Object
AstGenerator
for
the majority of its function. Preprocessing output will be cached and
reused as long as the cache file is newer than the input file. This
significantly reduces the runtime of a multi-file scan. All files are
parsed each time (there is no reuse of parser output) and the output
is saved into one of more possible outputs (based on user controlled
options):
This program provides a command line interface. See main(java.lang.String[])
for the
syntax.
The scan is performed across multiple threads to reduce execution time. The API
allows for a fixed number of threads to be specified. If 0 threads are specified,
the scan driver will use one thread per available processor, as reported by
Runtime.getRuntime().availableProcessors()
.
Important Note Regarding Multi-threading
In order to preserve the order of filenames written to the console, the writing of these names
is deferred until all the processing of a file, and of all those files submitted for processing
before it, has finished. This preserves the order of output of those filenames. However, since
most errors and warnings are written to stderr directly from the code which handles them, error
and warning information will display to the console before the name of the affected
file.
When running with a thread pool of size 1, the above does not apply. In this case, we enter a stricter mode which forces the filename to appear before any messages associated with it. This mode is particularly useful in the early stages of a conversion project, when working through unstable or unknown code which is likely to produce errors or warnings. Using a single thread naturally preserves the original order of the filenames.
When running with a thread pool larger than 1, the filename will appear below any messages as noted above, but not necessarily immediately below. Several filenames and/or messages may be written before the filename associated with the messages. Furthermore, the messages themselves are not guaranteed to be written completely to stderr from one thread before another thread interrupts with messages of its own. Therefore, it is best to use multiple threads only once a source code set has stabilized and no longer produces errors and warnings during the scan phase.
TODO: to fix this, we must overhaul the way error handling is performed by the classes invoked by this class.
Constructor and Description |
---|
ScanDriver() |
Modifier and Type | Method and Description |
---|---|
static void |
main(java.lang.String[] args)
Provides a command line interface for an end user to drive the
scanning harness.
|
static void |
scan(FileList files,
boolean silent)
Drive the scanning process for each of the given files in the list,
with preprocessing activated and caching of all output (preprocessor,
lexer, parser), persistence of ASTs and no registry rebuild.
|
static void |
scan(FileList files,
boolean preproc,
boolean cache,
boolean lex,
boolean parse,
boolean persist,
boolean silent,
boolean abortOnError,
int threads)
Drive the scanning process for each of the given files in the list,
honoring the caching and output options provided.
|
static void |
scan(FileList files,
boolean silent,
boolean abortOnError,
int threads)
Drive the scanning process for each of the given files in the list,
with preprocessing activated and caching of all output (preprocessor,
lexer, parser), persistence of ASTs and no registry rebuild.
|
private static void |
syntax(java.lang.String msg,
int rc)
Emit a syntax statement and optional error message to
stderr , then exit the process with the specified return
code. |
public static void scan(FileList files, boolean silent) throws java.lang.Exception
files
- The list of files. Must not be null
.silent
- false
if screen (stdout) output should be done.
If true
, normal screen output is suppressed and
the only output occurs on failures (this is written to
stderr).java.lang.Exception
- in the event abortOnError
is true and a failure occurs.public static void scan(FileList files, boolean silent, boolean abortOnError, int threads) throws java.lang.Exception
files
- The list of files. Must not be null
.silent
- false
if screen (stdout) output should be done.
If true
, normal screen output is suppressed and
the only output occurs on failures (this is written to
stderr).abortOnError
- true
to end the scanning run if an error is encountered,
else false
.threads
- Number of threads to use for the scan. A non-positive value will enable
the default behavior of a fixed size thread pool with one thread per
available CPU. A positive value will create a fixed size thread pool of
the given size.java.lang.Exception
- in the event abortOnError
is true and a failure occurs.public static void scan(FileList files, boolean preproc, boolean cache, boolean lex, boolean parse, boolean persist, boolean silent, boolean abortOnError, int threads) throws java.lang.Exception
files
- The list of files. Must not be null
.preproc
- true
if the preprocessor should be run.cache
- true
if the preprocessor output should be saved persistently.lex
- true
if the lexer output should be saved persistently.parse
- true
if the parser output should be saved persistently.persist
- true
if the resulting AST files should be saved persistently.silent
- false
if screen (stdout) output should be done.
If true
, normal screen output is suppressed and
the only output occurs on failures (this is written to stderr).abortOnError
- true
to end the scanning run if an error is encountered,
else false
.threads
- Number of threads to use for the scan. A value of zero will enable the
default behavior of a fixed size thread pool with one thread per available
CPU. A positive value will create a fixed size thread pool of the given
size.java.lang.Exception
- in the event abortOnError
is true and a failure occurs.private static void syntax(java.lang.String msg, int rc)
stderr
, then exit the process with the specified return
code. This method is called from main(java.lang.String[])
when the user passes
command line parameters which are not viable.msg
- Optional error message; may be null
.rc
- Process return code used with System.exit()
.public static void main(java.lang.String[] args)
Syntax:
java ScanDriver [-QCLPXSANR] <directory> <"filespec"> java ScanDriver -F[QCLPXSA] <"filelist">Where:
By default, options QCLPX are active. If any options are explicitly specified, all non-specified options are forced off.
args
- List of command line arguments.