Qt Cryptographic Architecture: QCA::SyncThread Class Reference

# QCA::SyncThread Class Reference
[QCA user API]

Convenience class to run a thread and interact with it synchronously. More...

`#include <QtCrypto>`

Inheritance diagram for QCA::SyncThread:

Collaboration diagram for QCA::SyncThread:

[legend]

List of all members.

## Public Member Functions
QVariant | call (QObject *obj, const QByteArray &method, const QVariantList &args=QVariantList(), bool *ok=0)
void | start ()
void | stop ()
| SyncThread (QObject *parent=0)
| ~SyncThread ()
## Protected Member Functions
virtual void | atEnd ()=0
virtual void | atStart ()=0
virtual void | run ()
## Friends
class | Private
## Related Functions
(Note that these are not member functions.)
QCA_EXPORT bool | invokeMethodWithVariants (QObject *obj, const QByteArray &method, const QVariantList &args, QVariant *ret, Qt::ConnectionType type=Qt::AutoConnection)
QCA_EXPORT QByteArray | methodReturnType (const QMetaObject *obj, const QByteArray &method, const QList< QByteArray > argTypes)

## Detailed Description

Convenience class to run a thread and interact with it synchronously.

SyncThread makes it easy to perform the common practice of starting a thread, running some objects in that thread, and then interacting with those objects safely. Often, there is no need to directly use threading primitives (e.g. QMutex), resulting in very clean multi-threaded code.

Note:
  The following is an excerpt from http://delta.affinix.com/2006/11/13/synchronized-threads-part-3/

---
With SyncThread, you can start, stop, and call a method in another thread while the main thread sleeps. The only requirement is that the methods be declared as slots.

Below is a contrived example, where we have an object in another thread that increments a counter over a some interval, using the Qt event loop, and provides a method to inspect the value.

First, the Counter object:

    class Counter : public QObject
    {
            Q_OBJECT
    private:
            int x;
            QTimer timer;

    public:
            Counter() : timer(this)
            {
                    x = 0;
                    connect(&timer, SIGNAL(timeout()), SLOT(t_timeout()));
            }

    public slots:
            void start(int seconds)
            {
                    timer.setInterval(seconds * 1000);
                    timer.start();
            }

            int value() const
            {
                    return x;
            }

    private slots:
            void t_timeout()
            {
                    ++x;
            }
    };

Looks like a typical object, no surprises.

Now to wrap Counter with SyncThread. We went over how to do this in the first article, and it is very straightforward:

    class CounterThread : public SyncThread
    {
            Q_OBJECT
    public:
            Counter *counter;

            CounterThread(QObject *parent) : SyncThread(parent)
            {
                    counter = 0;
            }

            ~CounterThread()
            {
                    // SyncThread will stop the thread on destruct, but since our
                    //   atStop() function makes references to CounterThread's
                    //   members, we need to shutdown here, before CounterThread
                    //   destructs.
                    stop();
            }

    protected:
            virtual void atStart()
            {
                    counter = new Counter;
            }

            virtual void atStop()
            {
                    delete counter;
            }
    };

We can then use it like this:

    CounterThread *thread = new CounterThread;

    // after this call, the thread is started and the Counter is ready
    thread->start();

    // let's start the counter with a 1 second interval
    thread->call(thread->counter, "start", QVariantList() << 1);
    ...

    // after some time passes, let's check on the value
    int x = thread->call(thread->counter, "value").toInt();

    // we're done with this thing
    delete thread;

Do you see a mutex anywhere? I didn't think so.
---

Even without the call() function, SyncThread is still very useful for preparing objects in another thread, which you can then QObject::connect() to and use signals and slots like normal.

## Constructor & Destructor Documentation

QCA::SyncThread::SyncThread | ( | QObject * | parent = `0` | ) |

Standard constructor.

Parameters:

  | parent | the parent object for this parent.

QCA::SyncThread::~SyncThread | ( |  | ) |

Calls stop() and then destructs.

Note:
  Subclasses should call stop() in their own destructor

## Member Function Documentation

virtual void QCA::SyncThread::atEnd | ( |  | ) | `[protected, pure virtual]`

Reimplement this to perform your deinitialization.

virtual void QCA::SyncThread::atStart | ( |  | ) | `[protected, pure virtual]`

Reimplement this to perform your initialization.

