Qt Remote Objects Replica

A compiled replica is a QRemoteObjectReplica based type, where the derived class definition is automatically generated by the repc compiler. When you use the REPC_REPLICA variable in your .pro file, this makes the generation part of the build process. Although only a header is generated, it's a complete type. There is no public constructor, so you need to use the QRemoteObjectNode::acquire template function to create the Replica instance.

A QRemoteObjectDynamicReplica can be generated at runtime. To do so, you call QRemoteObjectNode::acquireDynamic(), passing in the source name (a QString) as an argument. Dynamic replicas are a bit more verbose to use from C++, but they do not require compilation. Dynamic replicas do not support initial property values, or introspection until they have been initialized.

An important difference between these two ways of creating replicas is the behavior before the replica is initialized. Since a dynamic replica only gets a metaObject after initialization, it has basically no API before initialization -- no properties, and no signals to connect slots to.

Because metaObjects for compiled replicas are created at compile-time, their API is available when the replica is instantiated. You can even provide default values for properties in the template file, which are used until the replica is initialized with current values from the source.

Replica Initialization

A host node will share the list of sources that it hosts with every other node that connects to it. This host sends updates when sources are added to or removed from the list. In this way, a connected node will always know what sources it can attach itself to. Changes to a specific source are only propagated to nodes that have a replica of that source. Consequently, this avoids any unnecessary network traffic.

When a node acquires a replica for a known source, it sends a request for that source to the host node. Upon receiving this request, the host creates a reply packet with the current values for all properties of that source. If the requested replica is dynamic, the reply packet includes the API definition for the source. From then on, the replica's node will be included in the list of connections that receive changes to that source.

If a replica is instantiated but its node is not connected to the node that hosts the requested source -- or that object lives in a host node process, but sharing/remoting has not been enabled for the QObject -- the Replica will still be created, but remain uninitialized.

If, at a later time, the replica's node gets notified that the requested source is available from a connected node, at that point it will request the source and start the initialization process.

If the connection to a host node is lost, the replica will transition to the invalid state. It will attempt to reconnect and will re-initialize if the connection is restored; this makes sure all properties are current.

Replica Ownership

The acquire methods return a pointer to the replica QObject instantiated by the node. The node has no way of knowing the replica's intended lifetime. Consequently, when the replica is not longer needed, it is the calling program's responsibility to delete it.

You can instantiate multiple copies of the same replica. All replicas of the same source from a single node will share a private data member which handles the network communication. This means multiple instances of a replica do not introduce additional network traffic, although there will be some additional processing overhead. Failing to delete replicas will prevent the reference count on this private object from reaching 0, and cause unnecessary network communication until the calling process exits. For this reason, it is recommended to use QScopedPointer or QSharedPointer to help track the lifetime of replicas.