DEVELOPER_README revision 525:eb7b8340ce3a
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.unstable.relink.threshold=x 29 30This property controls how many call site misses are allowed before a 31callsite is relinked with "apply" semantics to never change again. 32In the case of megamorphic callsites, this is necessary, or the 33program would spend all its time swapping out callsite targets. Dynalink 34has a default value (currently 8 relinks) for this property if it 35is not explicitly set. 36 37 38SYSTEM PROPERTY: -Dnashorn.compiler.splitter.threshold=x 39 40This will change the node weight that requires a subgraph of the IR to 41be split into several classes in order not to run out of bytecode space. 42The default value is 0x8000 (32768). 43 44 45SYSTEM PROPERTY: -Dnashorn.compiler.intarithmetic 46 47(and integer arithmetic in general) 48 49<currently disabled - this is being refactored for update releases> 50 51Arithmetic operations in Nashorn (except bitwise ones) typically 52coerce the operands to doubles (as per the JavaScript spec). To switch 53this off and remain in integer mode, for example for "var x = a&b; var 54y = c&d; var z = x*y;", use this flag. This will force the 55multiplication of variables that are ints to be done with the IMUL 56bytecode and the result "z" to become an int. 57 58WARNING: Note that is is experimental only to ensure that type support 59exists for all primitive types. The generated code is unsound. This 60will be the case until we do optimizations based on it. There is a CR 61in Nashorn to do better range analysis, and ensure that this is only 62done where the operation can't overflow into a wider type. Currently 63no overflow checking is done, so at the moment, until range analysis 64has been completed, this option is turned off. 65 66We've experimented by using int arithmetic for everything and putting 67overflow checks afterwards, which would recompute the operation with 68the correct precision, but have yet to find a configuration where this 69is faster than just using doubles directly, even if the int operation 70does not overflow. Getting access to a JVM intrinsic that does branch 71on overflow would probably alleviate this. 72 73The future: 74 75We are transitioning to an optimistic type system that uses int 76arithmetic everywhere until proven wrong. The problem here is mostly 77catch an overflow exception and rolling back the state to a new method 78with less optimistic assumptions for an operation at a particular 79program point. This will most likely not be in the Java 8.0 release 80but likely end up in an update release 81 82For Java 8, several java.lang.Math methods like addExact, subExact and 83mulExact are available to help us. Experiments intrinsifying these 84show a lot of promise, and we have devised a system that basically 85does on stack replacement with exceptions in bytecode to revert 86erroneous assumptions. An explanation of how this works and what we 87are doing can be found here: 88http://www.slideshare.net/lagergren/lagergren-jvmls2013final 89 90Experiments with this show significant ~x2-3 performance increases on 91pretty much everything, provided that optimistic assumptions don't 92fail much. It will affect warmup time negatively, depending on how 93many erroneous too optimistic assumptions are placed in the code at 94compile time. We don't think this will be much of an issue. 95 96For example for a small benchmark that repeatedly executes this 97method taken from the Crypto Octane benchmark 98 99function am3(i,x,w,j,c,n) { 100 var this_array = this.array; 101 var w_array = w.array; 102 var xl = x&0x3fff, xh = x>>14; 103 while(--n >= 0) { 104 var l = this_array[i]&0x3fff; 105 var h = this_array[i++]>>14; 106 var m = xh*l+h*xl; 107 l = xl*l+((m&0x3fff)<<14)+w_array[j]+c; 108 c = (l>>28)+(m>>14)+xh*h; 109 w_array[j++] = l&0xfffffff; 110 } 111 112 return c; 113} 114 115The performance increase more than doubles. We are also working hard 116with the code generation team in the Java Virtual Machine to fix 117things that are lacking in invokedynamic performance, which is another 118area where a lot of ongoing performance work takes place 119 120"Pessimistic" bytecode for am3, guaranteed to be semantically correct: 121 122// access flags 0x9 123 public static am3(Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object; 124 L0 125 LINENUMBER 12 L0 126 ALOAD 0 127 INVOKEDYNAMIC dyn:getProp|getElem|getMethod:array(Ljava/lang/Object;)Ljava/lang/Object; [ 128 // handle kind 0x6 : INVOKESTATIC 129 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 130 // arguments: 131 0 132 ] 133 ASTORE 8 134 L1 135 LINENUMBER 13 L1 136 ALOAD 3 137 INVOKEDYNAMIC dyn:getProp|getElem|getMethod:array(Ljava/lang/Object;)Ljava/lang/Object; [ 138 // handle kind 0x6 : INVOKESTATIC 139 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 140 // arguments: 141 0 142 ] 143 ASTORE 9 144 L2 145 LINENUMBER 14 L2 146 ALOAD 2 147 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toInt32 (Ljava/lang/Object;)I 148 SIPUSH 16383 149 IAND 150 ISTORE 10 151 ALOAD 2 152 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toInt32 (Ljava/lang/Object;)I 153 BIPUSH 14 154 ISHR 155 ISTORE 11 156 L3 157 LINENUMBER 15 L3 158 GOTO L4 159 L5 160 LINENUMBER 16 L5 161 FRAME FULL [java/lang/Object java/lang/Object java/lang/Object java/lang/Object java/lang/Object java/lang/Object java/lang/Double T java/lang/Object java/lang/Object I I] [] 162 ALOAD 8 163 ALOAD 1 164 INVOKEDYNAMIC dyn:getElem|getProp|getMethod(Ljava/lang/Object;Ljava/lang/Object;)I [ 165 // handle kind 0x6 : INVOKESTATIC 166 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 167 // arguments: 168 0 169 ] 170 SIPUSH 16383 171 IAND 172 INVOKESTATIC java/lang/Integer.valueOf (I)Ljava/lang/Integer; 173 ASTORE 12 174 L6 175 LINENUMBER 17 L6 176 ALOAD 8 177 ALOAD 1 178 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toNumber (Ljava/lang/Object;)D 179 DUP2 180 DCONST_1 181 DADD 182 INVOKESTATIC java/lang/Double.valueOf (D)Ljava/lang/Double; 183 ASTORE 1 184 INVOKEDYNAMIC dyn:getElem|getProp|getMethod(Ljava/lang/Object;D)I [ 185 // handle kind 0x6 : INVOKESTATIC 186 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 187 // arguments: 188 0 189 ] 190 BIPUSH 14 191 ISHR 192 ISTORE 13 193 L7 194 LINENUMBER 18 L7 195 ILOAD 11 196 I2D 197 ALOAD 12 198 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toNumber (Ljava/lang/Object;)D 199 DMUL 200 ILOAD 13 201 I2D 202 ILOAD 10 203 I2D 204 DMUL 205 DADD 206 DSTORE 14 207 L8 208 LINENUMBER 19 L8 209 ILOAD 10 210 I2D 211 ALOAD 12 212 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toNumber (Ljava/lang/Object;)D 213 DMUL 214 DLOAD 14 215 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toInt32 (D)I 216 SIPUSH 16383 217 IAND 218 BIPUSH 14 219 ISHL 220 I2D 221 DADD 222 ALOAD 9 223 ALOAD 4 224 INVOKEDYNAMIC dyn:getElem|getProp|getMethod(Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object; [ 225 // handle kind 0x6 : INVOKESTATIC 226 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 227 // arguments: 228 0 229 ] 230 INVOKEDYNAMIC ADD:ODO_D(DLjava/lang/Object;)Ljava/lang/Object; [ 231 // handle kind 0x6 : INVOKESTATIC 232 jdk/nashorn/internal/runtime/linker/Bootstrap.runtimeBootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;)Ljava/lang/invoke/CallSite;) 233 // arguments: none 234 ] 235 ALOAD 5 236 INVOKEDYNAMIC ADD:OOO_I(Ljava/lang/Object;Ljava/lang/Object;)Ljava/lang/Object; [ 237 // handle kind 0x6 : INVOKESTATIC 238 jdk/nashorn/internal/runtime/linker/Bootstrap.runtimeBootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;)Ljava/lang/invoke/CallSite;) 239 // arguments: none 240 ] 241 ASTORE 12 242 L9 243 LINENUMBER 20 L9 244 ALOAD 12 245 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toInt32 (Ljava/lang/Object;)I 246 BIPUSH 28 247 ISHR 248 I2D 249 DLOAD 14 250 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toInt32 (D)I 251 BIPUSH 14 252 ISHR 253 I2D 254 DADD 255 ILOAD 11 256 I2D 257 ILOAD 13 258 I2D 259 DMUL 260 DADD 261 INVOKESTATIC java/lang/Double.valueOf (D)Ljava/lang/Double; 262 ASTORE 5 263 L10 264 LINENUMBER 21 L10 265 ALOAD 9 266 ALOAD 4 267 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toNumber (Ljava/lang/Object;)D 268 DUP2 269 DCONST_1 270 DADD 271 INVOKESTATIC java/lang/Double.valueOf (D)Ljava/lang/Double; 272 ASTORE 4 273 ALOAD 12 274 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toInt32 (Ljava/lang/Object;)I 275 LDC 268435455 276 IAND 277 INVOKEDYNAMIC dyn:setElem|setProp(Ljava/lang/Object;DI)V [ 278 // handle kind 0x6 : INVOKESTATIC 279 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 280 // arguments: 281 0 282 ] 283 L4 284 FRAME FULL [java/lang/Object java/lang/Object java/lang/Object java/lang/Object java/lang/Object java/lang/Object java/lang/Object T java/lang/Object java/lang/Object I I] [] 285 ALOAD 6 286 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.toNumber (Ljava/lang/Object;)D 287 LDC -1.0 288 DADD 289 DUP2 290 INVOKESTATIC java/lang/Double.valueOf (D)Ljava/lang/Double; 291 ASTORE 6 292 DCONST_0 293 DCMPL 294 IFGE L5 295 L11 296 LINENUMBER 24 L11 297 ALOAD 5 298 ARETURN 299 300"Optimistic" bytecode that requires invalidation on e.g overflow. Factor 301x2-3 speedup: 302 303public static am3(Ljava/lang/Object;IILjava/lang/Object;III)I 304 L0 305 LINENUMBER 12 L0 306 ALOAD 0 307 INVOKEDYNAMIC dyn:getProp|getElem|getMethod:array(Ljava/lang/Object;)Ljava/lang/Object; [ 308 // handle kind 0x6 : INVOKESTATIC 309 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 310 // arguments: 311 0 312 ] 313 ASTORE 8 314 L1 315 LINENUMBER 13 L1 316 ALOAD 3 317 INVOKEDYNAMIC dyn:getProp|getElem|getMethod:array(Ljava/lang/Object;)Ljava/lang/Object; [ 318 // handle kind 0x6 : INVOKESTATIC 319 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 320 // arguments: 321 0 322 ] 323 ASTORE 9 324 L2 325 LINENUMBER 14 L2 326 ILOAD 2 327 SIPUSH 16383 328 IAND 329 ISTORE 10 330 ILOAD 2 331 BIPUSH 14 332 ISHR 333 ISTORE 11 334 L3 335 LINENUMBER 15 L3 336 GOTO L4 337 L5 338 LINENUMBER 16 L5 339 FRAME FULL [java/lang/Object I I java/lang/Object I I I T java/lang/Object java/lang/Object I I] [] 340 ALOAD 8 341 ILOAD 1 342 INVOKEDYNAMIC dyn:getElem|getProp|getMethod(Ljava/lang/Object;I)I [ 343 // handle kind 0x6 : INVOKESTATIC 344 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 345 // arguments: 346 0 347 ] 348 SIPUSH 16383 349 IAND 350 ISTORE 12 351 L6 352 LINENUMBER 17 L6 353 ALOAD 8 354 ILOAD 1 355 DUP 356 ICONST_1 357 IADD 358 ISTORE 1 359 INVOKEDYNAMIC dyn:getElem|getProp|getMethod(Ljava/lang/Object;I)I [ 360 // handle kind 0x6 : INVOKESTATIC 361 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 362 // arguments: 363 0 364 ] 365 BIPUSH 14 366 ISHR 367 ISTORE 13 368 L7 369 LINENUMBER 18 L7 370 ILOAD 11 371 ILOAD 12 372 BIPUSH 8 373 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.mulExact (III)I 374 ILOAD 13 375 ILOAD 10 376 BIPUSH 9 377 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.mulExact (III)I 378 IADD 379 ISTORE 14 380 L8 381 LINENUMBER 19 L8 382 ILOAD 10 383 ILOAD 12 384 BIPUSH 11 385 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.mulExact (III)I 386 ILOAD 14 387 SIPUSH 16383 388 IAND 389 BIPUSH 14 390 ISHL 391 IADD 392 ALOAD 9 393 ILOAD 4 394 INVOKEDYNAMIC dyn:getElem|getProp|getMethod(Ljava/lang/Object;I)I [ 395 // handle kind 0x6 : INVOKESTATIC 396 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 397 // arguments: 398 0 399 ] 400 IADD 401 ILOAD 5 402 IADD 403 ISTORE 12 404 L9 405 LINENUMBER 20 L9 406 ILOAD 12 407 BIPUSH 28 408 ISHR 409 ILOAD 14 410 BIPUSH 14 411 ISHR 412 IADD 413 ILOAD 11 414 ILOAD 13 415 BIPUSH 21 416 INVOKESTATIC jdk/nashorn/internal/runtime/JSType.mulExact (III)I 417 IADD 418 ISTORE 5 419 L10 420 LINENUMBER 21 L10 421 ALOAD 9 422 ILOAD 4 423 DUP 424 ICONST_1 425 IADD 426 ISTORE 4 427 ILOAD 12 428 LDC 268435455 429 IAND 430 INVOKEDYNAMIC dyn:setElem|setProp(Ljava/lang/Object;II)V [ 431 // handle kind 0x6 : INVOKESTATIC 432 jdk/nashorn/internal/runtime/linker/Bootstrap.bootstrap((Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;I)Ljava/lang/invoke/CallSite;) 433 // arguments: 434 0 435 ] 436 L4 437 FRAME SAME 438 ILOAD 6 439 ICONST_M1 440 IADD 441 DUP 442 ISTORE 6 443 ICONST_0 444 IF_ICMPGE L5 445 L11 446 LINENUMBER 24 L11 447 ILOAD 5 448 IRETURN 449 450 451SYSTEM PROPERTY: -Dnashorn.codegen.debug, -Dnashorn.codegen.debug.trace=<x> 452 453See the description of the codegen logger below. 454 455 456SYSTEM_PROPERTY: -Dnashorn.fields.debug 457 458See the description on the fields logger below. 459 460 461SYSTEM PROPERTY: -Dnashorn.fields.dual 462 463When this property is true, Nashorn will attempt to use primitive 464fields for AccessorProperties (currently just AccessorProperties, not 465spill properties). Memory footprint for script objects will increase, 466as we need to maintain both a primitive field (a long) as well as an 467Object field for the property value. Ints are represented as the 32 468low bits of the long fields. Doubles are represented as the 469doubleToLongBits of their value. This way a single field can be used 470for all primitive types. Packing and unpacking doubles to their bit 471representation is intrinsified by the JVM and extremely fast. 472 473While dual fields in theory runs significantly faster than Object 474fields due to reduction of boxing and memory allocation overhead, 475there is still work to be done to make this a general purpose 476solution. Research is ongoing. 477 478In the future, this might complement or be replaced by experimental 479feature sun.misc.TaggedArray, which has been discussed on the mlvm 480mailing list. TaggedArrays are basically a way to share data space 481between primitives and references, and have the GC understand this. 482 483As long as only primitive values are written to the fields and enough 484type information exists to make sure that any reads don't have to be 485uselessly boxed and unboxed, this is significantly faster than the 486standard "Objects only" approach that currently is the default. See 487test/examples/dual-fields-micro.js for an example that runs twice as 488fast with dual fields as without them. Here, the compiler, can 489determine that we are dealing with numbers only throughout the entire 490property life span of the properties involved. 491 492If a "real" object (not a boxed primitive) is written to a field that 493has a primitive representation, its callsite is relinked and an Object 494field is used forevermore for that particular field in that 495PropertyMap and its children, even if primitives are later assigned to 496it. 497 498As the amount of compile time type information is very small in a 499dynamic language like JavaScript, it is frequently the case that 500something has to be treated as an object, because we don't know any 501better. In reality though, it is often a boxed primitive is stored to 502an AccessorProperty. The fastest way to handle this soundly is to use 503a callsite typecheck and avoid blowing the field up to an Object. We 504never revert object fields to primitives. Ping-pong:ing back and forth 505between primitive representation and Object representation would cause 506fatal performance overhead, so this is not an option. 507 508For a general application the dual fields approach is still slower 509than objects only fields in some places, about the same in most cases, 510and significantly faster in very few. This is due the program using 511primitives, but we still can't prove it. For example "local_var a = 512call(); field = a;" may very well write a double to the field, but the 513compiler dare not guess a double type if field is a local variable, 514due to bytecode variables being strongly typed and later non 515interchangeable. To get around this, the entire method would have to 516be replaced and a continuation retained to restart from. We believe 517that the next steps we should go through are instead: 518 5191) Implement method specialization based on callsite, as it's quite 520frequently the case that numbers are passed around, but currently our 521function nodes just have object types visible to the compiler. For 522example "var b = 17; func(a,b,17)" is an example where two parameters 523can be specialized, but the main version of func might also be called 524from another callsite with func(x,y,"string"). 525 5262) This requires lazy jitting as the functions have to be specialized 527per callsite. 528 529Even though "function square(x) { return x*x }" might look like a 530trivial function that can always only take doubles, this is not 531true. Someone might have overridden the valueOf for x so that the 532toNumber coercion has side effects. To fulfil JavaScript semantics, 533the coercion has to run twice for both terms of the multiplication 534even if they are the same object. This means that call site 535specialization is necessary, not parameter specialization on the form 536"function square(x) { var xd = (double)x; return xd*xd; }", as one 537might first think. 538 539Generating a method specialization for any variant of a function that 540we can determine by types at compile time is a combinatorial explosion 541of byte code (try it e.g. on all the variants of am3 in the Octane 542benchmark crypto.js). Thus, this needs to be lazy 543 5443) Optimistic callsite writes, something on the form 545 546x = y; //x is a field known to be a primitive. y is only an object as 547far as we can tell 548 549turns into 550 551try { 552 x = (int)y; 553} catch (X is not an integer field right now | ClassCastException e) { 554 x = y; 555} 556 557Mini POC shows that this is the key to a lot of dual field performance 558in seemingly trivial micros where one unknown object, in reality 559actually a primitive, foils it for us. Very common pattern. Once we 560are "all primitives", dual fields runs a lot faster than Object fields 561only. 562 563We still have to deal with objects vs primitives for local bytecode 564slots, possibly through code copying and versioning. 565 566The Future: 567 568We expect the usefulness of dual fields to increase significantly 569after the optimistic type system described in the section on 570integer arithmetic above is implemented. 571 572 573SYSTEM PROPERTY: -Dnashorn.compiler.symbol.trace=[<x>[,*]], 574 -Dnashorn.compiler.symbol.stacktrace=[<x>[,*]] 575 576When this property is set, creation and manipulation of any symbol 577named "x" will show information about when the compiler changes its 578type assumption, bytecode local variable slot assignment and other 579data. This is useful if, for example, a symbol shows up as an Object, 580when you believe it should be a primitive. Usually there is an 581explanation for this, for example that it exists in the global scope 582and type analysis has to be more conservative. 583 584Several symbols names to watch can be specified by comma separation. 585 586If no variable name is specified (and no equals sign), all symbols 587will be watched 588 589By using "stacktrace" instead of or together with "trace", stack 590traces will be displayed upon symbol changes according to the same 591semantics. 592 593 594SYSTEM PROPERTY: -Dnashorn.lexer.xmlliterals 595 596If this property it set, it means that the Lexer should attempt to 597parse XML literals, which would otherwise generate syntax 598errors. Warning: there are currently no unit tests for this 599functionality. 600 601XML literals, when this is enabled, end up as standard LiteralNodes in 602the IR. 603 604 605SYSTEM_PROPERTY: -Dnashorn.debug 606 607If this property is set to true, Nashorn runs in Debug mode. Debug 608mode is slightly slower, as for example statistics counters are enabled 609during the run. Debug mode makes available a NativeDebug instance 610called "Debug" in the global space that can be used to print property 611maps and layout for script objects, as well as a "dumpCounters" method 612that will print the current values of the previously mentioned stats 613counters. 614 615These functions currently exists for Debug: 616 617"map" - print(Debug.map(x)) will dump the PropertyMap for object x to 618stdout (currently there also exist functions called "embedX", where X 619is a value from 0 to 3, that will dump the contents of the embed pool 620for the first spill properties in any script object and "spill", that 621will dump the contents of the growing spill pool of spill properties 622in any script object. This is of course subject to change without 623notice, should we change the script object layout. 624 625"methodHandle" - this method returns the method handle that is used 626for invoking a particular script function. 627 628"identical" - this method compares two script objects for reference 629equality. It is a == Java comparison 630 631"dumpCounters" - will dump the debug counters' current values to 632stdout. 633 634Currently we count number of ScriptObjects in the system, number of 635Scope objects in the system, number of ScriptObject listeners added, 636removed and dead (without references). 637 638We also count number of ScriptFunctions, ScriptFunction invocations 639and ScriptFunction allocations. 640 641Furthermore we count PropertyMap statistics: how many property maps 642exist, how many times were property maps cloned, how many times did 643the property map history cache hit, prevent new allocations, how many 644prototype invalidations were done, how many time the property map 645proto cache hit. 646 647Finally we count callsite misses on a per callsite bases, which occur 648when a callsite has to be relinked, due to a previous assumption of 649object layout being invalidated. 650 651 652SYSTEM PROPERTY: -Dnashorn.methodhandles.debug, 653-Dnashorn.methodhandles.debug=create 654 655If this property is enabled, each MethodHandle related call that uses 656the java.lang.invoke package gets its MethodHandle intercepted and an 657instrumentation printout of arguments and return value appended to 658it. This shows exactly which method handles are executed and from 659where. (Also MethodTypes and SwitchPoints). This can be augmented with 660more information, for example, instance count, by subclassing or 661further extending the TraceMethodHandleFactory implementation in 662MethodHandleFactory.java. 663 664If the property is specialized with "=create" as its option, 665instrumentation will be shown for method handles upon creation time 666rather than at runtime usage. 667 668 669SYSTEM PROPERTY: -Dnashorn.methodhandles.debug.stacktrace 670 671This does the same as nashorn.methodhandles.debug, but when enabled 672also dumps the stack trace for every instrumented method handle 673operation. Warning: This is enormously verbose, but provides a pretty 674decent "grep:able" picture of where the calls are coming from. 675 676See the description of the codegen logger below for a more verbose 677description of this option 678 679 680SYSTEM PROPERTY: -Dnashorn.scriptfunction.specialization.disable 681 682There are several "fast path" implementations of constructors and 683functions in the NativeObject classes that, in their original form, 684take a variable amount of arguments. Said functions are also declared 685to take Object parameters in their original form, as this is what the 686JavaScript specification mandates. 687However, we often know quite a lot more at a callsite of one of these 688functions. For example, Math.min is called with a fixed number (2) of 689integer arguments. The overhead of boxing these ints to Objects and 690folding them into an Object array for the generic varargs Math.min 691function is an order of magnitude slower than calling a specialized 692implementation of Math.min that takes two integers. Specialized 693functions and constructors are identified by the tag 694@SpecializedFunction and @SpecializedConstructor in the Nashorn 695code. The linker will link in the most appropriate (narrowest types, 696right number of types and least number of arguments) specialization if 697specializations are available. 698 699Every ScriptFunction may carry specializations that the linker can 700choose from. This framework will likely be extended for user defined 701functions. The compiler can often infer enough parameter type info 702from callsites for in order to generate simpler versions with less 703generic Object types. This feature depends on future lazy jitting, as 704there tend to be many calls to user defined functions, some where the 705callsite can be specialized, some where we mostly see object 706parameters even at the callsite. 707 708If this system property is set to true, the linker will not attempt to 709use any specialized function or constructor for native objects, but 710just call the generic one. 711 712 713SYSTEM PROPERTY: -Dnashorn.tcs.miss.samplePercent=<x> 714 715When running with the trace callsite option (-tcs), Nashorn will count 716and instrument any callsite misses that require relinking. As the 717number of relinks is large and usually produces a lot of output, this 718system property can be used to constrain the percentage of misses that 719should be logged. Typically this is set to 1 or 5 (percent). 1% is the 720default value. 721 722 723SYSTEM_PROPERTY: -Dnashorn.profilefile=<filename> 724 725When running with the profile callsite options (-pcs), Nashorn will 726dump profiling data for all callsites to stderr as a shutdown hook. To 727instead redirect this to a file, specify the path to the file using 728this system property. 729 730 731SYSTEM_PROPERTY: -Dnashorn.regexp.impl=[jdk|joni] 732 733This property defines the regular expression engine to be used by 734Nashorn. Set this flag to "jdk" to get an implementation based on the 735JDK's java.util.regex package. Set this property to "joni" to install 736an implementation based on Joni, the regular expression engine used by 737the JRuby project. The default value for this flag is "joni" 738 739 740SYSTEM PROPERTY: -Dnashorn.time 741 742This enables timers for various phases of script compilation. The timers 743will be dumped when the Nashorn process exits. We see a percentage value 744of how much time was spent not executing bytecode (i.e. compilation and 745internal tasks) at the end of the report. 746 747Here is an example: 748 749[JavaScript Parsing] 61 ms 750[Constant Folding] 11 ms 751[Control Flow Lowering] 26 ms 752[Type Attribution] 81 ms 753[Range Analysis] 0 ms 754[Code Splitting] 29 ms 755[Type Finalization] 19 ms 756[Bytecode Generation] 189 ms 757[Code Installation] 7 ms 758Total runtime: 508 ms (Non-runtime: 423 ms [83%]) 759 760=============== 7612. The loggers. 762=============== 763 764It is very simple to create your own logger. Use the DebugLogger class 765and give the subsystem name as a constructor argument. 766 767The Nashorn loggers can be used to print per-module or per-subsystem 768debug information with different levels of verbosity. The loggers for 769a given subsystem are available are enabled by using 770 771--log=<systemname>[:<level>] 772 773on the command line. 774 775Here <systemname> identifies the name of the subsystem to be logged 776and the optional colon and level argument is a standard 777java.util.logging.Level name (severe, warning, info, config, fine, 778finer, finest). If the level is left out for a particular subsystem, 779it defaults to "info". Any log message logged as the level or a level 780that is more important will be output to stderr by the logger. 781 782Several loggers can be enabled by a single command line option, by 783putting a comma after each subsystem/level tuple (or each subsystem if 784level is unspecified). The --log option can also be given multiple 785times on the same command line, with the same effect. 786 787For example: --log=codegen,fields:finest is equivalent to 788--log=codegen:info --log=fields:finest 789 790The subsystems that currently support logging are: 791 792 793* compiler 794 795The compiler is in charge of turning source code and function nodes 796into byte code, and installs the classes into a class loader 797controlled from the Context. Log messages are, for example, about 798things like new compile units being allocated. The compiler has global 799settings that all the tiers of codegen (e.g. Lower and CodeGenerator) 800use.s 801 802 803* codegen 804 805The code generator is the emitter stage of the code pipeline, and 806turns the lowest tier of a FunctionNode into bytecode. Codegen logging 807shows byte codes as they are being emitted, line number information 808and jumps. It also shows the contents of the bytecode stack prior to 809each instruction being emitted. This is a good debugging aid. For 810example: 811 812[codegen] #41 line:2 (f)_afc824e 813[codegen] #42 load symbol x slot=2 814[codegen] #43 {1:O} load int 0 815[codegen] #44 {2:I O} dynamic_runtime_call GT:ZOI_I args=2 returnType=boolean 816[codegen] #45 signature (Ljava/lang/Object;I)Z 817[codegen] #46 {1:Z} ifeq ternary_false_5402fe28 818[codegen] #47 load symbol x slot=2 819[codegen] #48 {1:O} goto ternary_exit_107c1f2f 820[codegen] #49 ternary_false_5402fe28 821[codegen] #50 load symbol x slot=2 822[codegen] #51 {1:O} convert object -> double 823[codegen] #52 {1:D} neg 824[codegen] #53 {1:D} convert double -> object 825[codegen] #54 {1:O} ternary_exit_107c1f2f 826[codegen] #55 {1:O} return object 827 828shows a ternary node being generated for the sequence "return x > 0 ? 829x : -x" 830 831The first number on the log line is a unique monotonically increasing 832emission id per bytecode. There is no guarantee this is the same id 833between runs. depending on non deterministic code 834execution/compilation, but for small applications it usually is. If 835the system variable -Dnashorn.codegen.debug.trace=<x> is set, where x 836is a bytecode emission id, a stack trace will be shown as the 837particular bytecode is about to be emitted. This can be a quick way to 838determine where it comes from without attaching the debugger. "Who 839generated that neg?" 840 841The --log=codegen option is equivalent to setting the system variable 842"nashorn.codegen.debug" to true. 843 844* fold 845 846Shows constant folding taking place before lowering 847 848* lower 849 850This is the first lowering pass. 851 852Lower is a code generation pass that turns high level IR nodes into 853lower level one, for example substituting comparisons to RuntimeNodes 854and inlining finally blocks. 855 856Lower is also responsible for determining control flow information 857like end points. 858 859 860* attr 861 862The lowering annotates a FunctionNode with symbols for each identifier 863and transforms high level constructs into lower level ones, that the 864CodeGenerator consumes. 865 866Lower logging typically outputs things like post pass actions, 867insertions of casts because symbol types have been changed and type 868specialization information. Currently very little info is generated by 869this logger. This will probably change. 870 871 872* finalize 873 874This --log=finalize log option outputs information for type finalization, 875the third tier of the compiler. This means things like placement of 876specialized scope nodes or explicit conversions. 877 878 879* fields 880 881The --log=fields option (at info level) is equivalent to setting the 882system variable "nashorn.fields.debug" to true. At the info level it 883will only show info about type assumptions that were invalidated. If 884the level is set to finest, it will also trace every AccessorProperty 885getter and setter in the program, show arguments, return values 886etc. It will also show the internal representation of respective field 887(Object in the normal case, unless running with the dual field 888representation) 889 890 891======================= 8923. Undocumented options 893======================= 894 895Here follows a short description of undocumented options for Nashorn. 896To see a list of all undocumented options, use the (undocumented) flag 897"-xhelp". 898 899i.e. jjs -xhelp or java -jar nashorn.jar -xhelp 900 901Undocumented options are not guaranteed to work, run correctly or be 902bug free. They are experimental and for internal or debugging use. 903They are also subject to change without notice. 904 905In practice, though, all options below not explicitly documented as 906EXPERIMENTAL can be relied upon, for example --dump-on-error is useful 907for any JavaScript/Nashorn developer, but there is no guarantee. 908 909A short summary follows: 910 911 -D (-Dname=value. Set a system property. This option can be repeated.) 912 913 -ccs, --class-cache-size (Size of the Class cache size per global scope.) 914 915 -cp, -classpath (-cp path. Specify where to find user class files.) 916 917 -co, --compile-only (Compile script without running. Exit after compilation) 918 param: [true|false] default: false 919 920 -d, --dump-debug-dir (specify a destination directory to dump class files. 921 This must be combined with the --compile-only option to work) 922 param: <path> 923 924 --debug-lines (Generate line number table in .class files.) 925 param: [true|false] default: true 926 927 --debug-locals (Generate local variable table in .class files.) 928 param: [true|false] default: false 929 930 -doe, -dump-on-error (Dump a stack trace on errors.) 931 param: [true|false] default: false 932 933 --early-lvalue-error (invalid lvalue expressions should be reported as early errors.) 934 param: [true|false] default: true 935 936 --empty-statements (Preserve empty statements in AST.) 937 param: [true|false] default: false 938 939 -fv, -fullversion (Print full version info of Nashorn.) 940 param: [true|false] default: false 941 942 --function-statement-error (Report an error when function declaration is used as a statement.) 943 param: [true|false] default: false 944 945 --function-statement-warning (Warn when function declaration is used as a statement.) 946 param: [true|false] default: false 947 948 -fx (Launch script as an fx application.) 949 param: [true|false] default: false 950 951 --global-per-engine (Use single Global instance per script engine instance.) 952 param: [true|false] default: false 953 954 -h, -help (Print help for command line flags.) 955 param: [true|false] default: false 956 957 --lazy-compilation (EXPERIMENTAL: Use lazy code generation strategies - do not compile 958 the entire script at once.) 959 param: [true|false] default: false 960 961 --loader-per-compile (Create a new class loader per compile.) 962 param: [true|false] default: true 963 964 -l, --locale (Set Locale for script execution.) 965 param: <locale> default: en-US 966 967 --log (Enable logging of a given level for a given number of sub systems. 968 [for example: --log=fields:finest,codegen:info]) 969 param: <module:level>,* 970 971 -nj, --no-java (No Java support) 972 param: [true|false] default: false 973 974 -nse, --no-syntax-extensions (No non-standard syntax extensions) 975 param: [true|false] default: false 976 977 -nta, --no-typed-arrays (No Typed arrays support) 978 param: [true|false] default: false 979 980 --parse-only (Parse without compiling.) 981 param: [true|false] default: false 982 983 --print-ast (Print abstract syntax tree.) 984 param: [true|false] default: false 985 986 --print-code (Print bytecode.) 987 param: [true|false] default: false 988 989 --print-lower-ast (Print lowered abstract syntax tree.) 990 param: [true|false] default: false 991 992 --print-lower-parse (Print the parse tree after lowering.) 993 param: [true|false] default: false 994 995 --print-mem-usage (Print memory usage of IR after each compile stage.) 996 param: [true|false] default: false 997 998 --print-no-newline (Print function will not print new line char.) 999 param: [true|false] default: false 1000 1001 --print-parse (Print the parse tree.) 1002 param: [true|false] default: false 1003 1004 --print-symbols (Print the symbol table.) 1005 param: [true|false] default: false 1006 1007 -pcs, --profile-callsites (Dump callsite profile data.) 1008 param: [true|false] default: false 1009 1010 --range-analysis (EXPERIMENTAL: Do range analysis using known compile time types, 1011 and try to narrow number types) 1012 param: [true|false] default: false 1013 1014 -scripting (Enable scripting features.) 1015 param: [true|false] default: false 1016 1017 --specialize-calls (EXPERIMENTAL: Specialize all or a set of method according 1018 to callsite parameter types) 1019 param: [=function_1,...,function_n] 1020 1021 --stderr (Redirect stderr to a filename or to another tty, e.g. stdout) 1022 param: <output console> 1023 1024 --stdout (Redirect stdout to a filename or to another tty, e.g. stderr) 1025 param: <output console> 1026 1027 -strict (Run scripts in strict mode.) 1028 param: [true|false] default: false 1029 1030 -t, -timezone (Set timezone for script execution.) 1031 param: <timezone> default: Europe/Stockholm 1032 1033 -tcs, --trace-callsites (Enable callsite trace mode. Options are: miss [trace callsite misses] 1034 enterexit [trace callsite enter/exit], objects [print object properties]) 1035 param: [=[option,]*] 1036 1037 --verify-code (Verify byte code before running.) 1038 param: [true|false] default: false 1039 1040 -v, -version (Print version info of Nashorn.) 1041 param: [true|false] default: false 1042 1043 -xhelp (Print extended help for command line flags.) 1044 param: [true|false] default: false 1045 1046