Thread#

class Thread(*args, **kwargs)#

The Thread struct represents a running thread. This struct is returned by new() or try_new(). You can obtain the Thread struct representing the current thread by calling self().

GThread is refcounted, see ref() and unref(). The thread represented by it holds a reference while it is running, and join() consumes the reference that it is given, so it is normally not necessary to manage GThread references explicitly.

The structure is opaque – none of its fields may be directly accessed.

Constructors#

class Thread
classmethod new(name: str | None, func: Callable[[Any], Any | None], data: Any = None) → Thread#

This function creates a new thread. The new thread starts by invoking func with the argument data. The thread will run until func returns or until exit() is called from the new thread. The return value of func becomes the return value of the thread, which can be obtained with join().

The name can be useful for discriminating threads in a debugger. It is not used for other purposes and does not have to be unique. Some systems restrict the length of name to 16 bytes.

If the thread can not be created the program aborts. See try_new() if you want to attempt to deal with failures.

If you are using threads to offload (potentially many) short-lived tasks, ThreadPool may be more appropriate than manually spawning and tracking multiple Thread.

To free the struct returned by this function, use unref(). Note that join() implicitly unrefs the Thread as well.

New threads by default inherit their scheduler policy (POSIX) or thread priority (Windows) of the thread creating the new thread.

This behaviour changed in GLib 2.64: before threads on Windows were not inheriting the thread priority but were spawned with the default priority. Starting with GLib 2.64 the behaviour is now consistent between Windows and POSIX and all threads inherit their parent thread’s priority.

Added in version 2.32.

Parameters:

  • name – an (optional) name for the new thread

  • func – a function to execute in the new thread

  • data – an argument to supply to the new thread

classmethod try_new(name: str | None, func: Callable[[Any], Any | None], data: Any = None) → Thread#

This function is the same as new() except that it allows for the possibility of failure.

If a thread can not be created (due to resource limits), error is set and None is returned.

Added in version 2.32.

Parameters:

  • name – an (optional) name for the new thread

  • func – a function to execute in the new thread

  • data – an argument to supply to the new thread

Methods#

class Thread
classmethod error_quark() → int#
classmethod exit() → None#

Terminates the current thread.

If another thread is waiting for us using join() then the waiting thread will be woken up and get retval as the return value of join().

Calling exit() with a parameter retval is equivalent to returning retval from the function func, as given to new().

You must only call exit() from a thread that you created yourself with new() or related APIs. You must not call this function from a thread created with another threading library or or from within a ThreadPool.

join() → Any | None#

Waits until thread finishes, i.e. the function func, as given to new(), returns or exit() is called. If thread has already terminated, then join() returns immediately.

Any thread can wait for any other thread by calling join(), not just its ‘creator’. Calling join() from multiple threads for the same thread leads to undefined behaviour.

The value returned by func or given to exit() is returned by this function.

join() consumes the reference to the passed-in thread. This will usually cause the Thread struct and associated resources to be freed. Use ref() to obtain an extra reference if you want to keep the GThread alive beyond the join() call.

classmethod self() → Thread#

This function returns the Thread corresponding to the current thread. Note that this function does not increase the reference count of the returned struct.

This function will return a Thread even for threads that were not created by GLib (i.e. those created by other threading APIs). This may be useful for thread identification purposes (i.e. comparisons) but you must not use GLib functions (such as join()) on these threads.

classmethod yield_() → None#

Fields#

class Thread
data#
func#
joinable#
priority#