guikit.threads

Contains all the machinery for dealing with threads.

Module Contents

Classes

ThreadResult

Simple event to carry arbitrary result data.

WorkerThread

Worker Thread Class.

ThreadPool

Functions

run_thread(target[, on_abort, on_complete, on_error, ...])

Is an alias for ThreadPool().run_thread(...).

run_daemon(target[, on_abort, on_complete, on_error])

Is an alias for ThreadPool().run_thread(..., daemon=True).

abort_thread(ident)

Set thread with given identifier to abort.

should_abort()

Return whether the thread with given identifier should abort or not.
class guikit.threads.ThreadResult(data, event_type)

Bases: wx.PyEvent

Simple event to carry arbitrary result data.

Parameters:

  • data (Any) –

  • event_type (int) –

class guikit.threads.WorkerThread(target, on_abort=None, on_complete=None, on_error=None, daemon=None)

Bases: threading.Thread

Worker Thread Class.

Parameters:

  • target (Callable) –

  • on_abort (Optional[Callable]) –

  • on_complete (Optional[Callable]) –

  • on_error (Optional[Callable]) –

  • daemon (Optional[bool]) –

connect_events(window)

Connect the complete, abort and error events to the functions to execute.

Parameters:

window (wx.Frame) – The main window of the program.

Return type:

None

run()

Run worker thread and deals with the wrapping up accordingly.

on_abort(event)

To execute when the thread execution is aborted.

Parameters:

event (ThreadResult) – The event object with the relevant output data

on_complete(event)

To execute when the thread execution is completed normally.

Parameters:

event (ThreadResult) – The event object with the relevant output data

on_error(event)

To execute when the thread ends with an error.

Parameters:

event (ThreadResult) – The exception raised

class guikit.threads.ThreadPool(window=None)
Parameters:

window (Optional[wx.Frame]) –

_instance: Optional[ThreadPool]
get_thread(ident)

Get the worker thread referred to with ident in a thread-safe manner.

Parameters:

ident (int) – Thread identifier

Raises:

KeyError – If the thread identifier is not in the ThreadPool

Return type:

WorkerThread

run_thread(target, on_abort=None, on_complete=None, on_error=None, daemon=None)

Runs a new thread executing the target callable on it.

The thread will run until:

  • The ‘target’ function returns

  • An exception is raised

The target function might finish because it has completed what it was doing. In that case, ‘on_complete’ is executed after returning from target.

It might also finish because it is monitoring the value of ThreadPool().query_abort() and this is True. In that case, target should return with an appropriate value and on_abort is then executed.

Finally, an exception might occur in the thread. In this case, the exception is caught and on_error is executed.

on_complete, on_abort and on_error are all executed in the main thread.

Parameters:

  • target (Callable) – The function to be executed in a separate thread.

  • on_abort (Optional[Callable]) – The function to be executed when the target function is aborted. Takes as input the value returned by target.

  • on_complete (Optional[Callable]) – The function to be executed when the target function is completed normally. Takes as input the value returned by target.

  • on_error (Optional[Callable]) – The function to be executed when an exception is raised in the target. Takes as input the exception raised.

  • daemon (Optional[bool]) – If the function is a daemonic function.

Returns:

The id number for the thread, needed if it is to be aborted externally.

Return type:

int

query_abort()

Check if the current thread is to be aborted.

Raises:

KeyError – If the thread identifier is not in the ThreadPool

Return type:

bool

abort_thread(ident)

Flag the thread with ident to be aborted.

Parameters:

ident (int) – Thread identifier

Raises:

KeyError – If the thread identifier is not in the ThreadPool

Return type:

None

join_thread(ident)

Join the thread specified by ident.

Parameters:

ident (int) – Thread identifier

Raises:

KeyError – If the thread identifier is not in the ThreadPool

Return type:

None

post_event(event)

Adds an event to the event loop of the main thread.

Parameters:

event (ThreadResult) –

stop_threads()

Stop all worker threads and wait for them to finish.

guikit.threads.run_thread(target, on_abort=None, on_complete=None, on_error=None, daemon=None)

Is an alias for ThreadPool().run_thread(…).

Parameters:

  • target (Callable) –

  • on_abort (Optional[Callable]) –

  • on_complete (Optional[Callable]) –

  • on_error (Optional[Callable]) –

  • daemon (Optional[bool]) –

Return type:

int

guikit.threads.run_daemon(target, on_abort=None, on_complete=None, on_error=None)

Is an alias for ThreadPool().run_thread(…, daemon=True).

Parameters:

  • target (Callable) –

  • on_abort (Optional[Callable]) –

  • on_complete (Optional[Callable]) –

  • on_error (Optional[Callable]) –

Return type:

int

guikit.threads.abort_thread(ident)

Set thread with given identifier to abort.

Parameters:

ident (int) – Thread identifier

Return type:

None

guikit.threads.should_abort()

Return whether the thread with given identifier should abort or not.

Return type:

bool