* g_main_context_wakeup:
* @context: a #GMainContext
*
- * If @context is currently waiting in a poll(), interrupt
- * the poll(), and continue the iteration process.
+ * If @context is currently blocking in g_main_context_iteration()
+ * waiting for a source to become ready, cause it to stop blocking
+ * and return. Otherwise, cause the next invocation of
+ * g_main_context_iteration() to return without blocking.
+ *
+ * This API is useful for low-level control over #GMainContext; for
+ * example, integrating it with main loop implementations such as
+ * #GMainLoop.
+ *
+ * Another related use for this function is when implementing a main
+ * loop with a termination condition, computed from multiple threads:
+ *
+ * |[
+ * #define NUM_TASKS 10
+ * static volatile gint tasks_remaining = NUM_TASKS;
+ * ...
+ *
+ * while (g_atomic_int_get (&tasks_remaining) != 0)
+ * g_main_context_iteration (NULL, TRUE);
+ * ]|
+ *
+ * Then in a thread:
+ * |[
+ * perform_work();
+ *
+ * if (g_atomic_int_dec_and_test (&tasks_remaining))
+ * g_main_context_wakeup (NULL);
+ * ]|
**/
void
g_main_context_wakeup (GMainContext *context)