Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
Loading...
Searching...
No Matches
finetuning.qdoc
Go to the documentation of this file.
1// Copyright (C) 2019 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
3/*!
4
5\page qtqml-javascript-finetuning.html
6\meta {keywords} {qmltopic}
7\title Configuring the JavaScript Engine
8\brief Describes the environment variables available, to control how Javascript is run.
9
10Running JavaScript code can be influenced by a few environment variables, particularly:
11
12\table
13 \header
14 \li Environment Variable
15 \li Description
16 \row
17 \li \c{QV4_JIT_CALL_THRESHOLD}
18 \li The JavaScript engine contains a Just-In-Time compiler (JIT). The JIT will compile
19 frequently run JavaScript functions into machine code to run faster. This
20 environment variable determines how often a function needs to be run to be
21 considered for JIT compilation. The default value is 3 times.
22 \row
23 \li \c{QV4_FORCE_INTERPRETER}
24 \li Setting this environment variable runs all functions and expressions through the
25 interpreter. The JIT is never used, no matter how often a function or expression is
26 called. Functions and expressions may still be compiled ahead of time using
27 \l{qmlcachegen} or \l{qmlsc}, but only the generated byte code is used at run time. Any
28 generated C++ code and the machine code resulting from it is ignored.
29 \row
30 \li \c{QV4_FAIL_ON_INVALID_AOT}
31 \li QML code compiled to C++ is validated at runtime. If this validation fails, by default,
32 the code is then interpreted instead of running as native code. With this environment
33 variable set, a validation failure terminates the program instead. This can be useful to
34 ensure that all the code that can run as native code does.
35 \row
36 \li \c{QV4_SKIP_AOT_VALIDATION}
37 \li This environment variable skips the runtime validation of C++ code generated for
38 compiled QML code. This can be used to avoid the overhead of the validation itself.
39 Note that this only skips the validation. It will not prevent the validation code itself
40 from being generated by qmlcachegen. For that use the \c{NO_GENERATE_AOT_VALIDATION}
41 option of \l{qt_add_qml_module}.
42 \row
43 \li \c{QV4_JS_MAX_STACK_SIZE}
44 \li The JavaScript engine reserves a special memory area as a stack to run JavaScript.
45 This stack is separate from the C++ stack. Usually this area is 4MB in size. If this
46 environment variable contains a number, the JavaScript engine interprets it as the
47 size of the memory area, in bytes, to be allocated as the JavaScript stack.
48 \row
49 \li \c{QV4_GC_MAX_STACK_SIZE}
50 \li In addition to the regular JavaScript stack, the JavaScript engine keeps another stack
51 for the garbage collector, usually 2MB of memory. If the garbage collector needs to
52 handle an excessive number of objects at the same time, this stack might overrun.
53 If it contains a number, this environment variable is interpreted as the size in bytes
54 of the memory area that will be allocated as the stack for the garbage collector.
55 \row
56 \li \c{QV4_STACK_SOFT_LIMIT}
57 \li When this environment variable is set, the JavaScript engine will throw a "RangeError:
58 Maximum call stack size exceeded" exception once the call stack usage reaches the
59 defined soft limit. If the variable is not set, the engine defaults to runtime detected
60 or Qt predefined limits depending on the OS.
61
62 \row
63 \li \c{QV4_CRASH_ON_STACKOVERFLOW}
64 \li Usually the JavaScript engine tries to catch C++ stack overflows caused by
65 excessively recursive JavaScript code, and generates a non-fatal error condition.
66 There are separate recursion checks for compiling JavaScript and running JavaScript. A
67 stack overflow when compiling JavaScript indicates that the code contains deeply nested
68 objects and functions. A stack overflow at run-time indicates that the code results in
69 a deeply recursive program. The check for this is only indirectly related to the
70 JavaScript stack size mentioned above, as each JavaScript function call consumes stack
71 space on both, the C++ and the JavaScript stack. The code that checks for excessive
72 recursion is necessarily conservative, as the available stack size depends on many
73 factors and can often be customized by the user. With this environment variable set, the
74 JavaScript engine does not check for stack overflows when compiling or running
75 JavaScript and will not generate exceptions for them. Instead, when the stack overflows
76 the program attempts an invalid memory access. This most likely terminates the
77 program. In turn, the program gets to use up all the stack space the operating system
78 can provide.
79 \warning malicious code may be able to evade the termination and access unexpected
80 memory locations this way.
81 \row
82 \li \c{QV4_MAX_CALL_DEPTH}
83 \li Stack overflows when running (as opposed to compiling) JavaScript are prevented by
84 controlling the call depth: the number of nested function invocations. By
85 default, an exception is generated if the call depth exceeds a maximum number tuned
86 to the platform's default stack size. If the \c{QV4_MAX_CALL_DEPTH} environment
87 variable contains a number, this number is used as maximum call depth. Beware that
88 the recursion limit when compiling JavaScript is not affected. The default maximum
89 call depth is 1234 on most platforms. On QNX it is 640 because on QNX the default
90 stack size is smaller than on most platforms.
91 \row
92 \li \target{QV4_GC_TIMELIMIT}
93 \c{QV4_GC_TIMELIMIT}
94 \li This value is used to tell the engine how much time it should spend in each
95 incremental garbage collection step. It can either be a positive number,
96 specifying the timelimit in milliseconds, or 0. If the value is 0,
97 garbage collection becomes non-incremental.
98 \row
99 \li \c{QV4_MM_AGGRESSIVE_GC}
100 \li Setting this environment variable runs the garbage collector before each memory
101 allocation. This is very expensive at run-time, but it quickly uncovers many memory
102 management errors, for example the manual deletion of an object belonging to the QML
103 engine from C++.
104 \row
105 \li \c{QV4_MM_CROSS_VALIDATE_INCREMENTAL_GC}
106 \li Setting this environment variable runs additional debug steps to
107 recognize cases where the incremental garbage collector is
108 misbehaving by comparing its behavior to that of the non-incremetal
109 garbage collector.
110 \row
111 \li \c{QV4_PROFILE_WRITE_PERF_MAP}
112 \li On Linux, the \c perf utility can be used to profile programs. To analyze JIT-compiled
113 JavaScript functions, it needs to know about their names and locations in memory. To
114 provide this information, there's a convention to create a special file called
115 \c{perf-<pid>.map} in \e{/tmp} which perf then reads. This environment variable, if
116 set, causes the JIT to generate this file.
117 \row
118 \li \c{QV4_SHOW_BYTECODE}
119 \li Outputs the IR bytecode generated by Qt to the console.
120 Has to be combined with \c{QML_DISABLE_DISK_CACHE} or already cached bytecode will not
121 be shown.
122 \row
123 \li \c{QV4_DUMP_BASIC_BLOCKS}
124 \li Outputs the basic blocks of each function compiled ahead of time. The details of the
125 blocks are printed to the console. Additionally, control flow graphs with the byte code
126 for each block are generated in the DOT format for each compiled function. The value of
127 \c {QV4_DUMP_BASIC_BLOCKS} is used as the path to the folder where the DOT files should
128 be generated. If the path is any of ["-", "1", "true"] or if files can't be opened,
129 the graphs are dumped to stdout instead.
130 \row
131 \li \c{QV4_VALIDATE_BASIC_BLOCKS}
132 \li Performs checks on the basic blocks of a function compiled ahead of time to validate
133 its structure and coherence. If the validation fails, an error message is printed to
134 the console.
135\endtable
136
137\l{The QML Disk Cache} accepts further environment variables that allow fine tuning its behavior.
138In particular \c{QML_DISABLE_DISK_CACHE} may be useful for debugging.
139
140*/