Function

Clutterthreads_add_idle_full

Declaration [src]

guint
clutter_threads_add_idle_full (
  gint priority,
  GSourceFunc func,
  gpointer data,
  GDestroyNotify notify
)

Description [src]

Adds a function to be called whenever there are no higher priority events pending. If the function returns FALSE it is automatically removed from the list of event sources and will not be called again.

This function can be considered a thread-safe variant of g_idle_add_full(): it will call function while holding the Clutter lock. It is logically equivalent to the following implementation:

static gboolean
idle_safe_callback (gpointer data)
{
   SafeClosure *closure = data;
   gboolean res = FALSE;

   // the callback does not need to acquire the Clutter
    / lock itself, as it is held by the this proxy handler
    //
   res = closure->callback (closure->data);

   return res;
}
static gulong
add_safe_idle (GSourceFunc callback,
               gpointer    data)
{
  SafeClosure *closure = g_new0 (SafeClosure, 1);

  closure->callback = callback;
  closure->data = data;

  return g_idle_add_full (G_PRIORITY_DEFAULT_IDLE,
                          idle_safe_callback,
                          closure,
                          g_free)
}

This function should be used by threaded applications to make sure that func is emitted under the Clutter threads lock and invoked from the same thread that started the Clutter main loop. For instance, it can be used to update the UI using the results from a worker thread:

static gboolean
update_ui (gpointer data)
{
  SomeClosure *closure = data;

  // it is safe to call Clutter API from this function because
   / it is invoked from the same thread that started the main
   / loop and under the Clutter thread lock
   //
  clutter_label_set_text (CLUTTER_LABEL (closure->label),
                          closure->text);

  g_object_unref (closure->label);
  g_free (closure);

  return FALSE;
}

  // within another thread //
  closure = g_new0 (SomeClosure, 1);
  // always take a reference on GObject instances //
  closure->label = g_object_ref (my_application->label);
  closure->text = g_strdup (processed_text_to_update_the_label);

  clutter_threads_add_idle_full (G_PRIORITY_HIGH_IDLE,
                                 update_ui,
                                 closure,
                                 NULL);

This function is renamed to clutter_threads_add_idle() in language bindings.

Parameters

priority

Type: gint

The priority of the timeout source. Typically this will be in the range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.

func

Type: GSourceFunc

Function to call.

data

Type: gpointer

Data to pass to the function.

The argument can be NULL.

The data is owned by the caller of the function.

notify

Type: GDestroyNotify

Function to call when the idle source is removed.

Return value

Type: guint

The ID (greater than 0) of the event source.