Thread Support in Qt

When using Qt in a multithreaded program, it is important to understand the definition of the terms reentrant and thread-safe:

• reentrant - Describes a function which can be called simultaneously by multiple threads when each invocation of the function references unique data. Calling a reentrant function simultaneously with the same data is not safe, and such invocations should be serialized.
• thread-safe - Describes a function which can be called simultaneously by multiple threads when each invocation references shared data. Calling a thread-safe function simultaneously with the same data is safe, since all access to the shared data are serialized.

Note that Qt provides both implictly and explicitly shared classes. For more information, see the Threads and Shared Data section.

Most C++ member functions are inherently reentrant, since they only reference class member data. Any thread can call such a member function on an instance, as long as no other thread is calling a member function on the same instance. For example, given the class Number below:

    class Number
    {
    public:
        inline Number( int n ) : num( n ) { }

        inline int number() const { return num; }
        inline void setNumber( int n ) { num = n; }

    private:
        int num;
    };

The methods Number::number() and Number::setNumber() are reentrant, since they only reference unique data. Only one thread at a time can call member functions on each instance of Number. However, multiple threads can call member functions on separate instances of Number.

Thread-safe functions usually use a mutex (e.g a QMutex) to serialize access to shared data. Because of this, thread-safe functions are usually slower than reentrant functions, because of the extra overhead of locking and unlocking the mutex. For example, given the class Counter below:

    class Counter
    {
    public:
        inline Counter()  { ++instances; }
        inline ~Counter() { --instances; }

    private:
        static int instances;
    };

Since the modifications of the static instances integer are not serialized, this class is not thread-safe. So make it threadsafe, a mutex must be used:

    class Counter
    {
    public:
        inline Counter()
        {
            mutex.lock();
            ++instances;
            mutex.unlock();
        }

        ...
    private:
        static QMutex mutex;
        static int instances;
    };

Thread-safe Event Posting

    ...
    qApp->lock();

    QPainter p;
    p.begin( mywidget );
    p.setPen( QColor( "red" ) );
    p.drawLine( 0,0,100,100 );
    p.end();

    qApp->unlock();
    ...