Qt Documentation

Contents

Overview Qt Remote Objects

Introduction

The Qt Remote Objects (QtRO) module provides an easy way to share Qt APIs between processes and devices. A data channel between processes and devices is required for this to work. Therefore, the first thing you need in QtRO is a QRemoteObjectNode. In QtRO, a node is an endpoint for communication. Each participant in a remote objects network, be it a process or a device, needs its own node. QtRO is a peer-to-peer network, with connected nodes being the links in the network.

Nodes, by themselves, don’t provide much use. The value comes from adding QObject classes to a node for sharing. Any peer node can then request a copy/instance of the shared object from the node that shares it (called the host node). Unlike when using normal class instances (with independent properties and signal emissions), the idea in QtRO is to synchronize the changes of the shared object to all of the copies. With a few exceptions, the copies have the exact same Qt API as the original object, and are intended to be used exactly as if the original object were available. In QtRO, the original object is called the Source. It is a fully implemented C++ class, with whatever business logic is needed to provide the desired functionality. Copies of this object are called Replicas. You don’t need to write any C++ code for a replica; instead, you simply request an instance from a node. You still need some code to use it, such as connecting signals to your own slots, but you don’t need to implement the internal behavior – that was already done in the source object.

Because the source can be in a different process or even on a different device, there are concerns in QtRO that you won’t run into when developing without Inter-Process Communication (IPC). Specifically, what happens if the process or device isn’t there? This is where the additions to the Replica API come in. There is an initialized() signal that is emitted once the replica has received the source state from the QtRO network. There is also an isReplicaValid property and a stateChanged() signal to alert you if the connection is lost.

Objects shared over QtRO use the links (conduits) between nodes for all communication. If you intend to share a QObject, you must create a host node with a URL other nodes can connect to. You can also use the QtRO Registry to facilitate connections, but your nodes sharing sources still need to be Host nodes. Each shared object is given a name (a QString), used for identifying it on the QtRO network.

See the Overview for a more detailed description, or use the following examples to get started with QtRO.

Implementation

To illustrate the use of remote objects, on the source side we need to:

  1. Create the Source object that will be replicated to other nodes (with or without using repc, the Qt Remote Objects Compiler).
  2. (Optional) Create the Registry. If not used, direct connections are required.
  3. Create a host node so the source object can be shared.
  4. Call the node's enableRemoting() function to share the source object.

And on the replica side:

  1. (Optional) Use repc to generate a Replica header for your project.
  2. Create the node that will connect with the Source host node.
  3. Call the node's acquire() function to create a pointer to a replica.

The examples below will show both repc-compiled static objects and dynamic source objects. The examples will also show direct connections as well as connections using a Registry between nodes.

Example 1: Direct Connection Using a Static Source

In this example, the source object is a simple binary switch that will toggle its state based on a timer. When the state changes, a signal is emitted by the source which QtRO propagates to all replicas. As the replica will have the same properties, signals and slots as were exposed from the source object, any slots connected to the replica's signal will be called when the replica receives the signal. The client process then echoes back the received switch state to the source by emitting its own signal which is connected to a slot on the replica.

  1. Create a source object

    To create this Source object, we first create the definition file, simpleswitch.rep. This file describes the properties and methods for the object and is input to the repc utility which is part of Qt Remote Objects. Only the interfaces that need to be exposed to Replica objects are defined in this file.

    simpleswitch.rep

    class SimpleSwitch
{
    PROP(bool currState=false);
    SLOT(server_slot(bool clientState));
};

    Above,

    • currState holds the current state of the switch, and
    • server_slot() allows us to interact with the Source - it will be connected to the echoSwitchState(bool newstate) signal.

    For repc to process this file, add the following line to the .pro file:

    REPC_SOURCE = simpleswitch.rep

    The REPC_SOURCE variable is only relevant for the Qt Remote Object module, so you need to add it to your project as well:

    QT       += remoteobjects

    repc creates the header rep_SimpleSwitch_source.h in your specified build directory. Refer to the Source section for more details about this file.

    Repc creates three helper classes for use with QtRO. For this example, we will use the most basic: SimpleSwitchSimpleSource. It is an abstract class, defined in rep_SimpleSwitch_source.h. We derive from it to define our SimpleSwitch implementation class as shown below:

    simpleswitch.h

    #ifndef SIMPLESWITCH_H
