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)
 {