Package org.gnome.glib

Class Cond

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.glib.Cond

All Implemented Interfaces:

Proxy

@Generated("io.github.jwharm.JavaGI")
public class Cond
extends ProxyInstance

The GCond struct is an opaque data structure that represents a condition. Threads can block on a GCond if they find a certain condition to be false. If other threads change the state of this condition they signal the GCond, and that causes the waiting threads to be woken up.

Consider the following example of a shared variable. One or more threads can wait for data to be published to the variable and when another thread publishes the data, it can signal one of the waiting threads to wake up to collect the data.

Here is an example for using GCond to block a thread until a condition is satisfied:

  gpointer current_data = NULL;
   GMutex data_mutex;
   GCond data_cond;

   void
   push_data (gpointer data)
   {
     g_mutex_lock (&data_mutex);
     current_data = data;
     g_cond_signal (&data_cond);
     g_mutex_unlock (&data_mutex);
   }

   gpointer
   pop_data (void)
   {
     gpointer data;

     g_mutex_lock (&data_mutex);
     while (!current_data)
       g_cond_wait (&data_cond, &data_mutex);
     data = current_data;
     current_data = NULL;
     g_mutex_unlock (&data_mutex);

     return data;
   }
 

Whenever a thread calls pop_data() now, it will wait until current_data is non-null, i.e. until some other thread has called push_data().

The example shows that use of a condition variable must always be paired with a mutex. Without the use of a mutex, there would be a race between the check of currentData by the while loop in pop_data() and waiting. Specifically, another thread could set currentData after the check, and signal the cond (with nobody waiting on it) before the first thread goes to sleep. GCond is specifically useful for its ability to release the mutex and go to sleep atomically.

It is also important to use the g_cond_wait() and g_cond_wait_until() functions only inside a loop which checks for the condition to be true. See g_cond_wait() for an explanation of why the condition may not be true even after it returns.

If a GCond is allocated in static storage then it can be used without initialisation. Otherwise, you should call g_cond_init() on it and g_cond_clear() when done.

A GCond should only be accessed via the g_cond_ functions.

Constructor Summary

Constructors

Constructor	Description
Cond()	Allocate a new Cond.
Cond(Arena arena)	Allocate a new Cond.
Cond(MemorySegment address)	Create a Cond proxy instance for the provided memory address.
Cond(MemorySegment p, int[] i)	Allocate a new Cond with the fields set to the provided values.
Cond(MemorySegment p, int[] i, Arena arena)	Allocate a new Cond with the fields set to the provided values.

Method Summary

Modifier and Type	Method	Description
void	broadcast()	If threads are waiting for this Cond, all of them are unblocked.
void	clear()	Frees the resources allocated to a GCond with g_cond_init().
void	free()	Deprecated. GCond can now be statically allocated, or embedded in structures and initialised with g_cond_init().
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
void	init()	Initialises a GCond so that it can be used.
static Cond	new_()	Deprecated. GCond can now be statically allocated, or embedded in structures and initialised with g_cond_init().
int[]	readI()	Read the value of the field i.
MemorySegment	readP()	Read the value of the field p.
void	signal()	If threads are waiting for this Cond, at least one of them is unblocked.
boolean	timedWait(Mutex mutex, TimeVal absTime)	Deprecated. Use g_cond_wait_until() instead.
void	wait_(Mutex mutex)	Atomically releases mutex and waits until this Cond is signalled.
boolean	waitUntil(Mutex mutex, long endTime)	Waits until either this Cond is signalled or endTime has passed.
void	writeI(int[] i, Arena _arena)	Write a value in the field i.
void	writeP(MemorySegment p)	Write a value in the field p.

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

Cond

public Cond(MemorySegment address)

Create a Cond proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Cond

public Cond(Arena arena)

Allocate a new Cond.

Parameters:

arena - to control the memory allocation scope

Cond

public Cond()

Allocate a new Cond. The memory is allocated with Arena.ofAuto().

Cond

public Cond(MemorySegment p,
 int[] i,
 Arena arena)

Allocate a new Cond with the fields set to the provided values.

Parameters:

p - value for the field p

i - value for the field i

arena - to control the memory allocation scope

Cond

public Cond(MemorySegment p,
 int[] i)

Allocate a new Cond with the fields set to the provided values. The memory is allocated with Arena.ofAuto().

Parameters:

p - value for the field p

i - value for the field i

Method Details

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

readP

public MemorySegment readP()

Read the value of the field p.

Returns:

The value of the field p

writeP

public void writeP(MemorySegment p)

Write a value in the field p.

Parameters:

p - The new value for the field p

readI

public int[] readI()

