GLib.Thread¶

Fields¶

None

Methods¶

class	`error_quark` ()
class	`exit` (retval)
class	`new` (name, func, *data)
class	`self` ()
class	`try_new` (name, func, *data)
class	`yield_` ()
	`join` ()
	`ref` ()
	`unref` ()

Details¶

class GLib.Thread¶

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

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

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

classmethod error_quark()[source]¶

Return type:	`int`

classmethod exit(retval)[source]¶

Parameters:	retval (`object` or `None`) – the return value of this thread

Terminates the current thread.

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

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

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

classmethod new(name, func, *data)[source]¶

Parameters:	name (`str` or `None`) – an (optional) name for the new thread func (`GLib.ThreadFunc`) – a function to execute in the new thread data (`object` or `None`) – an argument to supply to the new thread
Returns:	the new `GLib.Thread`
Return type:	`GLib.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 GLib.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 GLib.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 GLib.Thread.try_new() if you want to attempt to deal with failures.

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

To free the struct returned by this function, use GLib.Thread.unref(). Note that GLib.Thread.join() implicitly unrefs the GLib.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.

New in version 2.32.

classmethod self()[source]¶

Returns:	the `GLib.Thread` representing the current thread
Return type:	`GLib.Thread`

This function returns the GLib.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 GLib.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 GLib.Thread.join()) on these threads.

classmethod try_new(name, func, *data)[source]¶

Parameters:	name (`str` or `None`) – an (optional) name for the new thread func (`GLib.ThreadFunc`) – a function to execute in the new thread data (`object` or `None`) – an argument to supply to the new thread
Raises:	`GLib.Error`
Returns:	the new `GLib.Thread`, or `None` if an error occurred
Return type:	`GLib.Thread`

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

New in version 2.32.

classmethod yield_()[source]¶

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.

join()[source]¶

Returns:	the return value of the thread
Return type:	`object` or `None`

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

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

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

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

ref()[source]¶

Returns:	a new reference to self
Return type:	`GLib.Thread`

Increase the reference count on self.

New in version 2.32.

unref()[source]¶

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

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

New in version 2.32.