 |
Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
|
|
Qt
Internal/Contributor docs for the Qt SDK. Note: These are NOT official API docs; those are found at https://doc.qt.io/
|
An object that keeps track of the provenance of its owned value, allowing to reflect mutations on the original instance. More...
#include <qv4referenceobject_p.h>
Static Public Member Functions | |
| template<typename HeapObject> | |
| static bool | readReference (HeapObject *ref) |
| template<typename HeapObject> | |
| static bool | writeBack (HeapObject *ref, int internalIndex=AllProperties) |
| template<typename HeapObject> | |
| static HeapObject * | detached (HeapObject *ref) |
| Static Public Member Functions inherited from QV4::Object | |
| static ReturnedValue | getValue (const Value *thisObject, const Value &v, PropertyAttributes attrs) |
| static ReturnedValue | getValueAccessor (const Value *thisObject, const Value &v, PropertyAttributes attrs) |
| static ReturnedValue | checkedInstanceOf (ExecutionEngine *engine, const FunctionObject *typeObject, const Value &var) |
| Static Public Member Functions inherited from QV4::Managed | |
| static QString | typeToString (Type) |
| Static Public Member Functions inherited from QV4::Value | |
| static constexpr Value | fromStaticValue (StaticValue staticValue) |
| static constexpr Value | undefined () |
| static Value | fromHeapObject (HeapBasePtr m) |
| static bool | toBooleanImpl (Value val) |
| static double | toNumberImpl (Value v) |
| static Heap::String * | toString (ExecutionEngine *e, Value val) |
| static Heap::Object * | toObject (ExecutionEngine *e, Value val) |
| static constexpr Value | fromReturnedValue (ReturnedValue val) |
| static double | toInteger (double d) |
| static int | toInt32 (double d) |
| static unsigned int | toUInt32 (double d) |
| static constexpr Value | emptyValue () |
| static constexpr Value | fromBoolean (bool b) |
| static constexpr Value | fromInt32 (int i) |
| static constexpr Value | undefinedValue () |
| static constexpr Value | nullValue () |
| static Value | fromDouble (double d) |
| static Value | fromUInt32 (uint i) |
| Static Public Member Functions inherited from QV4::StaticValue | |
| static int | valueOffset () |
| static int | tagOffset () |
| static constexpr quint64 | tagValue (quint32 tag, quint32 value) |
| static constexpr quint64 | tagBitMask (TagBit bit) |
| static bool | integerCompatible (StaticValue a, StaticValue b) |
| static bool | bothDouble (StaticValue a, StaticValue b) |
| static QV4_NEARLY_ALWAYS_INLINE bool | isInt32 (double d) |
| static constexpr StaticValue | fromReturnedValue (ReturnedValue val) |
| static constexpr StaticValue | emptyValue () |
| static constexpr StaticValue | fromBoolean (bool b) |
| static constexpr StaticValue | fromInt32 (int i) |
| static constexpr StaticValue | undefinedValue () |
| static constexpr StaticValue | nullValue () |
| static StaticValue | fromDouble (double d) |
| static StaticValue | fromUInt32 (uint i) |
| static double | toInteger (double d) |
| static int | toInt32 (double d) |
| static unsigned int | toUInt32 (double d) |
An object that keeps track of the provenance of its owned value, allowing to reflect mutations on the original instance.
In QML, certain types are conceptually passed by value. Instances of those types are always copied when they are accessed or passed around.
Let those be "Copied Type"s.
For example, suppose that {foo} is an instance of a Copied Type that has a member {bar} that has some value {X}.
Consider the following example:
\qml import QtQuick
Item { Component.onCompleted: { foo.bar = Y console.log(foo.bar) } } \endqml
Where {Y} is some value that can inhabit {foo.bar} and whose stringified representation is distinguishable from {X}.
One might expect that a stringified representation of {Y} should be logged. Nonetheless, as {foo} is a Copied Type, accessing it creates a copy. The access to the {bar} member and its further mutation is performed on the copy that was created, and thus is not retained by the object that {foo} refers to.
If {copy} is an operation that performs a deep-copy of an object and returns it, the above snippet can be considered implicitly equivalent to the following:
\qml import QtQuick
Item { Component.onCompleted: { copy(foo).bar = Y console.log(copy(foo).bar) } } \endqml
This can generally be surprising as it stands in contrast to the effect that the above assignment would have if {foo} wasn't a Copied Type. Similarly, it stands in contrast to what one could expect from the outcome of the same assignment in a Javascript environment, where the mutation might be expected to generally be visible in later steps no matter the type of {foo}.
A ReferenceObject can be used to avoid this inconsistency by wrapping a value and providing a "write-back" mechanism that can reflect mutations back on the original value.
Furthermore, a ReferenceObject can be used to load the data from the original value to ensure that the two values remain in sync, as the value might have been mutated while the copy is still alive, conceptually allowing for an "inverted write-back".
ReferenceObject is intended to be extended by inheritance.
An object that is used to wrap a value that is copied around but has a provenance that requires a write-back, can inherit from ReferenceObject to plug into the write-back behavior.
The heap part of the object should subclass QV4::Heap::ReferenceObject while the object part should subclass QV4::ReferenceObject.
When initializing the heap part of the subclass, QV4::Heap::ReferenceObject::init should be called to set up the write-back mechanism.
The write-back mechanism stores a reference to an object and, potentially, a property index to write-back at.
Furthermore, a series of flags can be used to condition the behavior of the write-back.
For example:
The snippet is an example of some sub-class {Foo} of ReferenceObject setting up for a write-back to the property at index 1 of some object {object}.
Generally, a sub-class of ReferenceObject will be used to wrap one or more Copied Types and provide a certain behavior.
In certain situations there is no need to setup a write-back. For example, we might have certain cases where there is no original value to be wrapped while still in need of providing an object of the sub-classing type.
One example of such a behavior is that of returning an instance from a C++ method to QML.
When that is the case, the following initialization can be provided:
In certain cases, we try to avoid read-backs when we know that we have the latest data available already, see \l{Limiting reads on a QObject property}.
Certain implementation of ReferenceObject, might want to lazily load the data on the first read, rather than on the initialization of the reference. One such example would be QQmlValueTypeWrapper.
When that is the case, the IsDirty flag should be passed at initialiazation time. For example:
If the flag is not passed there the first read might be elided, leaving the object in an incorrect state.
Generally, to use the base implementation of write and read backs, as provided by QV4::ReferenceObject::readReference and QV4::ReferenceObject::writeBack, a sub-class should provide the following interface:
The two overloads of {storagePointer} should provide access to the internal backing storage of the ReferenceObject.
Generally, a ReferenceObject will be wrapping some instance of a C++ type, owning a copy of the original instance used as a storage for writes and reads. An implementation of {storagePointer} should give access to this backing storage, which is used to know what value to write-back and where to write when reading back from the original value.
For example, a Sequence type that wraps a QVariantList will own its own instance of a QVariantList. The implementation for {storagePointer} should give access to that owned instance.
{toVariant} should provide a QVariant wrapped representation of the internal storage that the ReferenceObject uses. This is used during the write-back of a ReferenceObject whose original value was a QVariant backed instance.
Do remember that instances of a ReferenceObject that are backing QVariant values should further pass the QV4::Heap::ReferenceObject::Flag::IsVariant flag at initialization time.
On the opposite side, {setVariant} should switch the value that the ReferenceObject stores with the provided variant. This is used when a QVariant backed ReferenceObject performs a read of its original value, to allow for synchronization.
It is still possible to use ReferenceObject without necessarily providing the above interface. QV4::DateObject is an example of a ReferenceObject sub-class that provides its own writeBack implementation and doesn't abide by the above.
With a sub-class of ReferenceObject that was set-up as above, a write-back can be performed by calling QV4::ReferenceObject::writeBack.
For example, some ReferenceObject subclass {Foo} might be backing, say, some map-like object.
Internally, insertion of an element might pass by some method, say {insertElement}. An implementation might, for example, look like the following:
The call to writeBack will ensure that the newly inserted element will be reflected on the original value where the object originates from.
Here {d()}, with {Foo} being a sub-class of ReferenceObject and thus of Object, is the heap part of {Foo} that should provide the interface specificed above and owns the actual storage of the stored value.
QV4::ReferenceObject::readReference provides a way to obtain the current state of the value that the ReferenceObject refers to.
When this read is performed, the obtained value will be stored back into the backing storage for the ReferenceObject.
This allows the ReferenceObject to lazily load the latest data on demand and correctly reflect the original value.
For example, say that {Foo} is a sub-class of ReferenceObject that is used to back array-like values.
{Foo} should provide the usual {virtualGetLength} method to support the {length} property that we expect an array to have.
In a possible implementation of {virtualGetLength}, {Foo} should ensure that readReference is called before providing a value for the length, to ensure that the latest data is available.
For example:
In most cases we cannot know whether the original data was modified between read accesses. This generally forces a read to be performed each time we require the latest data, even if we might have it already.
This can have surprising results, as certain procedure might require reading the data multiple times to be performed, which sometimes can be very expensive.
When the original data comes from the property of a {QObject}, and the property has a \tt{NOTIFY} signal or is \tt{BINDABLE}, we can subscribe to the signal to know when the data is actually modified outside our control, so that we need to fetch it again.
A ReferenceObject can take advantage of this to reduce the number of reads that are required when dealing with a {QObject}'s property provening data.
When a property has a \tt{NOTIFY} signal and is a \tt{BINDABLE} at the same time, we only need to use one such connection. Currently, the \tt{BINDABLE} subscription will take predecedence.
ReferenceObjects that are part of a \l{Reference object chains}{chain}, will traverse the chain up until a QOjbect holding root is found, and connect based on that object. As read/write backs in a chain are always propagated up the chain, this allow ReferenceObjects that are not directly parented to relevant element to still avoid unnecesary reads.
For example, the property of a value type exposed by a Q_GADGET, cannot have a \tt{NOTIFY} signal. Nonetheless, if a change were to occur to the parent value type or the property itself, that change would be propagated up the chain, possibly triggering a \tt{NOTIFY} signal that is part of the chain. Thus, by connecting to that upper \tt{NOTIFY} signal, we can still reliably know if a change was performed on the property itself and thus avoid reduce the number of reads.
As changes in the chain that do not really invalidate the data of that property will still trigger that same \tt{NOTIFY} signal, sometimes we will perform a read that is unnecessary due to granularity at which we are working. This is the case, returning to the example above, when a different property of that same value type will be changed.
This should still be a win, as we still expect to cut off multiple reads that would be performed without the optimization.
The default implementation for QV4::ReferenceObject::readReference will take care of performing this optimization already.
Derived objects that provide their own readReference implementation can plug into QV4::Heap::ReferenceObject::isDirty, QV4::Heap::ReferenceObject::setDirty and QV4::Heap::ReferenceObject::isConnected to provide the same optimization.
A ReferenceObject uses a "dirty" flag to track whether the data should be read again. If the ReferenceObject refers to a {QObject}'s property that has a \tt{NOTIFY} signal or is \tt{BINDABLE}, it will set the flag each time the \tt{NOTIFY} signal is emitted or the \tt{BINDABLE} is changed.
isDirty returns whether the flag is set and, thus, a readReference implementation should avoid performing the read itself when the method returns true.
After a read is performed, the "dirty" flag should be set again if the read was unsuccessful. The flag can be modified by usages of setDirty.
Generally, this only applies to instances of ReferenceObject that provene from a {QObject}'s property that has a notify signal, as that is the case that allows us to know when a read is required.
In all other cases, a ReferenceObject should always be "dirty" and perform a read, as it cannot know if the data was modified since its last read. This case will initially be managed by the base constructor for ReferenceObject, nonetheless derived objects with a custom readReference implementation need to take it into accoutn when setting the "dirty" flag after a read.
isConnected can be used to discern between the two cases, as it will only return true when the ReferenceObject is connected to a NOTIFY signal that can modify the "dirty" flag. When isConnected is false, a read implementation should always keep the ReferenceObject in a permanent "dirty" state, to ensure that the correct data is fetched when required.
Consider the following code:
\qml import QtQuick
Text { Component.onCompleted: { var f = font // font is a value type and f is a value type reference f.bold = true; otherText.font = f } } \endqml
Remembering that {font} is a Copied Type in QtQuick, {f} will be a Copied Type reference, internally backed by a ReferenceObject. Changing the {bold} property of {f} would internally perform a write-back which will reflect on the original {font} property of the {Text} component, as we would expect from the definition we gave above.
Nonetheless, we could generally expect that the intention behind the code wasn't to update the original {font} property, but to pass a slightly modified version of its value to {otherText}.
To avoid introducing this kind of possibly unintended behavior while still supporting a solution to the original problem, ReferenceObject allows limiting the availability of write-backs to a specific source location.
For example, by limiting the availability of write-backs to the single statement where a Copied Type reference is created, we can address the most common cases of the original issue while avoiding the unintuitive behavior of the above.
To enable source location enforcement, QV4::Heap::ReferenceObject::Flag::EnforcesLocation should be set when the ReferenceObject is initialized.
A reference location should be set by calling QV4::Heap::ReferenceObject::setLocation. For example, during initialization, one might be set to limit write-backs to the currently processed statement, where the ReferenceObject was created, as follows:
Do note that calls to QV4::ReferenceObject::writeBack and QV4::ReferenceObject::readReference do not directly take into account location enforcement.
This should generally be handled by the sub-class. QV4::Heap::ReferenceObject::isAttachedToProperty can be used to recognize whether the reference is still suitable for write-backs in a location-enforcement-aware way.
ReferenceObject can be nested.
For example, consider:
Where {a} is some object exposed to QML, {b} is a property of {a} and {c} is a property of {b}.
Based on what each of {a}, {b} and {c} is, multiple ReferenceObject instances, parented to one another, might be introduced.
For example, if {a} is a Q_OBJECT, {b} is a value type and {c} is a type that will be converted to a QV4::Sequence, {a} will be wrapped by a QObjectWrapper, {b} will be wrapped by a QQmlValueTypeWrapper which is parented to the QObjectWrapper wrapping {a} and {c} will be a Sequence that is parented to the QQmlValueTypeWrapper wrapping {b}.
This parenting chain is used to enable recursive read/write backs, ensuring that a read/write back travels up the chain as required so that the latest data is available on every relevant element.
At certain points in the chain, it is possible that a non-reference object is introduced.
For example, this is always the case when a Q_OBJECT is retrieved, as it will be wrapped in a QObjectWrapper which is not a reference object.
This breaks the chain of parenting and introduces the start of a new chain. As a QObjectWrapper directly stores a pointer to the original object, it doesn't need to perform the same read/write backs that reference objects do. Similarly, child reference objects only need to read up to the innermost QObjectWrapper in a chain to obtain the latest data.
Returning to the example above, if {b} is a Q_OBJECT instead of a value type, then it will be the root of the reference chain that has {c} has its child, without the need to be related to the QObjectWrapper that has been built by accessing {a}.
QQmlTypeWrapper, that can wrap a QObject pointer that represents a singleton or an attached property, behaves as chain root in the exact same way that QObjectWrapper does.
Definition at line 262 of file qv4referenceobject_p.h.
|
inlinestatic |
Definition at line 320 of file qv4referenceobject_p.h.
|
inlinestatic |
Definition at line 272 of file qv4referenceobject_p.h.
|
inlinestatic |
Definition at line 299 of file qv4referenceobject_p.h.
|
staticconstexpr |
Definition at line 269 of file qv4referenceobject_p.h.
1.14.0