#define SIMPLESWITCH_H

#include "rep_SimpleSwitch_source.h"

class SimpleSwitch : public SimpleSwitchSimpleSource
{
    Q_OBJECT
public:
    SimpleSwitch(QObject *parent = nullptr);
    ~SimpleSwitch();
    virtual void server_slot(bool clientState);
public Q_SLOTS:
    void timeout_slot();
private:
    QTimer *stateChangeTimer;
};

#endif

    Above,

    • stateChangeTimer is a QTimer that is used to toggle the state of our SimpleSwitch,
    • timeout_slot() is connected to the timeout() signal of stateChangeTimer,
    • server_slot() -- which is called on the source (automatically via QtRO) whenever any replica calls their version of the slot -- outputs the received value, and
    • currStateChanged(bool), defined in repc-generated rep_SimpleSwitch_source.h, is emitted whenever currState toggles. In this example, we ignore the signal on the source side, and handle it later on the replica side.

    The definition of our SwitchState class is shown below:

    simpleswitch.cpp

    #include "simpleswitch.h"

// constructor
SimpleSwitch::SimpleSwitch(QObject *parent) : SimpleSwitchSimpleSource(parent)
{
    stateChangeTimer = new QTimer(this); // Initialize timer
    QObject::connect(stateChangeTimer, SIGNAL(timeout()), this, SLOT(timeout_slot())); // connect timeout() signal from stateChangeTimer to timeout_slot() of simpleSwitch
    stateChangeTimer->start(2000); // Start timer and set timout to 2 seconds
    qDebug() << "Source Node Started";
}

//destructor
SimpleSwitch::~SimpleSwitch()
{
    stateChangeTimer->stop();
}

void SimpleSwitch::server_slot(bool clientState)
{
    qDebug() << "Replica state is " << clientState; // print switch state echoed back by client
}

void SimpleSwitch::timeout_slot()
{
    // slot called on timer timeout
    if (currState()) // check if current state is true, currState() is defined in repc generated rep_SimpleSwitch_source.h
        setCurrState(false); // set state to false
    else
        setCurrState(true); // set state to true
    qDebug() << "Source State is "<<currState();

}
  2. Create a registry

    Because this example involves using a direct connection between nodes, step 2 for Registry creation is omitted.

  3. Create a host node

    The host node is created as shown below:

    QRemoteObjectHost srcNode(QUrl(QStringLiteral("local:switch")));
  4. Host source object and remoting

    The following statements instantiate the Source object and pass it to the host to enable "remoting", that is, making the object visible to the QtRO network:

    SimpleSwitch srcSwitch; // create simple switch
srcNode.enableRemoting(&srcSwitch); // enable remoting

    The contents of main.cpp file that implements the above steps are shown below:

    main.cpp

    #include <QCoreApplication>
#include "simpleswitch.h"

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    SimpleSwitch srcSwitch; // create simple switch

    QRemoteObjectHost srcNode(QUrl(QStringLiteral("local:switch"))); // create host node without Registry
    srcNode.enableRemoting(&srcSwitch); // enable remoting/sharing

    return a.exec();
}

    Compile and run this (source side) project. The output (without any replicas created) should look as shown below with the switch state toggling between true and false every two seconds.

    "Example 1: Server output"

    Next are the steps for creating the replica side of the network, which in this example gets the state of switch from the Source and echoes it back.

Replica Code

  1. Use repc to add a replica to your project

    The same API definition file as was used on the source side, SimpleSwitch.rep, is used for creating a Replica header file using the repc utility. Include the following line in your client side .pro file, specifying a .rep file input:

    REPC_REPLICA = simpleswitch.rep

    The repc tool generates a rep_SimpleSwitch_replica.h file in the build directory. Refer to Replica section for more details about this file.

  2. Create a node to connect with the source's host node

    The following code instantiates the second node on the network and connects it with the source host node:

    QRemoteObjectNode repNode; // create remote object node
repNode.connectToNode(QUrl(QStringLiteral("local:switch"))); // connect with remote host node
  3. Call node's acquire() to create a pointer to a replica

    First, a replica is instantiated:

    QSharedPointer<SimpleSwitchReplica> ptr;
