Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.trolltech.qt.core
Class QThreadPool

    java.lang.Object
      com.trolltech.qt.QSignalEmitter
          com.trolltech.qt.QtJambiObject
              com.trolltech.qt.core.QObject
                  com.trolltech.qt.core.QThreadPool

All Implemented Interfaces:
  QtJambiInterface

    public class QThreadPool

extends QObject

The `QThreadPool` class manages a collection of `QThreads`. `QThreadPool` manages and recyles individual QThread objects to help reduce thread creation costs in programs that use threads. Each Qt application has one global `QThreadPool` object, which can be accessed by calling `globalInstance()`.

To use one of the `QThreadPool` threads, subclass `QRunnable` and implement the `run()` virtual function. Then create an object of that class and pass it to `QThreadPool::start()`.

            static class HelloWorldTask extends QRunnable {
                @Override
                public void run()
                {
                    System.out.println("Hello world from thread" + QThread.currentThread());
                }
            }

            public static void main(String args[]) {
                QCoreApplication.initialize(args);

                HelloWorldTask hello = new HelloWorldTask();
                // QThreadPool takes ownership and deletes 'hello' automatically
                QThreadPool.globalInstance().start(hello);
            }

`QThreadPool` deletes the `QRunnable` automatically by default. Use `QRunnable::setAutoDelete()` to change the auto-deletion flag.

`QThreadPool` supports executing the same `QRunnable` more than once by calling `tryStart`(this) from within `QRunnable::run()`. If `autoDelete` is enabled the `QRunnable` will be deleted when the last thread exits the run function. Calling `start()` multiple times with the same `QRunnable` when `autoDelete` is enabled creates a race condition and is not recommended.

Threads that are unused for a certain amount of time will expire. The default expiry timeout is 30000 milliseconds (30 seconds). This can be changed using `setExpiryTimeout()`. Setting a negative expiry timeout disables the expiry mechanism.

Call `maxThreadCount()` to query the maximum number of threads to be used. If needed, you can change the limit with `setMaxThreadCount()`. The default `maxThreadCount()` is QThread::idealThreadCount(). The `activeThreadCount()` function returns the number of threads currently doing work.

The `reserveThread()` function reserves a thread for external use. Use `releaseThread()` when your are done with the thread, so that it may be reused. Essentially, these functions temporarily increase or reduce the active thread count and are useful when implementing time-consuming operations that are not visible to the `QThreadPool`.

Note that `QThreadPool` is a low-level class for managing threads, see QtConcurrent::run() or the other Qt Concurrent APIs for higher level alternatives.

See also:
  `QRunnable`.

Nested Class Summary

Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter
`QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9`

Constructor Summary
`QThreadPool()` Constructs a thread pool with the given `parent`.
`QThreadPool(QObject parent)` Constructs a thread pool with the given `parent`.

Method Summary
`int` | `activeThreadCount()` This property represents the number of active threads in the thread pool.
`int` | `expiryTimeout()` Threads that are unused for `expiryTimeout` milliseconds are considered to have expired and will exit.
`static QThreadPool` | `fromNativePointer(QNativePointer nativePointer)` This method returns the QThreadPool instance pointed to by `nativePointer`.
`static QThreadPool` | `globalInstance()` Returns the global `QThreadPool` instance.
`int` | `maxThreadCount()` This property represents the maximum number of threads used by the thread pool.
`void` | `releaseThread()` Releases a thread previously reserved by a call to `reserveThread()`.
`void` | `reserveThread()` Reserves one thread, disregarding `activeThreadCount()` and `maxThreadCount()`.
`void` | `setExpiryTimeout(int expiryTimeout)` Threads that are unused for `expiryTimeout` milliseconds are considered to have expired and will exit.
`void` | `setMaxThreadCount(int maxThreadCount)` This property represents the maximum number of threads used by the thread pool.
`void` | `start(QRunnable runnable)` Reserves a thread and uses it to run `runnable`, unless this thread will make the current thread count exceed `maxThreadCount()`.
`void` | `start(QRunnable runnable, int priority)` Reserves a thread and uses it to run `runnable`, unless this thread will make the current thread count exceed `maxThreadCount()`.
`boolean` | `tryStart(QRunnable runnable)` Attempts to reserve a thread to run `runnable`.
`void` | `waitForDone()` Waits for each thread to exit and removes all threads from the thread pool.

Methods inherited from class com.trolltech.qt.core.QObject
`childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty`

Methods inherited from class com.trolltech.qt.QtJambiObject
`dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr`

Methods inherited from class com.trolltech.qt.QSignalEmitter
`blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread`

