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