QtScript: Add API for reporting additional memory costs

QScriptEngine::reportAdditionalMemoryCost(int).

This function provides the ability to give a hint to the engine
that it should perhaps trigger garbage collection sooner rather
than later.

For example, if you've implemented a JS ByteArray class that
wraps a QByteArray, and a user constructs a few hundred
temporary ByteArray objects of large sizes, failure to report
the additional memory cost may cause the application's memory
consumption to grow and grow (because the script engine thinks
they are "cheap" objects, the GC won't kick in).

Reporting the correct size can be difficult (or impossible) in
some cases. For example, it's difficult to predict the total
amount of system memory & resources consumed by a QImage.
But even reporting a heuristic / approximate cost can be better
than reporting no cost.

Task-number: QTBUG-6238
Reviewed-by: Simon Hausmann

4 files changed, 62 insertions, 3 deletions

diff --git a/src/script/api/qscriptengine.cpp b/src/script/api/qscriptengine.cpp
index 2650d7f..b322523 100644
--- a/src/script/api/qscriptengine.cpp
+++ b/src/script/api/qscriptengine.cpp
@@ -260,6 +260,22 @@ QT_BEGIN_NAMESPACE
   whether an engine is currently running a script by calling
   isEvaluating().
 
+  \section1 Garbage Collection
+
+  Qt Script objects may be garbage collected when they are no longer
+  referenced. There is no guarantee as to when automatic garbage
+  collection will take place.
+
+  The collectGarbage() function can be called to explicitly request
+  garbage collection.
+
+  The reportAdditionalMemoryCost() function can be called to indicate
+  that a Qt Script object occupies memory that isn't managed by the
+  scripting environment. Reporting the additional cost makes it more
+  likely that the garbage collector will be triggered. This can be
+  useful, for example, when many custom, native Qt Script objects are
+  allocated.
+
   \section1 Core Debugging/Tracing Facilities
 
   Since Qt 4.4, you can be notified of events pertaining to script
@@ -1193,6 +1209,12 @@ void QScriptEnginePrivate::collectGarbage()
     globalData->heap.collectAllGarbage();
 }
 
