1// Copyright (C) 2019 The Qt Company Ltd.
2// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR GFDL-1.3-no-invariants-only
5\page qtqml-javascript-finetuning.html
6\title Configuring the JavaScript Engine
7\brief Describes the environment variables available, to control how Javascript is run.
9Running JavaScript code can be influenced by a few environment variables, particularly:
13 \li Environment Variable
16 \li \c{QV4_JIT_CALL_THRESHOLD}
17 \li The JavaScript engine contains a Just-In-Time compiler (JIT). The JIT will compile
18 frequently run JavaScript functions into machine code to run faster. This
19 environment variable determines how often a function needs to be run to be
20 considered for JIT compilation. The default value is 3 times.
22 \li \c{QV4_FORCE_INTERPRETER}
23 \li Setting this environment variable runs all functions and expressions through the
24 interpreter. The JIT is never used, no matter how often a function or expression is
25 called. Functions and expressions may still be compiled ahead of time using
26 \l{qmlcachegen} or \l{qmlsc}, but only the generated byte code is used at run time. Any
27 generated C++ code and the machine code resulting from it is ignored.
29 \li \c{QV4_JS_MAX_STACK_SIZE}
30 \li The JavaScript engine reserves a special memory area as a stack to run JavaScript.
31 This stack is separate from the C++ stack. Usually this area is 4MB in size. If this
32 environment variable contains a number, the JavaScript engine interprets it as the
33 size of the memory area, in bytes, to be allocated as the JavaScript stack.
35 \li \c{QV4_GC_MAX_STACK_SIZE}
36 \li In addition to the regular JavaScript stack, the JavaScript engine keeps another stack
37 for the garbage collector, usually 2MB of memory. If the garbage collector needs to
38 handle an excessive number of objects at the same time, this stack might overrun.
39 If it contains a number, this environment variable is interpreted as the size in bytes
40 of the memory area that will be allocated as the stack for the garbage collector.
42 \li \c{QV4_CRASH_ON_STACKOVERFLOW}
43 \li Usually the JavaScript engine tries to catch C++ stack overflows caused by
44 excessively recursive JavaScript code, and generates a non-fatal error condition.
45 There are separate recursion checks for compiling JavaScript and running JavaScript. A
46 stack overflow when compiling JavaScript indicates that the code contains deeply nested
47 objects and functions. A stack overflow at run-time indicates that the code results in
48 a deeply recursive program. The check for this is only indirectly related to the
49 JavaScript stack size mentioned above, as each JavaScript function call consumes stack
50 space on both, the C++ and the JavaScript stack. The code that checks for excessive
51 recursion is necessarily conservative, as the available stack size depends on many
52 factors and can often be customized by the user. With this environment variable set, the
53 JavaScript engine does not check for stack overflows when compiling or running
54 JavaScript and will not generate exceptions for them. Instead, when the stack overflows
55 the program attempts an invalid memory access. This most likely terminates the
56 program. In turn, the program gets to use up all the stack space the operating system
58 \warning malicious code may be able to evade the termination and access unexpected
59 memory locations this way.
61 \li \c{QV4_MAX_CALL_DEPTH}
62 \li Stack overflows when running (as opposed to compiling) JavaScript are prevented by
63 controlling the call depth: the number of nested function invocations. By
64 default, an exception is generated if the call depth exceeds a maximum number tuned
65 to the platform's default stack size. If the \c{QV4_MAX_CALL_DEPTH} environment
66 variable contains a number, this number is used as maximum call depth. Beware that
67 the recursion limit when compiling JavaScript is not affected. The default maximum
68 call depth is 1234 on most platforms. On QNX it is 640 because on QNX the default
69 stack size is smaller than on most platforms.
71 \li \c{QV4_MM_AGGRESSIVE_GC}
72 \li Setting this environment variable runs the garbage collector before each memory
73 allocation. This is very expensive at run-time, but it quickly uncovers many memory
74 management errors, for example the manual deletion of an object belonging to the QML
77 \li \c{QV4_PROFILE_WRITE_PERF_MAP}
78 \li On Linux, the \c perf utility can be used to profile programs. To analyze JIT-compiled
79 JavaScript functions, it needs to know about their names and locations in memory. To
80 provide this information, there's a convention to create a special file called
81 \c{perf-<pid>.map} in \e{/tmp} which perf then reads. This environment variable, if
82 set, causes the JIT to generate this file.
84 \li \c{QV4_SHOW_BYTECODE}
85 \li Outputs the IR bytecode generated by Qt to the console.
86 Has to be combined with \c{QML_DISABLE_DISK_CACHE} or already cached bytecode will not
89 \li \c{QV4_DUMP_BASIC_BLOCKS}
90 \li Outputs the basic blocks of each function compiled ahead of time. The details of the
91 blocks are printed to the console. Additionally, control flow graphs with the byte code
92 for each block are generated in the DOT format for each compiled function. The value of
93 \c {QV4_DUMP_BASIC_BLOCKS} is used as the path to the folder where the DOT files should
94 be generated. If the path is any of ["-", "1", "true"] or if files can't be opened,
95 the graphs are dumped to stdout instead.
97 \li \c{QV4_VALIDATE_BASIC_BLOCKS}
98 \li Performs checks on the basic blocks of a function compiled ahead of time to validate
99 its structure and coherence. If the validation fails, an error message is printed to
103\l{The QML Disk Cache} accepts further environment variables that allow fine tuning its behavior.
104In particular \c{QML_DISABLE_DISK_CACHE} may be useful for debugging.
1.10.0