QVariant QCA::SyncThread::call | ( | QObject * | obj,
|  | const QByteArray & | method,
|  | const QVariantList & | args = `QVariantList()`,
|  | bool * | ok = `0` |
| ) |  |  |

Calls a slot of an object in the thread.

This function will block until the slot has returned.

It is possible for the call to fail, for example if the method does not exist.

The arguments and return value of the call use QVariant. If the method has no return value (returns void), then the returned QVariant will be null.

Parameters:

  | obj | the object to call the method on
  | method | the name of the method (without the arguments or brackets)
  | args | the list of arguments to use in the method call
  | ok | if not 0, true is stored here if the call succeeds, otherwise false is stored here.

virtual void QCA::SyncThread::run | ( |  | ) | `[protected, virtual]`

Starts the event loop and calls atStart and atStop as necessary.

Reimplemented from QThread.

void QCA::SyncThread::start | ( |  | ) |

Starts the thread, begins the event loop the thread, and then calls atStart() in the thread.

This function will block until atStart() has returned.

void QCA::SyncThread::stop | ( |  | ) |

Stops the event loop of the thread, calls atStop() in the thread, and instructs the thread to finish.

This function will block until the thread has finished.

## Friends And Related Function Documentation

QCA_EXPORT bool invokeMethodWithVariants | ( | QObject * | obj,
|  | const QByteArray & | method,
|  | const QVariantList & | args,
|  | QVariant * | ret,
|  | Qt::ConnectionType | type = `Qt::AutoConnection` |
| ) |  |  | `[related]`

Convenience method to invoke a method by name, using a variant list of arguments.

This function can be used as shown:

    class TestClass : public QObject
    {
        Q_OBJECT
        // ...
    public slots:
        QString qstringMethod()  { return QString( "the result" ); };
        bool boolMethod( const QString & )  { return true; };
    };

    TestClass *testClass = new TestClass;
    QVariantList args;

    QVariant stringRes;
    // calls testClass->qstringMethod() with no arguments ( since args is an empty list)
    bool ret = QCA::invokeMethodWithVariants( testClass, QByteArray( "qstringMethod" ), args, &stringRes );
    // ret is true (since call succeeded), stringRes.toString() is a string - "the result"

    QVariant boolResult;
    QString someString( "not important" );
    args << someString;
    // calls testClass->boolMethod( someString ), returning result in boolResult
    ret = QCA::invokeMethodWithVariants( testClass1, QByteArray( "boolMethod" ), args, &boolResult );
    // ret is true (since call succeeded), boolResult.toBool() is true.

Parameters:

  | obj | the object to call the method on
  | method | the name of the method (without the arguments or brackets)
  | args | the list of arguments to use in the method call
  | ret | the return value of the method (unchanged if the call fails)
  | type | the type of connection to use

Returns:
  true if the call succeeded, otherwise false

QCA_EXPORT QByteArray methodReturnType | ( | const QMetaObject * | obj,
|  | const QByteArray & | method,
|  | const QList< QByteArray > | argTypes |
| ) |  |  | `[related]`

Convenience method to determine the return type of a method.

This function identifies the return type of a specified method. This function can be used as shown:

    class TestClass : public QObject
    {
        Q_OBJECT
        // ...
    public slots:
        QString qstringMethod()  { return QString(); };
        bool boolMethod( const QString & )  { return true; };
    };

    QByteArray myTypeName;

    TestClass testClass;
    QList<QByteArray> argsList; // empty list, since no args

    myTypeName = QCA::methodReturnType( testClass.metaObject(), QByteArray( "qstringMethod" ), argsList );
    // myTypeName is "QString"

    myTypeName = QCA::methodReturnType( testClass.metaObject(), QByteArray( "boolMethod" ), argsList );
    // myTypeName is "", because there is no method called "boolMethod" that has no arguments

    argsList << "QString"; // now we have one argument
    myTypeName = QCA::methodReturnType( testClass.metaObject(), QByteArray( "boolMethod" ), argsList );
    // myTypeName is "bool"

The return type name of a method returning void is an empty string, not "void"

Note:
  This function is not normally required for use with QCA. It is provided for use in your code, if required.

Parameters:

  | obj | the QMetaObject for the object
  | method | the name of the method (without the arguments or brackets)
  | argTypes | the list of argument types of the method

Returns:
  the name of the type that this method will return with the specified argument types.

See also:
  QMetaType for more information on the Qt meta type system.

The documentation for this class was generated from the following file:

- qca_support.h