Methods inherited from class java.lang.Object
`clone, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Methods inherited from interface com.trolltech.qt.QtJambiInterface
`disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership`

Constructor Detail

### QThreadPool

    public QThreadPool()

  Constructs a thread pool with the given `parent`.

### QThreadPool

    public QThreadPool(QObject parent)

  Constructs a thread pool with the given `parent`.

Method Detail

### activeThreadCount

    public final int activeThreadCount()

  This property represents the number of active threads in the thread pool.

  Note: It is possible for this function to return a value that is greater than `maxThreadCount()`. See `reserveThread()` for more details.

See also:
  `reserveThread()`, and `releaseThread()`.

### expiryTimeout

    public final int expiryTimeout()

  Threads that are unused for `expiryTimeout` milliseconds are considered to have expired and will exit. Such threads will be restarted as needed. The default `expiryTimeout` is 30000 milliseconds (30 seconds). If `expiryTimeout` is negative, newly created threads will not expire, e.g., they will not exit until the thread pool is destroyed.

  Note that setting `expiryTimeout` has no effect on already running threads. Only newly created threads will use the new `expiryTimeout`. We recommend setting the `expiryTimeout` immediately after creating the thread pool, but before calling `start()`.

### maxThreadCount

    public final int maxThreadCount()

  This property represents the maximum number of threads used by the thread pool.

  Note: The thread pool will always use at least 1 thread, even if `maxThreadCount` limit is zero or negative.

  The default `maxThreadCount` is QThread::idealThreadCount().

### releaseThread

    public final void releaseThread()

  Releases a thread previously reserved by a call to `reserveThread()`.

  Note: Calling this function without previously reserving a thread temporarily increases `maxThreadCount()`. This is useful when a thread goes to sleep waiting for more work, allowing other threads to continue. Be sure to call `reserveThread()` when done waiting, so that the thread pool can correctly maintain the `activeThreadCount()`.

See also:
  `reserveThread()`.

### reserveThread

    public final void reserveThread()

  Reserves one thread, disregarding `activeThreadCount()` and `maxThreadCount()`.

  Once you are done with the thread, call `releaseThread()` to allow it to be reused.

  Note: This function will always increase the number of active threads. This means that by using this function, it is possible for `activeThreadCount()` to return a value greater than `maxThreadCount()` .

See also:
  `releaseThread()`.

### setExpiryTimeout

    public final void setExpiryTimeout(int expiryTimeout)

  Threads that are unused for `expiryTimeout` milliseconds are considered to have expired and will exit. Such threads will be restarted as needed. The default `expiryTimeout` is 30000 milliseconds (30 seconds). If `expiryTimeout` is negative, newly created threads will not expire, e.g., they will not exit until the thread pool is destroyed.

  Note that setting `expiryTimeout` has no effect on already running threads. Only newly created threads will use the new `expiryTimeout`. We recommend setting the `expiryTimeout` immediately after creating the thread pool, but before calling `start()`.

### setMaxThreadCount

    public final void setMaxThreadCount(int maxThreadCount)

  This property represents the maximum number of threads used by the thread pool.

  Note: The thread pool will always use at least 1 thread, even if `maxThreadCount` limit is zero or negative.

  The default `maxThreadCount` is QThread::idealThreadCount().

### start

    public final void start(QRunnable runnable)

  Reserves a thread and uses it to run `runnable`, unless this thread will make the current thread count exceed `maxThreadCount()`. In that case, `runnable` is added to a run queue instead. The `priority` argument can be used to control the run queue's order of execution.

  Note that the thread pool takes ownership of the `runnable` if `runnable->autoDelete()` returns true, and the `runnable` will be deleted automatically by the thread pool after the `runnable->run()` returns. If `runnable->autoDelete()` returns false, ownership of `runnable` remains with the caller. Note that changing the auto-deletion on `runnable` after calling this functions results in undefined behavior.

### start

    public final void start(QRunnable runnable,
                            int priority)

  Reserves a thread and uses it to run `runnable`, unless this thread will make the current thread count exceed `maxThreadCount()`. In that case, `runnable` is added to a run queue instead. The `priority` argument can be used to control the run queue's order of execution.

  Note that the thread pool takes ownership of the `runnable` if `runnable->autoDelete()` returns true, and the `runnable` will be deleted automatically by the thread pool after the `runnable->run()` returns. If `runnable->autoDelete()` returns false, ownership of `runnable` remains with the caller. Note that changing the auto-deletion on `runnable` after calling this functions results in undefined behavior.

### tryStart

    public final boolean tryStart(QRunnable runnable)

  Attempts to reserve a thread to run `runnable`.

  If no threads are available at the time of calling, then this function does nothing and returns false. Otherwise, `runnable` is run immediately using one available thread and this function returns true.

  Note that the thread pool takes ownership of the `runnable` if `runnable->autoDelete()` returns true, and the `runnable` will be deleted automatically by the thread pool after the `runnable->run()` returns. If `runnable->autoDelete()` returns false, ownership of `runnable` remains with the caller. Note that changing the auto-deletion on `runnable` after calling this function results in undefined behavior.

### waitForDone

    public final void waitForDone()

  Waits for each thread to exit and removes all threads from the thread pool.

### globalInstance

    public static QThreadPool globalInstance()

  Returns the global `QThreadPool` instance.

### fromNativePointer

    public static QThreadPool fromNativePointer(QNativePointer nativePointer)

  This method returns the QThreadPool instance pointed to by `nativePointer`.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD