GLib.Thread

record (struct)

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

GThread is refcounted, see Thread.ref and Thread.unref. The thread represented by it holds a reference while it is running, and Thread.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

new

@classmethod
def new(cls, name: str | None, func: ThreadFunc) -> 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 Thread.exit is called from the new thread. The return value of func becomes the return value of the thread, which can be obtained with Thread.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 Thread.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 GThreads.

To free the struct returned by this function, use Thread.unref. Note that Thread.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.

Parameters:

• name — an (optional) name for the new thread
• func — a function to execute in the new thread

try_new

@classmethod
def try_new(cls, name: str | None, func: ThreadFunc) -> Thread

This function is the same as Thread.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.

Parameters:

• name — an (optional) name for the new thread
• func — a function to execute in the new thread

Methods

get_name

def get_name(self) -> str

Gets the name of the thread.

This function is intended for debugging purposes.

join

def join(self) -> int | None

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

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

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

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

ref

def ref(self) -> Thread

Increase the reference count on thread.

unref

def unref(self) -> None

Decrease the reference count on thread, possibly freeing all resources associated with it.

Note that each thread holds a reference to its Thread while it is running, so it is safe to drop your own reference to it if you don't need it anymore.

Static functions

error_quark

@staticmethod
def error_quark() -> Quark

exit

@staticmethod
def exit(retval: int | None = ...) -> None

Terminates the current thread.

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

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

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

Parameters:

• retval — the return value of this thread

self

@staticmethod
def 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 Thread.join) on these threads.

yield_

@staticmethod
def yield_() -> None

Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run.

This function is often used as a method to make busy wait less evil.

Properties

func

func: ThreadFunc  # read/write

data

data: int  # read/write

joinable

joinable: bool  # read/write