Skip to content

Commit

Permalink
Ensure that scarce resources work with var properties
Browse files Browse the repository at this point in the history 
Now that we have a new property type which stores JavaScript handles,
we need to ensure that scarce resources can be used with them.

Task-number: QMLNG-18
Task-number: QTBUG-21843
Change-Id: I4a920ae39e7d33cf5e33362e5e0ee21c74cb35e3
Reviewed-by: Martin Jones <martin.jones@nokia.com>
  • Loading branch information
Chris Adams authored and Qt by Nokia committed Dec 6, 2011
1 parent 8601f34 commit 564d580
Show file tree
Hide file tree
Showing 61 changed files with 1,606 additions and 246 deletions.
13 changes: 13 additions & 0 deletions doc/src/declarative/basictypes.qdoc
View file
Expand Up @@ -479,6 +479,19 @@
}
\endqml

A \c var type property can also hold an image or pixmap.
A \c var which contains a QPixmap or QImage is known as a
"scarce resource" and the declarative engine will attempt to
automatically release such resources after evaluation of any JavaScript
expression which requires one to be copied has completed.

Clients may explicitly release such a scarce resource by calling the
"destroy" method on the \c var property from within JavaScript. They
may also explicitly preserve the scarce resource by calling the
"preserve" method on the \c var property from within JavaScript.
For more information regarding the usage of a scarce resource, please
see \l{Scarce Resources in JavaScript}.

\sa {QML Basic Types}
*/

