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