ptr.reset(repNode.acquire<SimpleSwitchReplica>()); // acquire replica of source from host node

    Note that acquire() returns a pointer to the replica. However, it does not manage the pointer lifetime. This example uses the recommended process of wrapping the returned pointer in a QSharedPointer or QScopedPointer to ensure the pointer is properly deleted.

    main.cpp implements above steps and instantiates our object:

    main.cpp

    #include <QCoreApplication>
#include "client.h"

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    QSharedPointer<SimpleSwitchReplica> ptr; // shared pointer to hold source replica

    QRemoteObjectNode repNode; // create remote object node
    repNode.connectToNode(QUrl(QStringLiteral("local:switch"))); // connect with remote host node

    ptr.reset(repNode.acquire<SimpleSwitchReplica>()); // acquire replica of source from host node

    Client rswitch(ptr); // create client switch object and pass reference of replica to it

    return a.exec();
}

    Complete declaration and definition of the Client class:

    client.h

    #ifndef _CLIENT_H
#define _CLIENT_H

#include <QObject>
#include <QSharedPointer>

#include "rep_SimpleSwitch_replica.h"

class Client : public QObject
{
    Q_OBJECT
public:
    Client(QSharedPointer<SimpleSwitchReplica> ptr);
    ~Client();
    void initConnections();// Function to connect signals and slots of source and client

Q_SIGNALS:
    void echoSwitchState(bool switchState);// this signal is connected with server_slot(..) on the source object and echoes back switch state received from source

public Q_SLOTS:
    void recSwitchState_slot(); // slot to receive source state
private:
    bool clientSwitchState; // holds received server switch state
    QSharedPointer<SimpleSwitchReplica> reptr;// holds reference to replica

 };

#endif

    client.cpp

    #include "client.h"

// constructor
Client::Client(QSharedPointer<SimpleSwitchReplica> ptr) :
    QObject(nullptr),reptr(ptr)
{
    initConnections();
    //We can connect to SimpleSwitchReplica Signals/Slots
    //directly because our Replica was generated by repc.
}

//destructor
Client::~Client()
{
}

void Client::initConnections()
{
        // initialize connections between signals and slots

       // connect source replica signal currStateChanged() with client's recSwitchState() slot to receive source's current state
        QObject::connect(reptr.data(), SIGNAL(currStateChanged()), this, SLOT(recSwitchState_slot()));
       // connect client's echoSwitchState(..) signal with replica's server_slot(..) to echo back received state
        QObject::connect(this, SIGNAL(echoSwitchState(bool)),reptr.data(), SLOT(server_slot(bool)));
}

void Client::recSwitchState_slot()
{
    qDebug() << "Received source state "<<reptr.data()->currState();
    clientSwitchState = reptr.data()->currState();
    Q_EMIT echoSwitchState(clientSwitchState); // Emit signal to echo received state back to server
}

    Compiling and executing this example together with the source-side example generates the following output:

    "Direct Connect Server Client Communication output"

Example 2: Direct Connection with a Dynamic Replica

A dynamic replica is initially created as a "bare" QObject - that is, it has no properties, signals or slots. QtRO returns the API for the object during initialization (after the connection to the source is made), thus the API is added to the object at runtime.

There are no changes to the source side as a dynamic Replica only impacts how the requestor node acquires the replica. The source-side code shown in Example 1 will be used.

  1. Add replica generation to project.

    Because the replica is dynamically acquired, no .rep file is required unlike in Example 1.

  2. Create the remote node and connect it with the source host node.

    The code for this step is unchanged from Example 1.

    QRemoteObjectNode repNode; // create remote object node
repNode.connectToNode(QUrl(QStringLiteral("local:switch"))); // connect with remote host node
  3. Acquire a replica of the remote source object.

    In main.cpp, we use a QSharedPointer to hold a replica of the remote object, and then instantiate a replica requestor object:

    #include <QCoreApplication>

