:right-sidebar: True Thread =================================================================== .. currentmodule:: gi.repository.GLib .. class:: Thread(*args, **kwargs) :no-contents-entry: The :obj:`~gi.repository.GLib.Thread` struct represents a running thread. This struct is returned by :func:`~gi.repository.GLib.Thread.new` or :func:`~gi.repository.GLib.Thread.try_new`. You can obtain the :obj:`~gi.repository.GLib.Thread` struct representing the current thread by calling :func:`~gi.repository.GLib.Thread.self`. GThread is refcounted, see :func:`~gi.repository.GLib.Thread.ref` and :func:`~gi.repository.GLib.Thread.unref`. The thread represented by it holds a reference while it is running, and :func:`~gi.repository.GLib.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 ------------ .. rst-class:: interim-class .. class:: Thread :no-index: .. classmethod:: new(name: str | None, func: ~typing.Callable[[~typing.Any], ~typing.Any | None], data: ~typing.Any = None) -> ~gi.repository.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 :func:`~gi.repository.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 :func:`~gi.repository.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 :func:`~gi.repository.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, :obj:`~gi.repository.GLib.ThreadPool` may be more appropriate than manually spawning and tracking multiple :obj:`~gi.repository.GLib.Thread`\. To free the struct returned by this function, use :func:`~gi.repository.GLib.Thread.unref`. Note that :func:`~gi.repository.GLib.Thread.join` implicitly unrefs the :obj:`~gi.repository.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. .. versionadded:: 2.32 :param name: an (optional) name for the new thread :param func: a function to execute in the new thread :param data: an argument to supply to the new thread .. classmethod:: try_new(name: str | None, func: ~typing.Callable[[~typing.Any], ~typing.Any | None], data: ~typing.Any = None) -> ~gi.repository.GLib.Thread This function is the same as :func:`~gi.repository.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 :const:`None` is returned. .. versionadded:: 2.32 :param name: an (optional) name for the new thread :param func: a function to execute in the new thread :param data: an argument to supply to the new thread Methods ------- .. rst-class:: interim-class .. class:: Thread :no-index: .. classmethod:: error_quark() -> int .. classmethod:: exit() -> None Terminates the current thread. If another thread is waiting for us using :func:`~gi.repository.GLib.Thread.join` then the waiting thread will be woken up and get ``retval`` as the return value of :func:`~gi.repository.GLib.Thread.join`. Calling :func:`~gi.repository.GLib.Thread.exit` with a parameter ``retval`` is equivalent to returning ``retval`` from the function ``func``\, as given to :func:`~gi.repository.GLib.Thread.new`. You must only call :func:`~gi.repository.GLib.Thread.exit` from a thread that you created yourself with :func:`~gi.repository.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 :obj:`~gi.repository.GLib.ThreadPool`\. .. method:: join() -> ~typing.Any | None Waits until ``thread`` finishes, i.e. the function ``func``\, as given to :func:`~gi.repository.GLib.Thread.new`, returns or :func:`~gi.repository.GLib.Thread.exit` is called. If ``thread`` has already terminated, then :func:`~gi.repository.GLib.Thread.join` returns immediately. Any thread can wait for any other thread by calling :func:`~gi.repository.GLib.Thread.join`, not just its 'creator'. Calling :func:`~gi.repository.GLib.Thread.join` from multiple threads for the same ``thread`` leads to undefined behaviour. The value returned by ``func`` or given to :func:`~gi.repository.GLib.Thread.exit` is returned by this function. :func:`~gi.repository.GLib.Thread.join` consumes the reference to the passed-in ``thread``\. This will usually cause the :obj:`~gi.repository.GLib.Thread` struct and associated resources to be freed. Use :func:`~gi.repository.GLib.Thread.ref` to obtain an extra reference if you want to keep the GThread alive beyond the :func:`~gi.repository.GLib.Thread.join` call. .. classmethod:: self() -> ~gi.repository.GLib.Thread This function returns the :obj:`~gi.repository.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 :obj:`~gi.repository.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 :func:`~gi.repository.GLib.Thread.join`) on these threads. .. classmethod:: yield_() -> None Fields ------ .. rst-class:: interim-class .. class:: Thread :no-index: .. attribute:: data .. attribute:: func .. attribute:: joinable .. attribute:: priority