Package org.gnome.glib

Class Thread

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.glib.Thread

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.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 Summary

Constructors

Constructor	Description
Thread(@Nullable String name, ThreadFunc func)	This function creates a new thread.
Thread(MemorySegment address)	Create a Thread proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
static Thread	create(ThreadFunc func, boolean joinable)	Deprecated. Use g_thread_new() instead
static Thread	createFull(ThreadFunc func, int stackSize, boolean joinable, boolean bound, ThreadPriority priority)	Deprecated. The bound and priority arguments are now ignored.
static Quark	errorQuark()
static void	exit(@Nullable MemorySegment retval)	Terminates the current thread.
static void	foreach(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().
static boolean	getInitialized()	Indicates if g_thread_init() has been called.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
static Type	getType()	Get the GType of the Thread class
static void	init(@Nullable MemorySegment vtable)	Deprecated. This function is no longer necessary.
static void	initWithErrorcheckMutexes(@Nullable MemorySegment vtable)
MemorySegment	join()	Waits until this Thread finishes, i.e.
MemorySegment	readData()	Read the value of the field data.
ThreadFunc	readFunc()	Read the value of the field func.
boolean	readJoinable()	Read the value of the field joinable.
ThreadPriority	readPriority()	Read the value of the field priority.
Thread	ref()	Increase the reference count on this Thread.
static Thread	self()	This function returns the GThread corresponding to the current thread.
void	setPriority(ThreadPriority priority)	Deprecated. Thread priorities no longer have any effect.
static Thread	tryNew(@Nullable String name, ThreadFunc func)	This function is the same as g_thread_new() except that it allows for the possibility of failure.
void	unref()	Decrease the reference count on this Thread, possibly freeing all resources associated with it.
void	writeData(MemorySegment data)	Write a value in the field data.
void	writeFunc(ThreadFunc func, Arena _arena)	Write a value in the field func.
void	writeJoinable(boolean joinable)	Write a value in the field joinable.
void	writePriority(ThreadPriority priority)	Write a value in the field priority.
static void	yield()	Causes the calling thread to voluntarily relinquish the CPU, so that other threads can run.

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

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
 @Nullable String name,
 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

Method Details

getType

public static 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 ThreadFunc readFunc()

Read the value of the field func.

Returns:

The value of the field func

writeFunc

public void writeFunc(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
 @Nullable String name,
 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

create

@Deprecated
public static Thread create(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(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
 @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(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

getInitialized

public static boolean getInitialized()

Indicates if g_thread_init() has been called.

Returns:

true if threads have been initialized.

init

@Deprecated
public static void init(@Nullable
 @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
 @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.

join

public 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 this 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 this Thread.

Returns:

a new reference to this Thread

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 this 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.