#include "dynamicclient.h"

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    QSharedPointer<QRemoteObjectDynamicReplica> ptr; // shared pointer to hold replica

    QRemoteObjectNode repNode;
    repNode.connectToNode(QUrl(QStringLiteral("local:switch")));

    ptr.reset(repNode.acquireDynamic("SimpleSwitch")); // acquire replica of source from host node

    DynamicClient rswitch(ptr); // create client switch object and pass replica reference to it
}

Below is the complete declaration and definition of the requestor class (DynamicClient in this example):

dynamicclient.h

#ifndef _DYNAMICCLIENT_H
#define _DYNAMICCLIENT_H

#include <QObject>
#include <QSharedPointer>

#include <QRemoteObjectNode>
#include <qremoteobjectdynamicreplica.h>

class DynamicClient : public QObject
{
    Q_OBJECT
public:
    DynamicClient(QSharedPointer<QRemoteObjectDynamicReplica> ptr);
    ~DynamicClient();

Q_SIGNALS:
    void echoSwitchState(bool switchState);// this signal is connected with server_slot(..) slot of source object and echoes back switch state received from source

public Q_SLOTS:
    void recSwitchState_slot(); // Slot to receive source state
    void initConnection_slot(); //Slot to connect signals/slot on replica initialization

private:
    bool clientSwitchState; // holds received server switch state
    QSharedPointer<QRemoteObjectDynamicReplica> reptr;// holds reference to replica
 };

#endif

dynamicclient.cpp

#include "dynamicclient.h"

// constructor
DynamicClient::DynamicClient(QSharedPointer<QRemoteObjectDynamicReplica> ptr) :
    QObject(nullptr), reptr(ptr)
{

    //connect signal for replica valid changed with signal slot initialization
    QObject::connect(reptr.data(), SIGNAL(initialized()), this, SLOT(initConnection_slot()));
}

//destructor
DynamicClient::~DynamicClient()
{
}

// Function to initialize connections between slots and signals
void DynamicClient::initConnection_slot()
{

    // connect source replica signal currStateChanged() with client's recSwitchState() slot to receive source's current state
   QObject::connect(reptr.data(), SIGNAL(currStateChanged()), this, SLOT(recSwitchState_slot()));
   // connect client's echoSwitchState(..) signal with replica's server_slot(..) to echo back received state
   QObject::connect(this, SIGNAL(echoSwitchState(bool)),reptr.data(), SLOT(server_slot(bool)));
}

void DynamicClient::recSwitchState_slot()
{
   clientSwitchState = reptr->property("currState").toBool(); // use replica property to get currState from source
   qDebug() << "Received source state " << clientSwitchState;
   Q_EMIT echoSwitchState(clientSwitchState); // Emit signal to echo received state back to server
}

When executed together with the source-side example, the output is identical to Example 1.

Example 3: Remote Nodes using a Registry

This example will illustrate the use of a Registry for building the node topology. For only two nodes, the benefits of using a registry are minimal. With a registry, instead of using a QUrl to create a direct connection between two nodes, you use a different QUrl to point both the host and replica nodes to the registry. As the network grows, using a registry means that all nodes only need to connect to the registry via a single QUrl. With direct connections, nodes would have to maintain a list of QUrls for each node they link to.

Source Code

The simpleswitch.h and simpleswitch.cpp sources from Example can be used without modification. The difference is in the way a host node is created and connected to the Registry:

main.cpp

#include <QCoreApplication>
#include "simpleswitch.h"

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    SimpleSwitch srcSwitch; // create SimpleSwitch

    QRemoteObjectRegistryHost regNode(QUrl(QStringLiteral("local:registry"))); // create node that hosts registry
    QRemoteObjectHost srcNode(QUrl(QStringLiteral("local:switch")), QUrl(QStringLiteral("local:registry"))); // create node that will host source and connect to registry
    //Note, you can add srcSwitch directly to regNode if desired.
    //We use two Nodes here, as the regNode could easily be in a third process.

    srcNode.enableRemoting(&srcSwitch); // enable remoting of source object

    return a.exec();
}

Replica Code

The requestor object used for this example is the dynamic replica client discussed in Example 2.

The only modification is in main.cpp: a Registry node is created to acquire a Replica:

    QRemoteObjectNode repNode(QUrl(QStringLiteral("local:registry")));

When executed together with the source-side example, the output is identical to Example 1.

© 2019 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.