内容

公共类型
公共函数
公共槽
信号
静态公共成员
保护函数
静态保护成员
详细描述
管理线程

QThread 类

The QThread 类提供独立于平台的方式管理线程。更多...

头：	#include <QThread>
继承：	QObject
继承者：

公共类型

enum	Priority { IdlePriority, LowestPriority, LowPriority, NormalPriority, ..., InheritPriority }

公共函数

	QThread (QObject * parent = 0)
	~QThread ()
void	exit (int returnCode = 0)
bool	isFinished () const
bool	isRunning () const
优先级	priority () const
void	setPriority (Priority priority )
void	setStackSize (uint stackSize )
uint	stackSize () const
bool	wait (unsigned long time = ULONG_MAX)

29 公共函数继承自 QObject

公共槽

void	quit ()
void	start (Priority priority = InheritPriority)
void	terminate ()

1 公共槽继承自 QObject

信号

void	finished ()
void	started ()
void	terminated ()

1 信号继承自 QObject

静态公共成员

QThread *	currentThread ()
Qt::HANDLE	currentThreadId ()
int	idealThreadCount ()
void	yieldCurrentThread ()

7 静态公共成员继承自 QObject

保护函数

int	exec ()
virtual void	run ()

8 保护函数继承自 QObject

静态保护成员

void	msleep (unsigned long msecs )
void	setTerminationEnabled (bool enabled = true)
void	sleep (unsigned long secs )
void	usleep (unsigned long usecs )

额外继承成员

1 特性继承自 QObject

详细描述

The QThread 类提供独立于平台的方式管理线程。

A QThread 对象管理程序中的某一控制线程。QThread 的开始执行是在 run ()。默认情况下， run () 启动事件循环通过调用 exec () 并在线程内运行 Qt 事件循环。

可以使用 Worker 对象，通过把它们移到线程使用 QObject::moveToThread ().

class Worker : public QObject
{
    Q_OBJECT
    QThread workerThread;
public slots:
    void doWork(const QString &parameter) {
        // ...
        emit resultReady(result);
    }
signals:
    void resultReady(const QString &result);
};
class Controller : public QObject
{
    Q_OBJECT
    QThread workerThread;
public:
    Controller() {
        Worker *worker = new Worker;
        worker->moveToThread(&workerThread);
        connect(&workerThread, SIGNAL(finished()), worker, SLOT(deleteLater()));
        connect(this, SIGNAL(operate(QString)), worker, SLOT(doWork(QString)));
        connect(worker, SIGNAL(resultReady(QString)), this, SLOT(handleResults(QString)));
        workerThread.start();
    }
    ~Controller() {
        workerThread.quit();
        workerThread.wait();
    }
public slots:
    void handleResults(const QString &);
signals:
    void operate(const QString &);
};

然后，会在单独线程中执行 Worker 槽代码。无论如何，把 Worker 槽连接到来自任何对象、任何线程中的任何信号是自由的。跨不同线程连接信号和槽是安全的，得益于机制队列连接 .

使在单独线程中运行代码的另一方式，是子类化 QThread 并重实现 run ()。例如：

class WorkerThread : public QThread
{
    Q_OBJECT
    void run() {
        QString result;
        /* expensive or blocking operation  */
        emit resultReady(result);
    }
signals:
    void resultReady(const QString &s);
};
void MyObject::startWorkInAThread()
{
    WorkerThread *workerThread = new WorkerThread(this);
    connect(workerThread, SIGNAL(resultReady(QString)), this, SLOT(handleResults(QString)));
    connect(workerThread, SIGNAL(finished()), workerThread, SLOT(deleteLater()));
    workerThread->start();
}

在该范例中，线程会在 run 函数有返回之后退出。没有任何事件循环会运行在线程中，除非调用 exec ().

重要的是记住 QThread 实例活在实例化它的旧线程，而不是新线程调用 run ()。这意味着所有 QThread 的队列槽将在旧线程中执行。因此，希望在新线程援引槽的开发者必须使用工作者对象方式；不应将新槽直接实现在子类化 QThread .

当子类化 QThread ，请记住构造函数在旧线程中执行而 run () 在新线程中执行。若从两者函数访问成员变量，则变量是从 2 不同线程被访问。检查这样做是安全的。

注意： 必须小心，当与跨不同线程的对象进行交互时。见同步线程了解细节。

管理线程

QThread 将通过信号通知您当线程 started (), finished ()，和 terminated ()，或可以使用 isFinished () 和 isRunning () 去查询线程的状态。

可以停止线程通过调用 exit () 或 quit ()。在极端情况下，可能希望强制 terminate () 执行线程。然而，这样做是危险的且不鼓励。请阅读文档编制为 terminate () 和 setTerminationEnabled () 了解详细信息。

从 Qt 4.8 起，解除活在刚结束线程中对象的分配是可能的，通过连接 finished () 信号到 QObject::deleteLater ().

使用 wait () 去阻塞调用线程，直到其它线程已执行完成 (或直到指定时间已过去)。

