nashorn/docs/DEVELOPER_README
author hannesw
Fri, 22 Feb 2013 17:00:22 +0100
changeset 16259 bb504280c322
parent 16227 1bafb74d17b2
child 16533 6ae708677f92
permissions -rw-r--r--
8006028: Integrate Joni regexp engine with Nashorn Reviewed-by: lagergren, attila
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     1
This document describes system properties that are used for internal
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     2
debugging and instrumentation purposes, along with the system loggers,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     3
which are used for the same thing.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     4
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     5
This document is intended as a developer resource, and it is not
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     6
needed as Nashorn documentation for normal usage. Flags and system
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     7
properties described herein are subject to change without notice.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     8
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
     9
=====================================
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    10
1. System properties used internally
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    11
=====================================
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    12
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    13
This documentation of the system property flags assume that the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    14
default value of the flag is false, unless otherwise specified.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    15
16152
ea430b83d74d 8005789: Forgot to document -Dnashorn.unstable.relink.threshold
lagergren
parents: 16147
diff changeset
    16
SYSTEM PROPERTY: -Dnashorn.unstable.relink.threshold=x
ea430b83d74d 8005789: Forgot to document -Dnashorn.unstable.relink.threshold
lagergren
parents: 16147
diff changeset
    17
ea430b83d74d 8005789: Forgot to document -Dnashorn.unstable.relink.threshold
lagergren
parents: 16147
diff changeset
    18
This property controls how many call site misses are allowed before a 
ea430b83d74d 8005789: Forgot to document -Dnashorn.unstable.relink.threshold
lagergren
parents: 16147
diff changeset
    19
callsite is relinked with "apply" semantics to never change again. 
ea430b83d74d 8005789: Forgot to document -Dnashorn.unstable.relink.threshold
lagergren
parents: 16147
diff changeset
    20
In the case of megamorphic callsites, this is necessary, or the 
ea430b83d74d 8005789: Forgot to document -Dnashorn.unstable.relink.threshold
lagergren
parents: 16147
diff changeset
    21
program would spend all its time swapping out callsite targets. Dynalink 
ea430b83d74d 8005789: Forgot to document -Dnashorn.unstable.relink.threshold
lagergren
parents: 16147
diff changeset
    22
has a default value (currently 8 relinks) for this property if it 
ea430b83d74d 8005789: Forgot to document -Dnashorn.unstable.relink.threshold
lagergren
parents: 16147
diff changeset
    23
is not explicitly set.
ea430b83d74d 8005789: Forgot to document -Dnashorn.unstable.relink.threshold
lagergren
parents: 16147
diff changeset
    24
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    25
16227
1bafb74d17b2 8007956: Wrong or obsolete system properties in docs/DEVELOPER_README
hannesw
parents: 16201
diff changeset
    26
SYSTEM PROPERTY: -Dnashorn.compiler.splitter.threshold=x
16168
f0c208287983 8005976: Break out AccessSpecializer into one pass before CodeGenerator instead of iterative applications from CodeGenerator
lagergren
parents: 16152
diff changeset
    27
f0c208287983 8005976: Break out AccessSpecializer into one pass before CodeGenerator instead of iterative applications from CodeGenerator
lagergren
parents: 16152
diff changeset
    28
This will change the node weight that requires a subgraph of the IR to
f0c208287983 8005976: Break out AccessSpecializer into one pass before CodeGenerator instead of iterative applications from CodeGenerator
lagergren
parents: 16152
diff changeset
    29
be split into several classes in order not to run out of bytecode space.
f0c208287983 8005976: Break out AccessSpecializer into one pass before CodeGenerator instead of iterative applications from CodeGenerator
lagergren
parents: 16152
diff changeset
    30
The default value is 0x8000 (32768).
f0c208287983 8005976: Break out AccessSpecializer into one pass before CodeGenerator instead of iterative applications from CodeGenerator
lagergren
parents: 16152
diff changeset
    31
f0c208287983 8005976: Break out AccessSpecializer into one pass before CodeGenerator instead of iterative applications from CodeGenerator
lagergren
parents: 16152
diff changeset
    32
16227
1bafb74d17b2 8007956: Wrong or obsolete system properties in docs/DEVELOPER_README
hannesw
parents: 16201
diff changeset
    33
