Class Thread

java.lang.Object
org.javagi.base.ProxyInstance
org.gnome.glib.Thread
All Implemented Interfaces:
Proxy
@Generated("org.javagi.JavaGI") public class Thread extends ProxyInstance

The GThread struct represents a running thread. This struct is returned by g_thread_new() or g_thread_try_new(). You can obtain the GThread struct representing the current thread by calling g_thread_self().

GThread is refcounted, see g_thread_ref() and g_thread_unref(). The thread represented by it holds a reference while it is running, and g_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.

  • Constructor Details

    • Thread

      public Thread(MemorySegment address)
      Create a Thread proxy instance for the provided memory address.
      Parameters:
      address - the memory address of the native object

    • Thread

      public Thread(@Nullable String name, @Nullable ThreadFunc func)

      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 g_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 g_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 g_thread_try_new() if you want to attempt to deal with failures.

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

      To free the struct returned by this function, use g_thread_unref(). Note that g_thread_join() implicitly unrefs the GThread 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
      Since:
      2.32

  • Method Details

    • getType

      public static @Nullable Type getType()
      Get the GType of the Thread class.
      Returns:
      the GType

    • getMemoryLayout

      public static MemoryLayout getMemoryLayout()
      The memory layout of the native struct.
      Returns:
      the memory layout

    • readFunc

      public @Nullable ThreadFunc readFunc()
      Read the value of the field func.
      Returns:
      The value of the field func

    • writeFunc

      public void writeFunc(@Nullable ThreadFunc func, Arena _arena)
      Write a value in the field func.
      Parameters:
      func - The new value for the field func
      _arena - to control the memory allocation scope

    • readData

      public MemorySegment readData()
      Read the value of the field data.
      Returns:
      The value of the field data

    • writeData

      public void writeData(MemorySegment data)
      Write a value in the field data.
      Parameters:
      data - The new value for the field data

    • readJoinable

      public boolean readJoinable()
      Read the value of the field joinable.
      Returns:
      The value of the field joinable

    • writeJoinable

      public void writeJoinable(boolean joinable)
      Write a value in the field joinable.
      Parameters:
      joinable - The new value for the field joinable

    • readPriority

      public ThreadPriority readPriority()
      Read the value of the field priority.
      Returns:
      The value of the field priority

    • writePriority

      public void writePriority(ThreadPriority priority)
      Write a value in the field priority.
      Parameters:
      priority - The new value for the field priority

    • tryNew

      public static Thread tryNew(@Nullable String name, @Nullable ThreadFunc func) throws GErrorException

      This function is the same as g_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 null is returned.

      Parameters:
      name - an (optional) name for the new thread
      func - a function to execute in the new thread
      Returns:
      the new GThread, or null if an error occurred
      Throws:
      GErrorException - see GError
      Since:
      2.32

    • create

      @Deprecated public static Thread create(@Nullable ThreadFunc func, boolean joinable) throws GErrorException
      Deprecated.
      Use g_thread_new() instead

      This function creates a new thread.

      The new thread executes the function func with the argument data. If the thread was created successfully, it is returned.

      error can be null to ignore errors, or non-null to report errors. The error is set, if and only if the function returns null.

      This function returns a reference to the created thread only if joinable is true. In that case, you must free this reference by calling g_thread_unref() or g_thread_join(). If joinable is false then you should probably not touch the return value.

      Parameters:
      func - a function to execute in the new thread
      joinable - should this thread be joinable?
      Returns:
      the new GThread on success
      Throws:
      GErrorException - see GError

    • createFull

      @Deprecated public static Thread createFull(@Nullable ThreadFunc func, int stackSize, boolean joinable, boolean bound, ThreadPriority priority) throws GErrorException
      Deprecated.
      The bound and priority arguments are now ignored. Use g_thread_new().
      This function creates a new thread.
      Parameters:
      func - a function to execute in the new thread.
      stackSize - a stack size for the new thread.
      joinable - should this thread be joinable?
      bound - ignored
      priority - ignored
      Returns:
      the new GThread on success.
      Throws:
      GErrorException - see GError

    • errorQuark

      public static Quark errorQuark()

    • exit

      public static void exit(@Nullable MemorySegment retval)

      Terminates the current thread.

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

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

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

      Parameters:
      retval - the return value of this thread

    • foreach

      @Deprecated public static void foreach(@Nullable Func threadFunc)
      Deprecated.
      There aren't many things you can do with a GThread, except comparing it with one that was returned from g_thread_create(). There are better ways to find out if your thread is still alive.

      Call threadFunc on all GThreads that have been created with g_thread_create().

      Note that threads may decide to exit while threadFunc is running, so without intimate knowledge about the lifetime of foreign threads, threadFunc shouldn't access the GThread* pointer passed in as first argument. However, threadFunc will not be called for threads which are known to have exited already.

      Due to thread lifetime checks, this function has an execution complexity which is quadratic in the number of existing threads.

      Parameters:
      threadFunc - function to call for all GThread structures
      Since:
      2.10

    • getInitialized

      public static boolean getInitialized()
      Indicates if g_thread_init() has been called.
      Returns:
      true if threads have been initialized.
      Since:
      2.20

    • init

      @Deprecated public static void init(@Nullable MemorySegment vtable)
      Deprecated.
      This function is no longer necessary. The GLib threading system is automatically initialized at the start of your program.

      If you use GLib from more than one thread, you must initialize the thread system by calling g_thread_init().

      Since version 2.24, calling g_thread_init() multiple times is allowed, but nothing happens except for the first call.

      Since version 2.32, GLib does not support custom thread implementations anymore and the vtable parameter is ignored and you should pass null.

      ::: note g_thread_init() must not be called directly or indirectly in a callback from GLib. Also no mutexes may be currently locked while calling g_thread_init().

      ::: note To use g_thread_init() in your program, you have to link with the libraries that the command pkg-config --libs gthread-2.0 outputs. This is not the case for all the other thread-related functions of GLib. Those can be used without having to link with the thread libraries.

      Parameters:
      vtable - a function table of type GThreadFunctions, that provides the entry points to the thread system to be used. Since 2.32, this parameter is ignored and should always be null

    • initWithErrorcheckMutexes

      public static void initWithErrorcheckMutexes(@Nullable MemorySegment vtable)

    • self

      public static Thread self()

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

      This function will return a GThread 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 g_thread_join()) on these threads.

      Returns:
      the GThread representing the current thread

    • yield

      public static void yield()

      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.

    • getName

      public String getName()

      Gets the name of the thread.

      This function is intended for debugging purposes.

      Returns:
      the name of the thread
      Since:
      2.84

    • join

      public @Nullable MemorySegment join()

      Waits until this Thread finishes, i.e. the function func, as given to g_thread_new(), returns or g_thread_exit() is called. If this Thread has already terminated, then g_thread_join() returns immediately.

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

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

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

      Returns:
      the return value of the thread

    • ref

      public Thread ref()
      Increase the reference count on thread.
      Returns:
      a new reference to this Thread
      Since:
      2.32

    • setPriority

      @Deprecated public void setPriority(ThreadPriority priority)
      Deprecated.
      Thread priorities no longer have any effect.
      This function does nothing.
      Parameters:
      priority - ignored

    • unref

      public void unref()

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

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

      Since:
      2.32