napari.qt.threading.WorkerBase

class napari.qt.threading.WorkerBase(func=None, SignalsClass=<class 'superqt.utils._qthreading.WorkerBaseSignals'>)[source]

Bases: PyQt5.QtCore.QRunnable, Generic[superqt.utils._qthreading._R]

Base class for creating a Worker that can run in another thread.

Parameters

SignalsClass (type, optional) – A QObject subclass that contains signals, by default WorkerBaseSignals

signals

signal emitter object. To allow identify which worker thread emitted signal.

Type

WorkerBaseSignals

Methods

Attributes

property abort_requested

Whether the worker has been requested to stop.

Return type

bool

autoDelete(self)bool
classmethod await_workers(msecs=None)[source]

Ask all workers to quit, and wait up to msec for quit.

Attempts to clean up all running workers by calling worker.quit() method. Any workers in the WorkerBase._worker_set set will have this method.

By default, this function will block indefinitely, until worker threads finish. If a timeout is provided, a RuntimeError will be raised if the workers do not gracefully exit in the time requests, but the threads will NOT be killed. It is (currently) left to the user to use their OS to force-quit rogue threads.

Important

If the user does not put any yields in their function, and the function is super long, it will just hang… For instance, there’s no graceful way to kill this thread in python:

@thread_worker
def ZZZzzz():
    time.sleep(10000000)

This is why it’s always advisable to use a generator that periodically yields for long-running computations in another thread.

See this stack-overflow post for a good discussion on the difficulty of killing a rogue python thread:

Parameters

msecs (int, optional) – Waits up to msecs milliseconds for all threads to exit and removes all threads from the thread pool. If msecs is None (the default), the timeout is ignored (waits for the last thread to exit).

Raises

RuntimeError – If a timeout is provided and workers do not quit successfully within the time allotted.

Return type

None

create(Callable[[], None])QRunnable
property is_running

Whether the worker has been started

Return type

bool

quit()[source]

Send a request to abort the worker.

Note

It is entirely up to subclasses to honor this method by checking self.abort_requested periodically in their worker.work method, and exiting if True.

Return type

None

run()[source]

Start the worker.

The end-user should never need to call this function. But it cannot be made private or renamed, since it is called by Qt.

The order of method calls when starting a worker is:

calls QThreadPool.globalInstance().start(worker)
|               triggered by the QThreadPool.start() method
|               |             called by worker.run
|               |             |
V               V             V
worker.start -> worker.run -> worker.work

This is the function that actually gets called when calling QThreadPool.start(worker)(). It simply wraps the work() method, and emits a few signals. Subclasses should NOT override this method (except with good reason), and instead should implement work().

Return type

None

setAutoDelete(self, bool)
start()[source]

Start this worker in a thread and add it to the global threadpool.

The order of method calls when starting a worker is:

calls QThreadPool.globalInstance().start(worker)
|               triggered by the QThreadPool.start() method
|               |             called by worker.run
|               |             |
V               V             V
worker.start -> worker.run -> worker.work
Return type

None

work()[source]

Main method to execute the worker.

The end-user should never need to call this function. But subclasses must implement this method (See GeneratorFunction.work() for an example implementation). Minimally, it should check self.abort_requested periodically and exit if True.

Examples

class MyWorker(WorkerBase):

    def work(self):
        i = 0
        while True:
            if self.abort_requested:
                self.aborted.emit()
                break
            i += 1
            if i > max_iters:
                break
            time.sleep(0.5)
Return type

Union[Exception, ~_R]