diff options
author | Ulf Hermann <ulf.hermann@qt.io> | 2019-09-09 16:02:45 +0200 |
---|---|---|
committer | Ulf Hermann <ulf.hermann@qt.io> | 2019-09-13 15:56:24 +0200 |
commit | d1071eed3f4c72b553903b47a7afca955b62f029 (patch) | |
tree | 12e3ed73613ca6aa46f51e2185d5a2cf1b846c33 /src/qml/doc | |
parent | ba30971c7e3a89a79f0b91618bf95f515d8a16d1 (diff) |
Doc: Document the most relevant QV4_* environment variables
Change-Id: I5150b39321967708b682eae70e917ddff7bb6b8b
Reviewed-by: Fabian Kosmale <fabian.kosmale@qt.io>
Reviewed-by: Kavindra Palaraja <kpalaraja@luxoft.com>
Diffstat (limited to 'src/qml/doc')
-rw-r--r-- | src/qml/doc/src/javascript/finetuning.qdoc | 104 | ||||
-rw-r--r-- | src/qml/doc/src/javascript/topic.qdoc | 7 |
2 files changed, 111 insertions, 0 deletions
diff --git a/src/qml/doc/src/javascript/finetuning.qdoc b/src/qml/doc/src/javascript/finetuning.qdoc new file mode 100644 index 0000000000..fcd710db8b --- /dev/null +++ b/src/qml/doc/src/javascript/finetuning.qdoc @@ -0,0 +1,104 @@ +/**************************************************************************** +** +** 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 1234. If it contains a + number, this environment variable overrides the maximum call depth. Beware that the + recursion limit when compiling JavaScript is not affected. + \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 + +*/ + diff --git a/src/qml/doc/src/javascript/topic.qdoc b/src/qml/doc/src/javascript/topic.qdoc index 0c06e14b4c..05fb1ddfdc 100644 --- a/src/qml/doc/src/javascript/topic.qdoc +++ b/src/qml/doc/src/javascript/topic.qdoc @@ -81,4 +81,11 @@ These limitations and extensions are documented in the description of the \l{qtqml-javascript-hostenvironment.html}{JavaScript Host Environment} provided by the QML engine. +\section1 Fine Tuning the JavaScript engine + +For specific use cases you may want to override some of the parameters the +JavaScript engine uses for handling memory and compiling JavaScript. See +\l{qtqml-javascript-finetuning.html}{Fine Tuning the JavaScript engine} for +more information on these parameters. + */ |