SYSTEM PROPERTY: -Dnashorn.compiler.intarithmetic
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    34
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    35
Arithmetic operations in Nashorn (except bitwise ones) typically
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    36
coerce the operands to doubles (as per the JavaScript spec). To switch
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    37
this off and remain in integer mode, for example for "var x = a&b; var
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    38
y = c&d; var z = x*y;", use this flag. This will force the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    39
multiplication of variables that are ints to be done with the IMUL
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    40
bytecode and the result "z" to become an int.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    41
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    42
WARNING: Note that is is experimental only to ensure that type support
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    43
exists for all primitive types. The generated code is unsound. This
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    44
will be the case until we do optimizations based on it. There is a CR
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    45
in Nashorn to do better range analysis, and ensure that this is only
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    46
done where the operation can't overflow into a wider type. Currently
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    47
no overflow checking is done, so at the moment, until range analysis
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    48
has been completed, this option is turned off.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    49
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    50
We've experimented by using int arithmetic for everything and putting
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    51
overflow checks afterwards, which would recompute the operation with
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    52
the correct precision, but have yet to find a configuration where this
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    53
is faster than just using doubles directly, even if the int operation
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    54
does not overflow. Getting access to a JVM intrinsic that does branch
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    55
on overflow would probably alleviate this.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    56
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    57
There is also a problem with this optimistic approach if the symbol
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    58
happens to reside in a local variable slot in the bytecode, as those
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    59
are strongly typed. Then we would need to split large sections of
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    60
control flow, so this is probably not the right way to go, while range
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    61
analysis is. There is a large difference between integer bytecode
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    62
without overflow checks and double bytecode. The former is
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    63
significantly faster.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    64
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    65
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    66
SYSTEM PROPERTY: -Dnashorn.codegen.debug, -Dnashorn.codegen.debug.trace=<x>
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    67
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    68
See the description of the codegen logger below.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    69
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    70
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    71
SYSTEM_PROPERTY: -Dnashorn.fields.debug
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    72
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    73
See the description on the fields logger below.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    74
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    75
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    76
SYSTEM PROPERTY: -Dnashorn.fields.dual
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    77
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    78
When this property is true, Nashorn will attempt to use primitive
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    79
fields for AccessorProperties (currently just AccessorProperties, not
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    80
spill properties). Memory footprint for script objects will increase,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    81
as we need to maintain both a primitive field (a long) as well as an
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    82
Object field for the property value. Ints are represented as the 32
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    83
low bits of the long fields. Doubles are represented as the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    84
doubleToLongBits of their value. This way a single field can be used
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    85
for all primitive types. Packing and unpacking doubles to their bit
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    86
representation is intrinsified by the JVM and extremely fast.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    87
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    88
While dual fields in theory runs significantly faster than Object
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    89
fields due to reduction of boxing and memory allocation overhead,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    90
there is still work to be done to make this a general purpose
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    91
solution. Research is ongoing.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    92
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    93
In the future, this might complement or be replaced by experimental
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    94
feature sun.misc.TaggedArray, which has been discussed on the mlvm
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    95
mailing list. TaggedArrays are basically a way to share data space
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    96
between primitives and references, and have the GC understand this.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    97
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    98
As long as only primitive values are written to the fields and enough
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
    99
type information exists to make sure that any reads don't have to be
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   100
uselessly boxed and unboxed, this is significantly faster than the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   101
standard "Objects only" approach that currently is the default. See
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   102
test/examples/dual-fields-micro.js for an example that runs twice as
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   103
fast with dual fields as without them. Here, the compiler, can
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   104
determine that we are dealing with numbers only throughout the entire
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   105
property life span of the properties involved.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   106
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   107
If a "real" object (not a boxed primitive) is written to a field that
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   108
has a primitive representation, its callsite is relinked and an Object
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   109
field is used forevermore for that particular field in that
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   110
PropertyMap and its children, even if primitives are later assigned to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   111
it.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   112
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   113
As the amount of compile time type information is very small in a
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   114
dynamic language like JavaScript, it is frequently the case that
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   115
something has to be treated as an object, because we don't know any
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   116
better. In reality though, it is often a boxed primitive is stored to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   117
an AccessorProperty. The fastest way to handle this soundly is to use
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   118
a callsite typecheck and avoid blowing the field up to an Object. We
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   119
never revert object fields to primitives. Ping-pong:ing back and forth
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   120
between primitive representation and Object representation would cause
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   121
fatal performance overhead, so this is not an option.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   122
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   123
For a general application the dual fields approach is still slower
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   124
than objects only fields in some places, about the same in most cases,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   125
and significantly faster in very few. This is due the program using
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   126
primitives, but we still can't prove it. For example "local_var a =
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   127
call(); field = a;" may very well write a double to the field, but the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   128
compiler dare not guess a double type if field is a local variable,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   129
due to bytecode variables being strongly typed and later non
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   130
interchangeable. To get around this, the entire method would have to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   131
be replaced and a continuation retained to restart from. We believe
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   132
that the next steps we should go through are instead:
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   133
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   134
1) Implement method specialization based on callsite, as it's quite
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   135
frequently the case that numbers are passed around, but currently our
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   136
function nodes just have object types visible to the compiler. For
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   137
example "var b = 17; func(a,b,17)" is an example where two parameters
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   138
can be specialized, but the main version of func might also be called
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   139
from another callsite with func(x,y,"string").
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   140
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   141
2) This requires lazy jitting as the functions have to be specialized
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   142
per callsite.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   143
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   144
Even though "function square(x) { return x*x }" might look like a
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   145
trivial function that can always only take doubles, this is not
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   146
true. Someone might have overridden the valueOf for x so that the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   147
toNumber coercion has side effects. To fulfil JavaScript semantics,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   148
the coercion has to run twice for both terms of the multiplication
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   149
even if they are the same object. This means that call site
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   150
specialization is necessary, not parameter specialization on the form
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   151
"function square(x) { var xd = (double)x; return xd*xd; }", as one
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   152
might first think.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   153
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   154
Generating a method specialization for any variant of a function that
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   155
we can determine by types at compile time is a combinatorial explosion
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   156
of byte code (try it e.g. on all the variants of am3 in the Octane
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   157
benchmark crypto.js). Thus, this needs to be lazy
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   158
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   159
3) Possibly optimistic callsite writes, something on the form
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   160
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   161
x = y; //x is a field known to be a primitive. y is only an object as
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   162
far as we can tell
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   163
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   164
turns into
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   165
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   166
try {
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   167
  x = (int)y;
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   168
} catch (X is not an integer field right now | ClassCastException e) {
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   169
  x = y;
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   170
}
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   171
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   172
Mini POC shows that this is the key to a lot of dual field performance
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   173
in seemingly trivial micros where one unknown object, in reality
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   174
actually a primitive, foils it for us. Very common pattern. Once we
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   175
are "all primitives", dual fields runs a lot faster than Object fields
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   176
only.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   177
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   178
We still have to deal with objects vs primitives for local bytecode
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   179
slots, possibly through code copying and versioning.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   180
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   181
16201
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   182
SYSTEM PROPERTY: -Dnashorn.compiler.symbol.trace=[<x>[,*]], 
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   183
  -Dnashorn.compiler.symbol.stacktrace=[<x>[,*]]
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   184
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   185
When this property is set, creation and manipulation of any symbol
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   186
named "x" will show information about when the compiler changes its
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   187
type assumption, bytecode local variable slot assignment and other
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   188
data. This is useful if, for example, a symbol shows up as an Object,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   189
when you believe it should be a primitive. Usually there is an
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   190
explanation for this, for example that it exists in the global scope
16201
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   191
and type analysis has to be more conservative. 
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   192
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   193
Several symbols names to watch can be specified by comma separation.
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   194
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   195
If no variable name is specified (and no equals sign), all symbols
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   196
will be watched
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   197
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   198
By using "stacktrace" instead of or together with "trace", stack
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   199
traces will be displayed upon symbol changes according to the same
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   200
semantics.
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   201
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   202
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   203
SYSTEM PROPERTY: nashorn.lexer.xmlliterals
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   204
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   205
If this property it set, it means that the Lexer should attempt to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   206
parse XML literals, which would otherwise generate syntax
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   207
errors. Warning: there are currently no unit tests for this
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   208
functionality.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   209
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   210
XML literals, when this is enabled, end up as standard LiteralNodes in
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   211
the IR.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   212
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   213
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   214
SYSTEM_PROPERTY: nashorn.debug
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   215
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   216
If this property is set to true, Nashorn runs in Debug mode. Debug
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   217
mode is slightly slower, as for example statistics counters are enabled
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   218
during the run. Debug mode makes available a NativeDebug instance
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   219
called "Debug" in the global space that can be used to print property
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   220
maps and layout for script objects, as well as a "dumpCounters" method
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   221
that will print the current values of the previously mentioned stats
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   222
counters.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   223
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   224
These functions currently exists for Debug:
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   225
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   226
"map" - print(Debug.map(x)) will dump the PropertyMap for object x to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   227
stdout (currently there also exist functions called "embedX", where X
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   228
is a value from 0 to 3, that will dump the contents of the embed pool
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   229
for the first spill properties in any script object and "spill", that
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   230
will dump the contents of the growing spill pool of spill properties
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   231
in any script object. This is of course subject to change without
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   232
notice, should we change the script object layout.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   233
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   234
"methodHandle" - this method returns the method handle that is used
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   235
for invoking a particular script function.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   236
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   237
"identical" - this method compares two script objects for reference
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   238
equality. It is a == Java comparison
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   239
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   240
"dumpCounters" - will dump the debug counters' current values to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   241
stdout.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   242
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   243
Currently we count number of ScriptObjects in the system, number of
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   244
Scope objects in the system, number of ScriptObject listeners added,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   245
removed and dead (without references).
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   246
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   247
We also count number of ScriptFunctions, ScriptFunction invocations
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   248
and ScriptFunction allocations.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   249
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   250
Furthermore we count PropertyMap statistics: how many property maps
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   251
exist, how many times were property maps cloned, how many times did
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   252
the property map history cache hit, prevent new allocations, how many
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   253
prototype invalidations were done, how many time the property map
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   254
proto cache hit.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   255
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   256
Finally we count callsite misses on a per callsite bases, which occur
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   257
when a callsite has to be relinked, due to a previous assumption of
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   258
object layout being invalidated.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   259
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   260
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   261
SYSTEM PROPERTY: nashorn.methodhandles.debug,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   262
nashorn.methodhandles.debug=create
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   263
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   264
If this property is enabled, each MethodHandle related call that uses
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   265
the java.lang.invoke package gets its MethodHandle intercepted and an
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   266
instrumentation printout of arguments and return value appended to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   267
it. This shows exactly which method handles are executed and from
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   268
where. (Also MethodTypes and SwitchPoints). This can be augmented with
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   269
more information, for example, instance count, by subclassing or
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   270
further extending the TraceMethodHandleFactory implementation in
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   271
MethodHandleFactory.java.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   272
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   273
If the property is specialized with "=create" as its option,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   274
instrumentation will be shown for method handles upon creation time
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   275
rather than at runtime usage.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   276
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   277
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   278
SYSTEM PROPERTY: nashorn.methodhandles.debug.stacktrace
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   279
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   280
This does the same as nashorn.methodhandles.debug, but when enabled
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   281
also dumps the stack trace for every instrumented method handle
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   282
operation. Warning: This is enormously verbose, but provides a pretty
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   283
decent "grep:able" picture of where the calls are coming from.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   284
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   285
See the description of the codegen logger below for a more verbose
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   286
description of this option
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   287
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   288
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   289
SYSTEM PROPERTY: nashorn.scriptfunction.specialization.disable
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   290
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   291
There are several "fast path" implementations of constructors and
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   292
functions in the NativeObject classes that, in their original form,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   293
take a variable amount of arguments. Said functions are also declared
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   294
to take Object parameters in their original form, as this is what the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   295
JavaScript specification mandates.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   296
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   297
However, we often know quite a lot more at a callsite of one of these
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   298
functions. For example, Math.min is called with a fixed number (2) of
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   299
integer arguments. The overhead of boxing these ints to Objects and
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   300
folding them into an Object array for the generic varargs Math.min
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   301
function is an order of magnitude slower than calling a specialized
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   302
implementation of Math.min that takes two integers. Specialized
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   303
functions and constructors are identified by the tag
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   304
@SpecializedFunction and @SpecializedConstructor in the Nashorn
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   305
code. The linker will link in the most appropriate (narrowest types,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   306
right number of types and least number of arguments) specialization if
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   307
specializations are available.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   308
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   309
Every ScriptFunction may carry specializations that the linker can
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   310
choose from. This framework will likely be extended for user defined
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   311
functions. The compiler can often infer enough parameter type info
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   312
from callsites for in order to generate simpler versions with less
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   313
generic Object types. This feature depends on future lazy jitting, as
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   314
there tend to be many calls to user defined functions, some where the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   315
callsite can be specialized, some where we mostly see object
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   316
parameters even at the callsite.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   317
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   318
If this system property is set to true, the linker will not attempt to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   319
use any specialized function or constructor for native objects, but
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   320
just call the generic one.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   321
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   322
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   323
SYSTEM PROPERTY: nashorn.tcs.miss.samplePercent=<x>
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   324
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   325
When running with the trace callsite option (-tcs), Nashorn will count
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   326
and instrument any callsite misses that require relinking. As the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   327
number of relinks is large and usually produces a lot of output, this
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   328
system property can be used to constrain the percentage of misses that
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   329
should be logged. Typically this is set to 1 or 5 (percent). 1% is the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   330
default value.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   331
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   332
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   333
SYSTEM_PROPERTY: nashorn.profilefile=<filename>
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   334
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   335
When running with the profile callsite options (-pcs), Nashorn will
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   336
dump profiling data for all callsites to stderr as a shutdown hook. To
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   337
instead redirect this to a file, specify the path to the file using
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   338
this system property.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   339
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   340
16259
bb504280c322 8006028: Integrate Joni regexp engine with Nashorn
hannesw
parents: 16227
diff changeset
   341
SYSTEM_PROPERTY: nashorn.regexp.impl=[jdk|joni]
bb504280c322 8006028: Integrate Joni regexp engine with Nashorn
hannesw
parents: 16227
diff changeset
   342
bb504280c322 8006028: Integrate Joni regexp engine with Nashorn
hannesw
parents: 16227
diff changeset
   343
This property defines the regular expression engine to be used by
bb504280c322 8006028: Integrate Joni regexp engine with Nashorn
hannesw
parents: 16227
diff changeset
   344
Nashorn. The default implementation is "jdk" which is based on the
bb504280c322 8006028: Integrate Joni regexp engine with Nashorn
hannesw
parents: 16227
diff changeset
   345
JDK's java.util.regex package. Set this property to "joni" to install
bb504280c322 8006028: Integrate Joni regexp engine with Nashorn
hannesw
parents: 16227
diff changeset
   346
an implementation based on Joni, the regular expression engine used by
bb504280c322 8006028: Integrate Joni regexp engine with Nashorn
hannesw
parents: 16227
diff changeset
   347
the JRuby project.
bb504280c322 8006028: Integrate Joni regexp engine with Nashorn
hannesw
parents: 16227
diff changeset
   348
bb504280c322 8006028: Integrate Joni regexp engine with Nashorn
hannesw
parents: 16227
diff changeset
   349
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   350
===============
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   351
2. The loggers.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   352
===============
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   353
16201
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   354
It is very simple to create your own logger. Use the DebugLogger class
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   355
and give the subsystem name as a constructor argument.
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   356
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   357
The Nashorn loggers can be used to print per-module or per-subsystem
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   358
debug information with different levels of verbosity. The loggers for
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   359
a given subsystem are available are enabled by using
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   360
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   361
--log=<systemname>[:<level>]
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   362
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   363
on the command line.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   364
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   365
Here <systemname> identifies the name of the subsystem to be logged
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   366
and the optional colon and level argument is a standard
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   367
java.util.logging.Level name (severe, warning, info, config, fine,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   368
finer, finest). If the level is left out for a particular subsystem,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   369
it defaults to "info". Any log message logged as the level or a level
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   370
that is more important will be output to stderr by the logger.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   371
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   372
Several loggers can be enabled by a single command line option, by
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   373
putting a comma after each subsystem/level tuple (or each subsystem if
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   374
level is unspecified). The --log option can also be given multiple
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   375
times on the same command line, with the same effect.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   376
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   377
For example: --log=codegen,fields:finest is equivalent to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   378
--log=codegen:info --log=fields:finest
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   379
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   380
The subsystems that currently support logging are:
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   381
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   382
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   383
* compiler
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   384
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   385
The compiler is in charge of turning source code and function nodes
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   386
into byte code, and installs the classes into a class loader
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   387
controlled from the Context. Log messages are, for example, about
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   388
things like new compile units being allocated. The compiler has global
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   389
settings that all the tiers of codegen (e.g. Lower and CodeGenerator)
16201
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   390
use.s
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   391
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   392
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   393
* codegen
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   394
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   395
The code generator is the emitter stage of the code pipeline, and
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   396
turns the lowest tier of a FunctionNode into bytecode. Codegen logging
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   397
shows byte codes as they are being emitted, line number information
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   398
and jumps. It also shows the contents of the bytecode stack prior to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   399
each instruction being emitted. This is a good debugging aid. For
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   400
example:
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   401
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   402
[codegen] #41                       line:2 (f)_afc824e 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   403
[codegen] #42                           load symbol x slot=2 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   404
[codegen] #43  {1:O}                    load int 0 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   405
[codegen] #44  {2:I O}                  dynamic_runtime_call GT:ZOI_I args=2 returnType=boolean 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   406
[codegen] #45                              signature (Ljava/lang/Object;I)Z 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   407
[codegen] #46  {1:Z}                    ifeq  ternary_false_5402fe28 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   408
[codegen] #47                           load symbol x slot=2 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   409
[codegen] #48  {1:O}                    goto ternary_exit_107c1f2f 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   410
[codegen] #49                       ternary_false_5402fe28 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   411
[codegen] #50                           load symbol x slot=2 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   412
[codegen] #51  {1:O}                    convert object -> double 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   413
[codegen] #52  {1:D}                    neg 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   414
[codegen] #53  {1:D}                    convert double -> object 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   415
[codegen] #54  {1:O}                ternary_exit_107c1f2f 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   416
[codegen] #55  {1:O}                    return object 
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   417
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   418
shows a ternary node being generated for the sequence "return x > 0 ?
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   419
x : -x"
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   420
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   421
The first number on the log line is a unique monotonically increasing
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   422
emission id per bytecode. There is no guarantee this is the same id
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   423
between runs.  depending on non deterministic code
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   424
execution/compilation, but for small applications it usually is. If
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   425
the system variable -Dnashorn.codegen.debug.trace=<x> is set, where x
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   426
is a bytecode emission id, a stack trace will be shown as the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   427
particular bytecode is about to be emitted. This can be a quick way to
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   428
determine where it comes from without attaching the debugger. "Who
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   429
generated that neg?"
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   430
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   431
The --log=codegen option is equivalent to setting the system variable
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   432
"nashorn.codegen.debug" to true.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   433
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   434
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   435
* lower
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   436
16201
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   437
This is the first lowering pass.
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   438
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   439
Lower is a code generation pass that turns high level IR nodes into
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   440
lower level one, for example substituting comparisons to RuntimeNodes
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   441
and inlining finally blocks.
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   442
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   443
Lower is also responsible for determining control flow information
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   444
like end points.
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   445
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   446
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   447
* attr
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   448
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   449
The lowering annotates a FunctionNode with symbols for each identifier
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   450
and transforms high level constructs into lower level ones, that the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   451
CodeGenerator consumes.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   452
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   453
Lower logging typically outputs things like post pass actions,
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   454
insertions of casts because symbol types have been changed and type
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   455
specialization information. Currently very little info is generated by
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   456
this logger. This will probably change.
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   457
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   458
16201
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   459
* finalize
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   460
16201
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   461
This --log=finalize log option outputs information for type finalization,
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   462
the third tier of the compiler. This means things like placement of 
889ddb179cdf 8007062: Split Lower up into Lower/Attr/FinalizeTypes. Integrate AccessSpecalizer into FinalizeTypes.
lagergren
parents: 16168
diff changeset
   463
specialized scope nodes or explicit conversions. 
16147
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   464
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   465
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   466
* fields
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   467
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   468
The --log=fields option (at info level) is equivalent to setting the
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   469
system variable "nashorn.fields.debug" to true. At the info level it
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   470
will only show info about type assumptions that were invalidated. If
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   471
the level is set to finest, it will also trace every AccessorProperty
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   472
getter and setter in the program, show arguments, return values
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   473
etc. It will also show the internal representation of respective field
e63b63819133 8005403: Open-source Nashorn
jlaskey
parents:
diff changeset
   474
(Object in the normal case, unless running with the dual field
16168
f0c208287983 8005976: Break out AccessSpecializer into one pass before CodeGenerator instead of iterative applications from CodeGenerator
lagergren
parents: 16152
diff changeset
   475
representation)