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