Expand Down
172 changes: 36 additions & 136 deletions doc/src/declarative/javascriptblocks.qdoc
View file
Expand Up @@ -362,7 +362,7 @@ Item {

\section1 Scarce Resources in JavaScript

As described in the documentation for \l{QML Basic Types}, a \c variant type
As described in the documentation for \l{QML Basic Types}, a \c var type
property may hold a "scarce resource" (image or pixmap). There are several
important semantics of scarce resources which should be noted:

Expand All @@ -379,30 +379,12 @@ may be necessary for clients to manually preserve or destroy resources for
themselves.

For the following examples, imagine that we have defined the following class:
\code
class AvatarExample : public QObject
{
Q_OBJECT
Q_PROPERTY(QPixmap avatar READ avatar WRITE setAvatar NOTIFY avatarChanged)
public:
AvatarExample(QObject *parent = 0) : QObject(parent), m_value(100, 100) { m_value.fill(Qt::blue); }
~AvatarExample() {}

QPixmap avatar() const { return m_value; }
void setAvatar(QPixmap v) { m_value = v; emit avatarChanged(); }

signals:
void avatarChanged();

private:
QPixmap m_value;
};
\endcode

\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.h 0

and that we have registered it with the QML type-system as follows:
\code
qmlRegisterType<AvatarExample>("Qt.example", 1, 0, "AvatarExample");
\endcode

\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 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
Expand All @@ -414,141 +396,59 @@ unless the client explicitly preserves it.

\section2 Example One: Automatic Release

In this example, the resource will be automatically
In the following example, the scarce resource will be automatically released
after the binding evaluation is complete.

\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleOne.qml 0

\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 1

\section2 Example Two: Automatic Release Prevented By Reference

In this example, the resource will not be automatically
released after the binding expression evaluation is
complete.
complete, because there is a property var referencing the
scarce resource.

\qml
// exampleOne.qml
import QtQuick 1.0
import Qt.example 1.0

QtObject {
property AvatarExample a;
a: AvatarExample { id: example }
property variant avatar: example.avatar
}
\endqml
\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleTwo.qml 0

\code
QDeclarativeComponent component(&engine, "exampleOne.qml");
QObject *object = component.create();
// The scarce resource will have been released automatically
// after the binding expression was evaluated.
// Since the scarce resource was not released explicitly prior
// to the binding expression being evaluated, we get the
// expected result:
//object->property("scarceResourceCopy").isValid() == true
delete object;
\endcode
\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 2

\section2 Example Two: Explicit Preservation
\section2 Example Three: Explicit Preservation

In this example, the resource must be explicitly preserved in order
to prevent the declarative engine from automatically releasing the
resource after evaluation of the imported script.

\code
// exampleTwo.js
.import Qt.example 1.0 as QtExample

var component = Qt.createComponent("exampleOne.qml");
var exampleOneElement = component.createObject(null);
var avatarExample = exampleOneElement.a;
var retn = avatarExample.avatar;

// without the following call, the scarce resource held
// by retn would be automatically released by the engine
// after the import statement in exampleTwo.qml, prior
// to the variable assignment.
retn.preserve();

function importAvatar() {
return retn;
}
\endcode
\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.js 0

\qml
// exampleTwo.qml
import QtQuick 1.0
import Qt.example 1.0
import "exampleTwo.js" as ExampleTwoJs
\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleThree.qml 0

QtObject {
property variant avatar: ExampleTwoJs.importAvatar()
}
\endqml
\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 3

\code
QDeclarativeComponent component(&engine, "exampleTwo.qml");
QObject *object = component.create();
// The resource was preserved explicitly during evaluation of the
// JavaScript expression. Thus, during property assignment, the
// scarce resource was still valid, and so we get the expected result:
//object->property("avatar").isValid() == true
// The scarce resource may not have been cleaned up by the JS GC yet;
// it will continue to consume system resources until the JS GC runs.
delete object;
\endcode

\section2 Example Three: Explicit Destruction
\section2 Example Four: Explicit Destruction

In the following example, we release (via destroy()) an explicitly preserved
scarce resource variant. This example shows how a client may free system
resources by releasing the scarce resource held in a JavaScript object, if
required, during evaluation of a JavaScript expression.

\code
// exampleThree.js
.import Qt.example 1.0 as QtExample
\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.js 0

var component = Qt.createComponent("exampleOne.qml");
var exampleOneElement = component.createObject(null);
var avatarExample = exampleOneElement.a;
var retn = avatarExample.avatar;
retn.preserve();
\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFour.qml 0

function importAvatar() {
return retn;
}
\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 4

function releaseAvatar() {
retn.destroy();
}
\endcode
\section2 Example Five: Explicit Destruction And JavaScript References

\qml
// exampleThree.qml
import QtQuick 1.0
import Qt.example 1.0
import "exampleThree.js" as ExampleThreeJs

QtObject {
property variant avatarOne
property variant avatarTwo

Component.onCompleted: {
avatarOne = ExampleThreeJs.importAvatar(); // valid at this stage
ExampleThreeJs.releaseAvatar(); // explicit release
avatarTwo = ExampleThreeJs.importAvatar(); // invalid at this stage
}
}
\endqml
One thing to be aware of when using "var" type properties is that they
hold references to JavaScript objects. As such, if multiple references
to one scarce resource is held, and the client calls destroy() on one
of those references (to explicitly release the scarce resource), all of
the references will be affected.

\code
QDeclarativeComponent component(&engine, "exampleThree.qml");
QObject *object = component.create();
// The scarce resource was explicitly preserved by the client during
// the evaluation of the imported script, and so the scarce resource
// remains valid until the explicit call to releaseAvatar(). As such,
// we get the expected results:
//object->property("avatarOne").isValid() == true
//object->property("avatarTwo").isValid() == false
// Because the scarce resource was released explicitly, it will no longer
// be consuming any system resources (beyond what a normal JS Object would;
// that small overhead will exist until the JS GC runs, as per any other
// JavaScript object).
delete object;
\endcode
\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/exampleFive.qml 0

\snippet doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp 5

*/
124 changes: 124 additions & 0 deletions doc/src/snippets/declarative/integrating-javascript/scarceresources/avatarExample.cpp
View file
@@ -0,0 +1,124 @@
/****************************************************************************
**
** Copyright (C) 2011 Nokia Corporation and/or its subsidiary(-ies).
** All rights reserved.
** Contact: Nokia Corporation (qt-info@nokia.com)
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:BSD$
** You may use this file under the terms of the BSD license as follows:
**
** "Redistribution and use in source and binary forms, with or without
** modification, are permitted provided that the following conditions are
** met:
** * Redistributions of source code must retain the above copyright
** notice, this list of conditions and the following disclaimer.
** * Redistributions in binary form must reproduce the above copyright
** notice, this list of conditions and the following disclaimer in
** the documentation and/or other materials provided with the
** distribution.
** * Neither the name of Nokia Corporation and its Subsidiary(-ies) nor
** the names of its contributors may be used to endorse or promote
** products derived from this software without specific prior written
** permission.
**
** THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
** "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
** LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
** A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
** OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
** SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
** LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
** DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
** THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
** (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
** OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
** $QT_END_LICENSE$
**
****************************************************************************/

#include "avatarExample.h"
#include <QDeclarativeEngine>
#include <QDeclarativeComponent>

void registerTypes()
{
//![0]
qmlRegisterType<AvatarExample>("Qt.example", 1, 0, "AvatarExample");
//![0]
}

void expectOne()
{
//![1]
QDeclarativeComponent component(&engine, "exampleOne.qml");
QObject *object = component.create();
// The scarce resource will have been released automatically
// by this point, after the binding expression was evaluated.
delete object;
//![1]
}

void expectTwo()
{
//![2]
QDeclarativeComponent component(&engine, "exampleTwo.qml");
QObject *object = component.create();
// The scarce resource will not have been released automatically
// after the binding expression was evaluated.
// Since the scarce resource was not released explicitly prior
// to the binding expression being evaluated, we get:
bool expectedResult = (object->property("avatar").isValid() == true);
delete object;
//![2]
}

void expectThree()
{
//![3]
QDeclarativeComponent component(&engine, "exampleThree.qml");
QObject *object = component.create();
// The resource was preserved explicitly during evaluation of the
// JavaScript expression. Thus, during property assignment, the
// scarce resource was still valid, and so we get:
bool expectedResult = (object->property("avatar").isValid() == true);
// The scarce resource will not be released until all references to
// the resource are released, and the JavaScript garbage collector runs.
delete object;
//![3]
}

void expectFour()
{
//![4]
QDeclarativeComponent component(&engine, "exampleFour.qml");
QObject *object = component.create();
// The scarce resource was explicitly preserved by the client during
// the importAvatar() function, and so the scarce resource
// remains valid until the explicit call to releaseAvatar(). As such,
// we get the expected results:
bool expectedResultOne = (object->property("avatarOne").isValid() == true);
bool expectedResultTwo = (object->property("avatarTwo").isValid() == false);
// Because the scarce resource referenced by avatarTwo was released explicitly,
// it will no longer be consuming any system resources (beyond what a normal
// JS Object would; that small overhead will exist until the JS GC runs, as per
// any other JavaScript object).
delete object;
//![4]
}

void expectFive()
{
//![5]
QDeclarativeComponent component(&engine, "exampleFive.qml");
QObject *object = component.create();
// We have the expected results:
bool expectedResultOne = (object->property("avatarOne").isValid() == false);
bool expectedResultTwo = (object->property("avatarTwo").isValid() == false);
// Because although only avatarTwo was explicitly released,
// avatarOne and avatarTwo were referencing the same
// scarce resource.
delete object;
//![5]
}

0 comments on commit 564d580

Please sign in to comment.