Read the value of the field i.

Returns:

The value of the field i

writeI

public void writeI(int[] i,
 Arena _arena)

Write a value in the field i.

Parameters:

i - The new value for the field i

_arena - to control the memory allocation scope

new_

@Deprecated
public static Cond new_()

Deprecated.

GCond can now be statically allocated, or embedded in structures and initialised with g_cond_init().

Allocates and initializes a new GCond.

Returns:

a newly allocated GCond. Free with g_cond_free()

broadcast

public void broadcast()

If threads are waiting for this Cond, all of them are unblocked. If no threads are waiting for this Cond, this function has no effect. It is good practice to lock the same mutex as the waiting threads while calling this function, though not required.

clear

public void clear()

Frees the resources allocated to a GCond with g_cond_init().

This function should not be used with a GCond that has been statically allocated.

Calling g_cond_clear() for a GCond on which threads are blocking leads to undefined behaviour.

free

@Deprecated
public void free()

Deprecated.

GCond can now be statically allocated, or embedded in structures and initialised with g_cond_init().

Destroys a GCond that has been created with g_cond_new().

Calling g_cond_free() for a GCond on which threads are blocking leads to undefined behaviour.

init

public void init()

Initialises a GCond so that it can be used.

This function is useful to initialise a GCond that has been allocated as part of a larger structure. It is not necessary to initialise a GCond that has been statically allocated.

To undo the effect of g_cond_init() when a GCond is no longer needed, use g_cond_clear().

Calling g_cond_init() on an already-initialised GCond leads to undefined behaviour.

signal

public void signal()

If threads are waiting for this Cond, at least one of them is unblocked. If no threads are waiting for this Cond, this function has no effect. It is good practice to hold the same lock as the waiting thread while calling this function, though not required.

timedWait

@Deprecated
public boolean timedWait(Mutex mutex,
 TimeVal absTime)

Deprecated.

Use g_cond_wait_until() instead.

Waits until this thread is woken up on this Cond, but not longer than until the time specified by absTime. The mutex is unlocked before falling asleep and locked again before resuming.

If absTime is null, g_cond_timed_wait() acts like g_cond_wait().

This function can be used even if g_thread_init() has not yet been called, and, in that case, will immediately return true.

To easily calculate absTime a combination of g_get_real_time() and g_time_val_add() can be used.

Parameters:

mutex - a GMutex that is currently locked

absTime - a GTimeVal, determining the final time

Returns:

true if this Cond was signalled, or false on timeout

wait_

public void wait_(Mutex mutex)

Atomically releases mutex and waits until this Cond is signalled. When this function returns, mutex is locked again and owned by the calling thread.

When using condition variables, it is possible that a spurious wakeup may occur (ie: g_cond_wait() returns even though g_cond_signal() was not called). It's also possible that a stolen wakeup may occur. This is when g_cond_signal() is called, but another thread acquires mutex before this thread and modifies the state of the program in such a way that when g_cond_wait() is able to return, the expected condition is no longer met.

For this reason, g_cond_wait() must always be used in a loop. See the documentation for GCond for a complete example.

Parameters:

mutex - a GMutex that is currently locked

waitUntil

public boolean waitUntil(Mutex mutex,
 long endTime)

Waits until either this Cond is signalled or endTime has passed.

As with g_cond_wait() it is possible that a spurious or stolen wakeup could occur. For that reason, waiting on a condition variable should always be in a loop, based on an explicitly-checked predicate.

true is returned if the condition variable was signalled (or in the case of a spurious wakeup). false is returned if endTime has passed.

The following code shows how to correctly perform a timed wait on a condition variable (extending the example presented in the documentation for GCond):

gpointer
 pop_data_timed (void)
 {
   gint64 end_time;
   gpointer data;

   g_mutex_lock (&data_mutex);

   end_time = g_get_monotonic_time () + 5 * G_TIME_SPAN_SECOND;
   while (!current_data)
     if (!g_cond_wait_until (&data_cond, &data_mutex, end_time))
       {
         // timeout has passed.
         g_mutex_unlock (&data_mutex);
         return NULL;
       }

   // there is data for us
   data = current_data;
   current_data = NULL;

   g_mutex_unlock (&data_mutex);

   return data;
 }
 

Notice that the end time is calculated once, before entering the loop and reused. This is the motivation behind the use of absolute time on this API -- if a relative time of 5 seconds were passed directly to the call and a spurious wakeup occurred, the program would have to start over waiting again (which would lead to a total wait time of more than 5 seconds).

Parameters:

mutex - a GMutex that is currently locked

endTime - the monotonic time to wait until

Returns:

true on a signal, false on a timeout