diff options
Diffstat (limited to 'src/qml/doc/src/javascript')
-rw-r--r-- | src/qml/doc/src/javascript/expressions.qdoc | 4 | ||||
-rw-r--r-- | src/qml/doc/src/javascript/finetuning.qdoc | 104 | ||||
-rw-r--r-- | src/qml/doc/src/javascript/hostenvironment.qdoc | 2 | ||||
-rw-r--r-- | src/qml/doc/src/javascript/imports.qdoc | 2 | ||||
-rw-r--r-- | src/qml/doc/src/javascript/topic.qdoc | 7 |
5 files changed, 116 insertions, 3 deletions
diff --git a/src/qml/doc/src/javascript/expressions.qdoc b/src/qml/doc/src/javascript/expressions.qdoc index b83127389a..b27bde3cf9 100644 --- a/src/qml/doc/src/javascript/expressions.qdoc +++ b/src/qml/doc/src/javascript/expressions.qdoc @@ -147,7 +147,7 @@ Rectangle { TapHandler { id: inputHandler - onTapped: { + onTapped: { // arbitrary JavaScript expression console.log("Tapped!") } @@ -339,7 +339,7 @@ For the following examples, imagine that we have defined the following class: and that we have registered it with the QML type-system as follows: -\snippet qml/integrating-javascript/scarceresources/avatarExample.cpp 0 +\snippet qml/integrating-javascript/scarceresources/scarceresources.pro 0 The AvatarExample class has a property which is a pixmap. When the property is accessed in JavaScript scope, a copy of the resource will be created and 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/hostenvironment.qdoc b/src/qml/doc/src/javascript/hostenvironment.qdoc index c22c392b80..bc75f843fb 100644 --- a/src/qml/doc/src/javascript/hostenvironment.qdoc +++ b/src/qml/doc/src/javascript/hostenvironment.qdoc @@ -42,6 +42,8 @@ Like a browser or server-side JavaScript environment, the QML runtime implements all of the built-in types and functions defined by the standard, such as Object, Array, and Math. The QML runtime implements the 7th edition of the standard. +Since Qt 5.15 \l{Nullish Coalescing} is also implemented in the QML runtime. + The standard ECMAScript built-ins are not explicitly documented in the QML documentation. For more information on their use, please refer to the ECMA-262 7th edition standard or one of the many online JavaScript reference and tutorial sites, such as the \l{W3Schools JavaScript Reference} (JavaScript Objects diff --git a/src/qml/doc/src/javascript/imports.qdoc b/src/qml/doc/src/javascript/imports.qdoc index 8e26c4aadd..9227f0e604 100644 --- a/src/qml/doc/src/javascript/imports.qdoc +++ b/src/qml/doc/src/javascript/imports.qdoc @@ -154,7 +154,7 @@ var importedEnumValue = JsQtTest.MyQmlObject.EnumValue3 \endcode In particular, this may be useful in order to access functionality provided -via a singleton type; see qmlRegisterSingletonType() for more information. +via a singleton type; see QML_SINGLETON for more information. \note The .import syntax doesn't work for scripts used in the \l {WorkerScript} */ 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. + */ |