静态函数 currentThreadId () 和 currentThread () 返回目前正执行线程的标识符。前者返回特定平台线程 ID。后者返回 QThread 指针。

要选取赋予线程的名称 (作为标识通过命令 ps -L 例如在 Linux)，可以调用 setObjectName() 在启动线程之前。若不调用 setObjectName() ，赋予线程的名称将是线程对象运行时类型的类名 (例如： "RenderThread" 在案例 Mandelbrot 范例，() 因为此名称针对 QThread 子类)。注意：目前这不可用于 Windows 发行构建。

QThread 还提供独立于平台的静态休眠函数： sleep (), msleep ()，和 usleep () 分别允许完整秒、毫秒及微秒分辨率。

注意： wait () 和 sleep () 函数一般是不必要的，因为 Qt 是事件驱动型框架。代替 wait ()，考虑监听 finished () 信号。代替 sleep () 函数，考虑使用 QTimer .

{Mandelbrot Example}, {Semaphores Example}, {Wait Conditions Example}

另请参阅 Qt 中的线程支持 , QThreadStorage ，和同步线程 .

成员类型文档编制

enum QThread:: Priority

此枚举类型指示操作系统应如何调度新近创建的线程。

常量	值	描述
`QThread::IdlePriority`	`0`	才调度，当没有其它线程在运行时。
`QThread::LowestPriority`	`1`	经常比 LowPriority 更少调度。
`QThread::LowPriority`	`2`	经常比 NormalPriority 更少调度。
`QThread::NormalPriority`	`3`	操作系统的默认优先级。
`QThread::HighPriority`	`4`	经常比 NormalPriority 更多调度。
`QThread::HighestPriority`	`5`	经常比 HighPriority 更多调度。
`QThread::TimeCriticalPriority`	`6`	尽可能经常调度。
`QThread::InheritPriority`	`7`	使用如创建线程的相同优先级。这是默认。

成员函数文档编制

QThread:: QThread ( QObject * parent = 0)

构造新的 QThread 管理新线程。 parent 拥有所有权对于 QThread 。线程不会被执行直到 start () 被调用。

另请参阅 start ().

QThread:: ~QThread ()

销毁 QThread .

注意：删除 QThread 对象不会停止其管理的线程的执行。删除正运行 QThread (即 isFinished () returns false) will probably result in a program crash. Wait for the finished () 信号先于删除 QThread .

`[static]` QThread * QThread:: currentThread ()

返回指针指向 QThread 由其管理目前正执行的线程。

`[static]` Qt::HANDLE QThread:: currentThreadId ()

返回目前执行线程的线程句柄。

警告： 由此函数返回的句柄可以用于内部目的，且不应用于任何应用程序代码中。

警告： 在 Windows，返回值是当前线程的伪句柄。它不可以用于数值比较。即：此函数返回由 Win32 函数 getCurrentThreadId() 返回的 DWORD (Windows 线程 ID)，而不是返回由 Win32 函数 getCurrentThread() 返回的 HANDLE (Windows 线程句柄)。

`[protected]` int QThread:: exec ()

进入事件循环并等待，直到 exit () 被调用，返回值被传递给 exit ()。返回值为 0 若 exit () 被调用凭借 quit ().

此函数意味着被调用从 run ()。它是必要的，去调用此函数以开始事件处理。

另请参阅 quit () 和 exit ().

void QThread:: exit ( int returnCode = 0)

告诉线程的事件循环采用返回代码退出。

在调用此函数之后，线程离开事件循环并返回从调用 QEventLoop::exec ()。 QEventLoop::exec () 函数返回 returnCode .

按约定， returnCode 0 意味着成功，任何非零值指示出错。

注意：不像同名 C 库函数，此函数 does 返回给调用者 -- 它停止事件处理。

没有 QEventLoop 会在此线程中被再次启动，直到 QThread::exec () 有被再次调用。若事件循环在 QThread::exec () 不在运行，则下一调用 QThread::exec () 也会立即返回。

另请参阅 quit () 和 QEventLoop .

`[signal]` void QThread:: finished ()

This signal is emitted when the thread has finished executing.

注意： 信号 finished 在此类中是重载。要使用函数指针句法连接到此信号，必须在静态铸造中指定信号类型，如此范例所示：

connect(thread, static_cast<void(QThread::*)()>(&QThread::finished),
    [=](){ /* ... */ });

另请参阅 started () 和 terminated ().

`[static]` int QThread:: idealThreadCount ()

返回可以在系统中运行的理想线程数。这的完成是查询系统中处理器的实际和逻辑两者核心数。此函数返回 -1 若无法检测处理器核心数。

bool QThread:: isFinished () const

Returns true if the thread is finished; otherwise returns false.

另请参阅 isRunning ().

bool QThread:: isRunning () const

Returns true if the thread is running; otherwise returns false.

另请参阅 isFinished ().

`[static protected]` void QThread:: msleep ( unsigned long msecs )

强制当前线程休眠 msecs 毫秒。

另请参阅 sleep () 和 usleep ().

