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