Mon, 22 Dec 2014 14:02:46 -0800
Added tag jdk8u45-b02 for changeset 37b3ef9a0732
1 This document describes system properties that are used for internal
2 debugging and instrumentation purposes, along with the system loggers,
3 which are used for the same thing.
5 This document is intended as a developer resource, and it is not
6 needed as Nashorn documentation for normal usage. Flags and system
7 properties described herein are subject to change without notice.
9 =====================================
10 1. System properties used internally
11 =====================================
13 This documentation of the system property flags assume that the
14 default value of the flag is false, unless otherwise specified.
16 SYSTEM PROPERTY: -Dnashorn.args=<string>
18 This property takes as its value a space separated list of Nashorn
19 command line options that should be passed to Nashorn. This might be
20 useful in environments where it is hard to tell how a nashorn.jar is
21 launched.
23 Example:
25 > java -Dnashorn.args="--lazy-complation --log=compiler" large-java-app-with-nashorn.jar
26 > ant -Dnashorn.args="--log=codegen" antjob
28 SYSTEM PROPERTY: -Dnashorn.args.prepend=<string>
30 This property behaves like nashorn.args, but adds the given arguments
31 before the existing ones instead of after them. Later arguments will
32 overwrite earlier ones, so this is useful for setting default arguments
33 that can be overwritten.
36 SYSTEM PROPERTY: -Dnashorn.unstable.relink.threshold=x
38 This property controls how many call site misses are allowed before a
39 callsite is relinked with "apply" semantics to never change again.
40 In the case of megamorphic callsites, this is necessary, or the
41 program would spend all its time swapping out callsite targets. Dynalink
42 has a default value (currently 8 relinks) for this property if it
43 is not explicitly set.
46 SYSTEM PROPERTY: -Dnashorn.compiler.splitter.threshold=x
48 This will change the node weight that requires a subgraph of the IR to
49 be split into several classes in order not to run out of bytecode space.
50 The default value is 0x8000 (32768).
53 SYSTEM PROPERTY: -Dnashorn.serialize.compression=<x>
55 This property sets the compression level used when deflating serialized
56 AST structures of anonymous split functions. Valid values range from 0 to 9,
57 the default value is 4. Higher values will reduce memory size of serialized
58 AST but increase CPU usage required for compression.
61 SYSTEM PROPERTY: -Dnashorn.codegen.debug.trace=<x>
63 See the description of the codegen logger below.
66 SYSTEM PROPERTY: -Dnashorn.fields.objects
68 When this property is true, Nashorn will only use object fields for
69 AccessorProperties. This means that primitive values must be boxed
70 when stored in a field, which is significantly slower than using
71 primitive fields.
73 By default, Nashorn uses dual object and long fields. Ints are
74 represented as the 32 low bits of the long fields. Doubles are
75 represented as the doubleToLongBits of their value. This way a
76 single field can be used for all primitive types. Packing and
77 unpacking doubles to their bit representation is intrinsified by
78 the JVM and extremely fast.
80 In the future, this might complement or be replaced by experimental
81 feature sun.misc.TaggedArray, which has been discussed on the mlvm
82 mailing list. TaggedArrays are basically a way to share data space
83 between primitives and references, and have the GC understand this.
86 SYSTEM PROPERTY: -Dnashorn.compiler.symbol.trace=[<x>[,*]],
87 -Dnashorn.compiler.symbol.stacktrace=[<x>[,*]]
89 When this property is set, creation and manipulation of any symbol
90 named "x" will show information about when the compiler changes its
91 type assumption, bytecode local variable slot assignment and other
92 data. This is useful if, for example, a symbol shows up as an Object,
93 when you believe it should be a primitive. Usually there is an
94 explanation for this, for example that it exists in the global scope
95 and type analysis has to be more conservative.
97 Several symbols names to watch can be specified by comma separation.
99 If no variable name is specified (and no equals sign), all symbols
100 will be watched
102 By using "stacktrace" instead of or together with "trace", stack
103 traces will be displayed upon symbol changes according to the same
104 semantics.
107 SYSTEM PROPERTY: -Dnashorn.lexer.xmlliterals
109 If this property it set, it means that the Lexer should attempt to
110 parse XML literals, which would otherwise generate syntax
111 errors. Warning: there are currently no unit tests for this
112 functionality.
114 XML literals, when this is enabled, end up as standard LiteralNodes in
115 the IR.
118 SYSTEM_PROPERTY: -Dnashorn.debug
120 If this property is set to true, Nashorn runs in Debug mode. Debug
121 mode is slightly slower, as for example statistics counters are enabled
122 during the run. Debug mode makes available a NativeDebug instance
123 called "Debug" in the global space that can be used to print property
124 maps and layout for script objects, as well as a "dumpCounters" method
125 that will print the current values of the previously mentioned stats
126 counters.
128 These functions currently exists for Debug:
130 "map" - print(Debug.map(x)) will dump the PropertyMap for object x to
131 stdout (currently there also exist functions called "embedX", where X
132 is a value from 0 to 3, that will dump the contents of the embed pool
133 for the first spill properties in any script object and "spill", that
134 will dump the contents of the growing spill pool of spill properties
135 in any script object. This is of course subject to change without
136 notice, should we change the script object layout.
138 "methodHandle" - this method returns the method handle that is used
139 for invoking a particular script function.
141 "identical" - this method compares two script objects for reference
142 equality. It is a == Java comparison
144 "equals" - Returns true if two objects are either referentially
145 identical or equal as defined by java.lang.Object.equals.
147 "dumpCounters" - will dump the debug counters' current values to
148 stdout.
150 Currently we count number of ScriptObjects in the system, number of
151 Scope objects in the system, number of ScriptObject listeners added,
152 removed and dead (without references).
154 We also count number of ScriptFunctions, ScriptFunction invocations
155 and ScriptFunction allocations.
157 Furthermore we count PropertyMap statistics: how many property maps
158 exist, how many times were property maps cloned, how many times did
159 the property map history cache hit, prevent new allocations, how many
160 prototype invalidations were done, how many time the property map
161 proto cache hit.
163 Finally we count callsite misses on a per callsite bases, which occur
164 when a callsite has to be relinked, due to a previous assumption of
165 object layout being invalidated.
167 "getContext" - return the current Nashorn context.
169 "equalWithoutType" - Returns true if if the two objects are both
170 property maps, and they have identical properties in the same order,
171 but allows the properties to differ in their types.
173 "diffPropertyMaps" Returns a diagnostic string representing the difference
174 of two property maps.
176 "getClass" - Returns the Java class of an object, or undefined if null.
178 "toJavaString" - Returns the Java toString representation of an object.
180 "toIdentString" - Returns a string representation of an object consisting
181 of its java class name and hash code.
183 "getListenerCount" - Return the number of property listeners for a
184 script object.
186 "getEventQueueCapacity" - Get the capacity of the event queue.
188 "setEventQueueCapacity" - Set the event queue capacity.
190 "addRuntimeEvent" - Add a runtime event to the runtime event queue.
191 The queue has a fixed size (see -Dnashorn.runtime.event.queue.size)
192 and the oldest entry will be thrown out of the queue is about to overflow.
194 "expandEventQueueCapacity" - Expands the event queue capacity,
195 or truncates if capacity is lower than current capacity. Then only
196 the newest entries are kept.
198 "clearRuntimeEvents" - Clear the runtime event queue.
200 "removeRuntimeEvent" - Remove a specific runtime event from the event queue.
202 "getRuntimeEvents" - Return all runtime events in the queue as an array.
204 "getLastRuntimeEvent" - Return the last runtime event in the queue.
207 SYSTEM PROPERTY: -Dnashorn.methodhandles.debug.stacktrace
209 This enhances methodhandles logging (see below) to also dump the
210 stack trace for every instrumented method handle operation.
211 Warning: This is enormously verbose, but provides a pretty
212 decent "grep:able" picture of where the calls are coming from.
215 SYSTEM PROPERTY: -Dnashorn.cce
217 Setting this system property causes the Nashorn linker to rely on
218 ClassCastExceptions for triggering a callsite relink. If not set, the linker
219 will add an explicit instanceof guard.
222 SYSTEM PROPERTY: -Dnashorn.spill.threshold=<x>
224 This property sets the number of fields in an object from which to use
225 generic array based spill storage instead of Java fields. The default value
226 is 256.
229 SYSTEM PROPERTY: -Dnashorn.tcs.miss.samplePercent=<x>
231 When running with the trace callsite option (-tcs), Nashorn will count
232 and instrument any callsite misses that require relinking. As the
233 number of relinks is large and usually produces a lot of output, this
234 system property can be used to constrain the percentage of misses that
235 should be logged. Typically this is set to 1 or 5 (percent). 1% is the
236 default value.
238 SYSTEM PROPERTY: -Dnashorn.persistent.code.cache
240 This property can be used to set the directory where Nashorn stores
241 serialized script classes generated with the -pcc/--persistent-code-cache
242 option. The default directory name is "nashorn_code_cache".
245 SYSTEM PROPERTY: -Dnashorn.typeInfo.maxFiles
247 Maximum number of files to store in the type info cache. The type info cache
248 is used to cache type data of JavaScript functions when running with
249 optimistic types (-ot/--optimistic-types). There is one file per JavaScript
250 function in the cache.
252 The default value is 0 which means the feature is disabled. Setting this
253 to something like 20000 is probably good enough for most applications and
254 will usually cap the cache directory to about 80MB presuming a 4kB
255 filesystem allocation unit. Set this to "unlimited" to run without limit.
257 If the value is not 0 or "unlimited", Nashorn will spawn a cleanup thread
258 that makes sure the number of files in the cache does not exceed the given
259 value by deleting the least recently modified files.
262 SYSTEM PROPERTY: -Dnashorn.typeInfo.cacheDir
264 This property can be used to set the directory where Nashorn stores the
265 type info cache when -Dnashorn.typeInfo.maxFiles is set to a nonzero
266 value. The default location is platform specific. On Windows, it is
267 "${java.io.tmpdir}\com.oracle.java.NashornTypeInfo". On Linux and
268 Solaris it is "~/.cache/com.oracle.java.NashornTypeInfo". On Mac OS X,
269 it is "~/Library/Caches/com.oracle.java.NashornTypeInfo".
272 SYSTEM PROPERTY: -Dnashorn.typeInfo.cleanupDelaySeconds=<value>
274 This sets the delay between cleanups of the typeInfo cache, in seconds.
275 The default delay is 20 seconds.
278 SYSTEM PROPERTY: -Dnashorn.profilefile=<filename>
280 When running with the profile callsite options (-pcs), Nashorn will
281 dump profiling data for all callsites to stderr as a shutdown hook. To
282 instead redirect this to a file, specify the path to the file using
283 this system property.
286 SYSTEM_PROPERTY: -Dnashorn.regexp.impl=[jdk|joni]
288 This property defines the regular expression engine to be used by
289 Nashorn. Set this flag to "jdk" to get an implementation based on the
290 JDK's java.util.regex package. Set this property to "joni" to install
291 an implementation based on Joni, the regular expression engine used by
292 the JRuby project. The default value for this flag is "joni"
294 SYSTEM PROPERTY: -Dnashorn.runtime.event.queue.size=<value>
296 Nashorn provides a fixed sized runtime event queue for debugging purposes.
297 See -Dnashorn.debug for methods to access the event queue.
298 The default value is 1024.
300 ===============
301 2. The loggers.
302 ===============
304 It is very simple to create your own logger. Use the DebugLogger class
305 and give the subsystem name as a constructor argument.
307 The Nashorn loggers can be used to print per-module or per-subsystem
308 debug information with different levels of verbosity. The loggers for
309 a given subsystem are available are enabled by using
311 --log=<systemname>[:<level>]
313 on the command line.
315 Here <systemname> identifies the name of the subsystem to be logged
316 and the optional colon and level argument is a standard
317 java.util.logging.Level name (severe, warning, info, config, fine,
318 finer, finest). If the level is left out for a particular subsystem,
319 it defaults to "info". Any log message logged as the level or a level
320 that is more important will be output to stderr by the logger.
322 Several loggers can be enabled by a single command line option, by
323 putting a comma after each subsystem/level tuple (or each subsystem if
324 level is unspecified). The --log option can also be given multiple
325 times on the same command line, with the same effect.
327 For example: --log=codegen,fields:finest is equivalent to
328 --log=codegen:info --log=fields:finest
330 The following is an incomplete list of subsystems that currently
331 support logging. Look for classes implementing
332 jdk.nashorn.internal.runtime.logging.Loggable for more loggers.
335 * compiler
337 The compiler is in charge of turning source code and function nodes
338 into byte code, and installs the classes into a class loader
339 controlled from the Context. Log messages are, for example, about
340 things like new compile units being allocated. The compiler has global
341 settings that all the tiers of codegen (e.g. Lower and CodeGenerator)
342 use.s
345 * recompile
347 This logger shows information about recompilation of scripts and
348 functions at runtime. Recompilation may happen because a function
349 was called with different parameter types, or because an optimistic
350 assumption failed while executing a function with -ot/--optimistic-types.
353 * codegen
355 The code generator is the emitter stage of the code pipeline, and
356 turns the lowest tier of a FunctionNode into bytecode. Codegen logging
357 shows byte codes as they are being emitted, line number information
358 and jumps. It also shows the contents of the bytecode stack prior to
359 each instruction being emitted. This is a good debugging aid. For
360 example:
362 [codegen] #41 line:2 (f)_afc824e
363 [codegen] #42 load symbol x slot=2
364 [codegen] #43 {1:O} load int 0
365 [codegen] #44 {2:I O} dynamic_runtime_call GT:ZOI_I args=2 returnType=boolean
366 [codegen] #45 signature (Ljava/lang/Object;I)Z
367 [codegen] #46 {1:Z} ifeq ternary_false_5402fe28
368 [codegen] #47 load symbol x slot=2
369 [codegen] #48 {1:O} goto ternary_exit_107c1f2f
370 [codegen] #49 ternary_false_5402fe28
371 [codegen] #50 load symbol x slot=2
372 [codegen] #51 {1:O} convert object -> double
373 [codegen] #52 {1:D} neg
374 [codegen] #53 {1:D} convert double -> object
375 [codegen] #54 {1:O} ternary_exit_107c1f2f
376 [codegen] #55 {1:O} return object
378 shows a ternary node being generated for the sequence "return x > 0 ?
379 x : -x"
381 The first number on the log line is a unique monotonically increasing
382 emission id per bytecode. There is no guarantee this is the same id
383 between runs. depending on non deterministic code
384 execution/compilation, but for small applications it usually is. If
385 the system variable -Dnashorn.codegen.debug.trace=<x> is set, where x
386 is a bytecode emission id, a stack trace will be shown as the
387 particular bytecode is about to be emitted. This can be a quick way to
388 determine where it comes from without attaching the debugger. "Who
389 generated that neg?"
391 The --log=codegen option is equivalent to setting the system variable
392 "nashorn.codegen.debug" to true.
394 * fold
396 Shows constant folding taking place before lowering
398 * lower
400 This is the first lowering pass.
402 Lower is a code generation pass that turns high level IR nodes into
403 lower level one, for example substituting comparisons to RuntimeNodes
404 and inlining finally blocks.
406 Lower is also responsible for determining control flow information
407 like end points.
409 * symbols
411 The symbols logger tracks the assignment os symbols to identifiers.
413 * scopedepths
415 This logs the calculation of scope depths for non-local symbols.
417 * fields
419 The --log=fields option (at info level) is equivalent to setting the
420 system variable "nashorn.fields.debug" to true. At the info level it
421 will only show info about type assumptions that were invalidated. If
422 the level is set to finest, it will also trace every AccessorProperty
423 getter and setter in the program, show arguments, return values
424 etc. It will also show the internal representation of respective field
425 (Object in the normal case, unless running with the dual field
426 representation)
428 * time
430 This enables timers for various phases of script compilation. The timers
431 will be dumped when the Nashorn process exits. We see a percentage value
432 of how much time was spent not executing bytecode (i.e. compilation and
433 internal tasks) at the end of the report.
435 A finer level than "info" will show individual compilation timings as they
436 happen.
438 Here is an example:
440 [time] Accumulated complation phase Timings:
441 [time]
442 [time] 'JavaScript Parsing' 1076 ms
443 [time] 'Constant Folding' 159 ms
444 [time] 'Control Flow Lowering' 303 ms
445 [time] 'Program Point Calculation' 282 ms
446 [time] 'Builtin Replacement' 71 ms
447 [time] 'Code Splitting' 670 ms
448 [time] 'Symbol Assignment' 474 ms
449 [time] 'Scope Depth Computation' 249 ms
450 [time] 'Optimistic Type Assignment' 186 ms
451 [time] 'Local Variable Type Calculation' 526 ms
452 [time] 'Bytecode Generation' 5177 ms
453 [time] 'Class Installation' 1854 ms
454 [time]
455 [time] Total runtime: 11994 ms (Non-runtime: 11027 ms [91%])
457 * methodhandles
459 If this logger is enabled, each MethodHandle related call that uses
460 the java.lang.invoke package gets its MethodHandle intercepted and an
461 instrumentation printout of arguments and return value appended to
462 it. This shows exactly which method handles are executed and from
463 where. (Also MethodTypes and SwitchPoints).
465 * classcache
467 This logger shows information about reusing code classes using the
468 in-memory class cache. Nashorn will try to avoid compilation of
469 scripts by using existing classes. This can significantly improve
470 performance when repeatedly evaluating the same script.
472 =======================
473 3. Undocumented options
474 =======================
476 Here follows a short description of undocumented options for Nashorn.
477 To see a list of all undocumented options, use the (undocumented) flag
478 "-xhelp".
480 i.e. jjs -xhelp or java -jar nashorn.jar -xhelp
482 Undocumented options are not guaranteed to work, run correctly or be
483 bug free. They are experimental and for internal or debugging use.
484 They are also subject to change without notice.
486 In practice, though, all options below not explicitly documented as
487 EXPERIMENTAL can be relied upon, for example --dump-on-error is useful
488 for any JavaScript/Nashorn developer, but there is no guarantee.
490 A short summary follows:
492 -D (-Dname=value. Set a system property. This option can be repeated.)
494 -ccs, --class-cache-size (Size of the Class cache size per global scope.)
496 -cp, -classpath (-cp path. Specify where to find user class files.)
498 -co, --compile-only (Compile without running.)
499 param: [true|false] default: false
501 -d, --dump-debug-dir (specify a destination directory to dump class files.)
502 param: <path>
504 --debug-lines (Generate line number table in .class files.)
505 param: [true|false] default: true
507 --debug-locals (Generate local variable table in .class files.)
508 param: [true|false] default: false
510 -doe, -dump-on-error (Dump a stack trace on errors.)
511 param: [true|false] default: false
513 --early-lvalue-error (invalid lvalue expressions should be reported as early errors.)
514 param: [true|false] default: true
516 --empty-statements (Preserve empty statements in AST.)
517 param: [true|false] default: false
519 -fv, -fullversion (Print full version info of Nashorn.)
520 param: [true|false] default: false
522 --function-statement-error (Report an error when function declaration is used as a statement.)
523 param: [true|false] default: false
525 --function-statement-warning (Warn when function declaration is used as a statement.)
526 param: [true|false] default: false
528 -fx (Launch script as an fx application.)
529 param: [true|false] default: false
531 --global-per-engine (Use single Global instance per script engine instance.)
532 param: [true|false] default: false
534 -h, -help (Print help for command line flags.)
535 param: [true|false] default: false
537 --loader-per-compile (Create a new class loader per compile.)
538 param: [true|false] default: true
540 -l, --locale (Set Locale for script execution.)
541 param: <locale> default: en-US
543 --log (Enable logging of a given level for a given number of sub systems.
544 [for example: --log=fields:finest,codegen:info].)
545 param: <module:level>,*
547 -nj, --no-java (Disable Java support.)
548 param: [true|false] default: false
550 -nse, --no-syntax-extensions (Disallow non-standard syntax extensions.)
551 param: [true|false] default: false
553 -nta, --no-typed-arrays (Disable typed arrays support.)
554 param: [true|false] default: false
556 --parse-only (Parse without compiling.)
557 param: [true|false] default: false
559 --print-ast (Print abstract syntax tree.)
560 param: [true|false] default: false
562 -pc, --print-code (Print generated bytecode. If a directory is specified, nothing will
563 be dumped to stderr. Also, in that case, .dot files will be generated
564 for all functions or for the function with the specified name only.)
565 param: [dir:<output-dir>,function:<name>]
567 --print-lower-ast (Print lowered abstract syntax tree.)
568 param: [true|false] default: false
570 -plp, --print-lower-parse (Print the parse tree after lowering.)
571 param: [true|false] default: false
573 --print-mem-usage (Print memory usage of IR after each compile stage.)
574 param: [true|false] default: false
576 --print-no-newline (Print function will not print new line char.)
577 param: [true|false] default: false
579 -pp, --print-parse (Print the parse tree.)
580 param: [true|false] default: false
582 --print-symbols (Print the symbol table.)
583 param: [true|false] default: false
585 -pcs, --profile-callsites (Dump callsite profile data.)
586 param: [true|false] default: false
588 -scripting (Enable scripting features.)
589 param: [true|false] default: false
591 --stderr (Redirect stderr to a filename or to another tty, e.g. stdout.)
592 param: <output console>
594 --stdout (Redirect stdout to a filename or to another tty, e.g. stderr.)
595 param: <output console>
597 -strict (Run scripts in strict mode.)
598 param: [true|false] default: false
600 -t, -timezone (Set timezone for script execution.)
601 param: <timezone> default: Europe/Stockholm
603 -tcs, --trace-callsites (Enable callsite trace mode. Options are: miss [trace callsite misses]
604 enterexit [trace callsite enter/exit], objects [print object properties].)
605 param: [=[option,]*]
607 --verify-code (Verify byte code before running.)
608 param: [true|false] default: false
610 -v, -version (Print version info of Nashorn.)
611 param: [true|false] default: false
613 -xhelp (Print extended help for command line flags.)
614 param: [true|false] default: false