napari.qt.threading#

Classes

`FunctionWorker`
`GeneratorWorker`
`GeneratorWorkerSignals`
`WorkerBase`	Base class for creating a Worker that can run in another thread.
`WorkerBaseSignals`

Functions

Convenience function to start a function in another thread.

By default, uses Worker, but a custom WorkerBase subclass may be provided. If so, it must be a subclass of Worker, which defines a standard set of signals and a run method.

Parameters:

func (Callable) – The function to call in another thread.
_start_thread (bool, optional) – Whether to immediaetly start the thread. If False, the returned worker must be manually started with worker.start(). by default it will be False if the _connect argument is None, otherwise True.
_connect (Dict[str, Union[Callable, Sequence]], optional) – A mapping of "signal_name" -> callable or list of callable: callback functions to connect to the various signals offered by the worker class. by default None
_progress (Union[bool, Dict[str, Union[int, bool, str]]], optional) – Can be True, to provide indeterminate progress bar, or dictionary. If dict, requires mapping of ‘total’ to number of expected yields. If total is not provided, progress bar will be indeterminate. Will connect progress bar update to yields and display this progress in the viewer. Can also take a mapping of ‘desc’ to the progress bar description. Progress bar will become indeterminate when number of yields exceeds ‘total’. By default None.
_worker_class (Type[WorkerBase], optional) – The :class`WorkerBase` to instantiate, by default FunctionWorker will be used if func is a regular function, and GeneratorWorker will be used if it is a generator.
_ignore_errors (bool, optional) – If False (the default), errors raised in the other thread will be reraised in the main thread (makes debugging significantly easier).
*args – will be passed to func
**kwargs – will be passed to func

Returns:

worker – An instantiated worker. If _start_thread was False, the worker will have a .start() method that can be used to start the thread.

Return type:

WorkerBase

Raises:

TypeError – If a worker_class is provided that is not a subclass of WorkerBase.
TypeError – If _connect is provided and is not a dict of {str: callable}
TypeError – If _progress is provided and function is not a generator

Examples

def long_function(duration):
    import time
    time.sleep(duration)

worker = create_worker(long_function, 10)

Decorator that runs a function in a separate thread when called.

When called, the decorated function returns a WorkerBase. See create_worker() for additional keyword arguments that can be used when calling the function.

The returned worker will have these signals:

started: emitted when the work is started
finished: emitted when the work is finished
returned: emitted with return value
errored: emitted with error object on Exception

It will also have a worker.start() method that can be used to start execution of the function in another thread. (useful if you need to connect callbacks to signals prior to execution)

If the decorated function is a generator, the returned worker will also provide these signals:

yielded: emitted with yielded values
paused: emitted when a running job has successfully paused
resumed: emitted when a paused job has successfully resumed
aborted: emitted when a running job is successfully aborted

And these methods:

quit: ask the thread to quit
toggle_paused: toggle the running state of the thread.
send: send a value into the generator. (This requires that your
decorator function uses the value = yield syntax)

Parameters:

function (callable) – Function to call in another thread. For communication between threads may be a generator function.
start_thread (bool, optional) – Whether to immediaetly start the thread. If False, the returned worker must be manually started with worker.start(). by default it will be False if the _connect argument is None, otherwise True.
connect (Dict[str, Union[Callable, Sequence]], optional) – A mapping of "signal_name" -> callable or list of callable: callback functions to connect to the various signals offered by the worker class. by default None
progress (Union[bool, Dict[str, Union[int, bool, str]]], optional) – Can be True, to provide indeterminate progress bar, or dictionary. If dict, requires mapping of ‘total’ to number of expected yields. If total is not provided, progress bar will be indeterminate. Will connect progress bar update to yields and display this progress in the viewer. Can also take a mapping of ‘desc’ to the progress bar description. Progress bar will become indeterminate when number of yields exceeds ‘total’. By default None. Must be used in conjunction with a generator function.
worker_class (Type[WorkerBase], optional) – The :class`WorkerBase` to instantiate, by default FunctionWorker will be used if func is a regular function, and GeneratorWorker will be used if it is a generator.
ignore_errors (bool, optional) – If False (the default), errors raised in the other thread will be reraised in the main thread (makes debugging significantly easier).

Returns:

function that creates a worker, puts it in a new thread and returns the worker instance.

Return type:

callable

Examples

@thread_worker
def long_function(start, end):
    # do work, periodically yielding
    i = start
    while i <= end:
        time.sleep(0.1)
        yield i

    # do teardown
    return 'anything'

# call the function to start running in another thread.
worker = long_function()
# connect signals here if desired... or they may be added using the
# `connect` argument in the `@thread_worker` decorator... in which
# case the worker will start immediately when long_function() is called
worker.start()