+void QScriptEnginePrivate::reportAdditionalMemoryCost(int size)
+{
+    if (size > 0)
+        globalData->heap.reportExtraMemoryCost(size);
+}
+
 QScript::TimeoutCheckerProxy *QScriptEnginePrivate::timeoutChecker() const
 {
     return static_cast<QScript::TimeoutCheckerProxy*>(globalData->timeoutChecker);
@@ -1990,7 +2012,7 @@ QScriptValue QScriptEngine::newRegExp(const QRegExp &regexp)
   prototype; otherwise, the prototype will be the Object prototype
   object.
 
-  \sa setDefaultPrototype(), QScriptValue::toVariant()
+  \sa setDefaultPrototype(), QScriptValue::toVariant(), reportAdditionalMemoryCost()
 */
 QScriptValue QScriptEngine::newVariant(const QVariant &value)
 {
@@ -2021,6 +2043,8 @@ QScriptValue QScriptEngine::newVariant(const QVariant &value)
   true), you can pass QScriptContext::thisObject() (the default
   constructed script object) to this function to initialize the new
   object.
+
+  \sa reportAdditionalMemoryCost()
 */
 QScriptValue QScriptEngine::newVariant(const QScriptValue &object,
                                        const QVariant &value)
@@ -2051,7 +2075,7 @@ QScriptValue QScriptEngine::newVariant(const QScriptValue &object,
   wrapper object (either by script code or C++) will result in a
   script exception.
 
-  \sa QScriptValue::toQObject()
+  \sa QScriptValue::toQObject(), reportAdditionalMemoryCost()
 */
 QScriptValue QScriptEngine::newQObject(QObject *object, ValueOwnership ownership,
                                        const QObjectWrapOptions &options)
@@ -2085,6 +2109,8 @@ QScriptValue QScriptEngine::newQObject(QObject *object, ValueOwnership ownership
   (QScriptContext::isCalledAsConstructor() returns true), you can pass
   QScriptContext::thisObject() (the default constructed script object)
   to this function to initialize the new object.
+
+  \sa reportAdditionalMemoryCost()
 */
 QScriptValue QScriptEngine::newQObject(const QScriptValue &scriptObject,
                                        QObject *qtObject,
@@ -2138,7 +2164,7 @@ QScriptValue QScriptEngine::newObject()
   \a data, if specified, is set as the internal data of the
   new object (using QScriptValue::setData()).
 
-  \sa QScriptValue::scriptClass()
+  \sa QScriptValue::scriptClass(), reportAdditionalMemoryCost()
 */
 QScriptValue QScriptEngine::newObject(QScriptClass *scriptClass,
                                       const QScriptValue &data)
@@ -3844,6 +3870,8 @@ QStringList QScriptEngine::importedExtensions() const
   been created). However, you can call this function to explicitly
   request that garbage collection should be performed as soon as
   possible.
+
+  \sa reportAdditionalMemoryCost()
 */
 void QScriptEngine::collectGarbage()
 {
@@ -3852,6 +3880,33 @@ void QScriptEngine::collectGarbage()
 }
 
 /*!
+  \since 4.7
+
+  Reports an additional memory cost of the given \a size, measured in
+  bytes, to the garbage collector.
+
+  This function can be called to indicate that a Qt Script object has
+  memory associated with it that isn't managed by Qt Script itself.
+  Reporting the additional cost makes it more likely that the garbage
+  collector will be triggered.
+
+  Note that if the additional memory is shared with objects outside
+  the scripting environment, the cost should not be reported, since
+  collecting the Qt Script object would not cause the memory to be
+  freed anyway.
+
+  Negative \a size values are ignored, i.e. this function can't be
+  used to report that the additional memory has been deallocated.
+
+  \sa collectGarbage()
+*/
+void QScriptEngine::reportAdditionalMemoryCost(int size)
+{
+    Q_D(QScriptEngine);
+    d->reportAdditionalMemoryCost(size);
+}
+
+/*!
 
   Sets the interval between calls to QCoreApplication::processEvents
   to \a interval milliseconds.
diff --git a/src/script/api/qscriptengine.h b/src/script/api/qscriptengine.h
index 76461bc..3212ed5 100644
--- a/src/script/api/qscriptengine.h
+++ b/src/script/api/qscriptengine.h
@@ -233,6 +233,7 @@ public:
     QStringList importedExtensions() const;
 
     void collectGarbage();
+    void reportAdditionalMemoryCost(int size);
 
     void setProcessEventsInterval(int interval);
     int processEventsInterval() const;
diff --git a/src/script/api/qscriptengine_p.h b/src/script/api/qscriptengine_p.h
index 47e5d8a..70ab7c9 100644
--- a/src/script/api/qscriptengine_p.h
+++ b/src/script/api/qscriptengine_p.h
@@ -244,6 +244,7 @@ public:
     void mark(JSC::MarkStack& markStack);
     bool isCollecting() const;
     void collectGarbage();
+    void reportAdditionalMemoryCost(int size);
 
     //flags that we set on the return value register for native function. (ie when codeBlock is 0)
     enum ContextFlags {
diff --git a/src/script/api/qscriptvalue.cpp b/src/script/api/qscriptvalue.cpp
index 3fe0e7d..4cd84a4 100644
--- a/src/script/api/qscriptvalue.cpp
+++ b/src/script/api/qscriptvalue.cpp
@@ -1970,6 +1970,8 @@ QScriptValue QScriptValue::data() const
   this function to set object-specific data that won't be directly
   accessible to scripts, but may be retrieved in C++ using the data()
   function.
+
+  \sa QScriptEngine::reportAdditionalMemoryCost()
 */
 void QScriptValue::setData(const QScriptValue &data)
 {