Priority QThread:: priority () const

返回正运行线程的优先级。若线程未在运行，此函数返回 InheritPriority .

该函数在 Qt 4.1 引入。

另请参阅 Priority , setPriority ()，和 start ().

`[slot]` void QThread:: quit ()

告诉线程的事件循环采用返回代码 0 (成功) 退出。相当于调用 QThread::exit (0).

此函数什么都不做，若线程没有事件循环。

另请参阅 exit () 和 QEventLoop .

`[virtual protected]` void QThread:: run ()

线程的起点。先调用 start ()，新近创建的线程调用此函数。默认实现只需调用 exec ().

可以重实现此函数以促进高级线程管理。来自此方法的返回将结束线程的执行。

另请参阅 start () 和 wait ().

void QThread:: setPriority ( Priority priority )

此函数设置 priority 为正运行线程。若线程未在运行，此函数什么都不做并立即返回。使用 start () 去启动线程采用特定优先级。

The priority 自变量可以是任意值在 QThread::Priority 枚举除了 InheritPriorty .

作用为 priority 参数从属于操作系统的调度策略。尤其， priority 会被忽略，在不支持线程优先级的系统中 (如在 Linux，见 http://linux.die.net/man/2/sched_setscheduler 了解更多细节)。

该函数在 Qt 4.1 引入。

另请参阅 Priority , priority ()，和 start ().

void QThread:: setStackSize ( uint stackSize )

把线程的最大堆栈尺寸设为 stackSize 。若 stackSize 大于 0，最大堆栈尺寸被设为 stackSize 字节，否则，最大堆栈尺寸由操作系统自动确定。

警告： 大多数操作系统对线程堆栈大小，有最小和最大限制。线程将无法启动，若堆栈大小超出这些限制。

另请参阅 stackSize ().

`[static protected]` void QThread:: setTerminationEnabled ( bool enabled = true)

启用 (或禁用) 当前线程的终止，基于 enabled 参数。线程必须已被启动由 QThread .

当 enabled 为 false，终止被禁用。未来调用 QThread::terminate () 将立即返回没有效果。相反，终止被延期，直到终止被启用。

当 enabled 为 true，终止被启用。未来调用 QThread::terminate () 将正常终止线程。若终止已被延期 (即： QThread::terminate () 被调用采用终止被禁用)，此函数将终止调用线程 immediately 。注意：此函数不会返回，在此情况下。

另请参阅 terminate ().

`[static protected]` void QThread:: sleep ( unsigned long secs )

强制当前线程休眠 secs 秒。

另请参阅 msleep () 和 usleep ().

uint QThread:: stackSize () const

返回线程的最大堆栈尺寸 (若设置采用 setStackSize ())；否则返回 0。

另请参阅 setStackSize ().

`[slot]` void QThread:: start ( Priority priority = InheritPriority)

开始执行线程通过调用 run ()。操作系统将调度线程根据 priority 参数。若线程已经在运行，此函数什么都不做。

另请参阅 run () 和 terminate ().

`[signal]` void QThread:: started ()

This signal is emitted when the thread starts executing.

另请参阅 finished () 和 terminated ().

`[slot]` void QThread:: terminate ()

Terminates the execution of the thread. The thread may or may not be terminated immediately, depending on the operating system's scheduling policies. Listen for the terminated () signal, or use QThread::wait () 在 terminate() 之后，来确保。

当线程被终止时，等待线程完成的所有线程都将被唤醒。

警告： 此函数是危险的，且不鼓励使用。线程可以在其代码路径中的任何点被终止。线程可以被终止，当修改数据时。线程没有机会在本身、解锁任何保持互斥、等之后被清理。简而言之，若绝对有必要才使用此函数。

终止可以被明确启用 (或禁用) 通过调用 QThread::setTerminationEnabled ()。当终止被禁用时，调用此函数会导致终止被延期，直到终止被重新启用。见文档编制 QThread::setTerminationEnabled () 了解更多信息。

另请参阅 setTerminationEnabled ().

`[signal]` void QThread:: terminated ()

This signal is emitted when the thread is terminated.

另请参阅 started () 和 finished ().

`[static protected]` void QThread:: usleep ( unsigned long usecs )

强制当前线程休眠 usecs 微秒。

另请参阅 sleep () 和 msleep ().

bool QThread:: wait ( unsigned long time = ULONG_MAX)

阻塞线程，直到满足这些条件之一：

关联此线程的 QThread 对象已执行完成 (即：当它返回从 run ())。此函数将返回 true，若线程已完成。它也返回 true，若线程尚未被启动。
time 毫秒已过去。若 time 为 ULONG_MAX (默认)，那么等待将从不超时 (线程必须返回自 run ())。此函数将返回 false 若等待超时。

这提供的功能类似 POSIX pthread_join() 函数。

另请参阅 sleep () 和 terminate ().

`[static]` void QThread:: yieldCurrentThread ()

把当前线程的执行产生到另一可运行线程，若有的话。注意：操作系统决定切换到哪个线程。

内容