1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
|
/****************************************************************************
**
** Copyright (C) 2019 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page qtqml-javascript-finetuning.html
\title Fine-tuning the JavaScript Engine
\brief Describes the environment variables available, to control how Javascript is run.
Running JavaScript code can be influenced by a few environment variables, particularly:
\table
\header
\li Environment Variable
\li Description
\row
\li \c{QV4_JIT_CALL_THRESHOLD}
\li The JavaScript engine contains a Just-In-Time compiler (JIT). The JIT will compile
frequently run JavaScript functions into machine code to run faster. This
environment variable determines how often a function needs to be run to be
considered for JIT compilation. The default value is 3 times.
\row
\li \c{QV4_FORCE_INTERPRETER}
\li Setting this environment variable disables the JIT and runs all
functions through the interpreter, no matter how often they are called.
\row
\li \c{QV4_JS_MAX_STACK_SIZE}
\li The JavaScript engine reserves a special memory area as a stack to run JavaScript.
This stack is separate from the C++ stack. Usually this area is 4MB in size. If this
environment variable contains a number, the JavaScript engine interprets it as the
size of the memory area, in bytes, to be allocated as the JavaScript stack.
\row
\li \c{QV4_GC_MAX_STACK_SIZE}
\li In addition to the regular JavaScript stack, the JavaScript engine keeps another stack
for the garbage collector, usually 2MB of memory. If the garbage collector needs to
handle an excessive number of objects at the same time, this stack might overrun.
If it contains a number, this environment variable is interpreted as the size in bytes
of the memory area that will be allocated as the stack for the garbage collector.
\row
\li \c{QV4_CRASH_ON_STACKOVERFLOW}
\li Usually the JavaScript engine tries to catch C++ stack overflows caused by
excessively recursive JavaScript code, and generates a non-fatal error condition.
There are separate recursion checks for compiling JavaScript and running JavaScript. A
stack overflow when compiling JavaScript indicates that the code contains deeply nested
objects and functions. A stack overflow at run-time indicates that the code results in
a deeply recursive program. The check for this is only indirectly related to the
JavaScript stack size mentioned above, as each JavaScript function call consumes stack
space on both, the C++ and the JavaScript stack. The code that checks for excessive
recursion is necessarily conservative, as the available stack size depends on many
factors and can often be customized by the user. With this environment variable set, the
JavaScript engine does not check for stack overflows when compiling or running
JavaScript and will not generate exceptions for them. Instead, when the stack overflows
the program attempts an invalid memory access. This most likely terminates the
program. In turn, the program gets to use up all the stack space the operating system
can provide.
\warning malicious code may be able to evade the termination and access unexpected
memory locations this way.
\row
\li \c{QV4_MAX_CALL_DEPTH}
\li Stack overflows when running (as opposed to compiling) JavaScript are prevented by
controlling the call depth: the number of nested function invocations. By
default, an exception is generated if the call depth exceeds a maximum number tuned
to the platform's default stack size. If the \c{QV4_MAX_CALL_DEPTH} environment
variable contains a number, this number is used as maximum call depth. Beware that
the recursion limit when compiling JavaScript is not affected. The default maximum
call depth is 1234 on most platforms. On QNX it is 640 because on QNX the default
stack size is smaller than on most platforms.
\row
\li \c{QV4_MM_AGGRESSIVE_GC}
\li Setting this environment variable runs the garbage collector before each memory
allocation. This is very expensive at run-time, but it quickly uncovers many memory
management errors, for example the manual deletion of an object belonging to the QML
engine from C++.
\row
\li \c{QV4_PROFILE_WRITE_PERF_MAP}
\li On Linux, the \c perf utility can be used to profile programs. To analyze JIT-compiled
JavaScript functions, it needs to know about their names and locations in memory. To
provide this information, there's a convention to create a special file called
\c{perf-<pid>.map} in \e{/tmp} which perf then reads. This environment variable, if
set, causes the JIT to generate this file.
\endtable
*/
|
