Method

GLibCondwait_until

since: 2.32

Declaration

gboolean
g_cond_wait_until (
  GCond* cond,
  GMutex* mutex,
  gint64 end_time
)

Description

Waits until either cond is signalled or end_time 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 end_time 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).

Available since: 2.32

Parameters

mutex

Type: GMutex

A GMutex that is currently locked.

The data is owned by the caller of the function.
end_time

Type: gint64

The monotonic time to wait until.

Return value

Type: gboolean

TRUE on a signal, FALSE on a timeout.