Use G_SOURCE_CONTINUE/REMOVE internally
[platform/upstream/glib.git] / glib / gmain.c
1 /* GLIB - Library of useful routines for C programming
2  * Copyright (C) 1995-1997  Peter Mattis, Spencer Kimball and Josh MacDonald
3  *
4  * gmain.c: Main loop abstraction, timeouts, and idle functions
5  * Copyright 1998 Owen Taylor
6  *
7  * This library is free software; you can redistribute it and/or
8  * modify it under the terms of the GNU Lesser General Public
9  * License as published by the Free Software Foundation; either
10  * version 2 of the License, or (at your option) any later version.
11  *
12  * This library is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this library; if not, write to the
19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
20  * Boston, MA 02111-1307, USA.
21  */
22
23 /*
24  * Modified by the GLib Team and others 1997-2000.  See the AUTHORS
25  * file for a list of people on the GLib Team.  See the ChangeLog
26  * files for a list of changes.  These files are distributed with
27  * GLib at ftp://ftp.gtk.org/pub/gtk/.
28  */
29
30 /*
31  * MT safe
32  */
33
34 #include "config.h"
35 #include "glibconfig.h"
36
37 /* Uncomment the next line (and the corresponding line in gpoll.c) to
38  * enable debugging printouts if the environment variable
39  * G_MAIN_POLL_DEBUG is set to some value.
40  */
41 /* #define G_MAIN_POLL_DEBUG */
42
43 #ifdef _WIN32
44 /* Always enable debugging printout on Windows, as it is more often
45  * needed there...
46  */
47 #define G_MAIN_POLL_DEBUG
48 #endif
49
50 #ifdef G_OS_UNIX
51 #include "glib-unix.h"
52 #include <pthread.h>
53 #ifdef HAVE_EVENTFD
54 #include <sys/eventfd.h>
55 #endif
56 #endif
57
58 #include <signal.h>
59 #include <sys/types.h>
60 #include <time.h>
61 #include <stdlib.h>
62 #ifdef HAVE_SYS_TIME_H
63 #include <sys/time.h>
64 #endif /* HAVE_SYS_TIME_H */
65 #ifdef HAVE_UNISTD_H
66 #include <unistd.h>
67 #endif /* HAVE_UNISTD_H */
68 #include <errno.h>
69 #include <string.h>
70
71 #ifdef G_OS_WIN32
72 #define STRICT
73 #include <windows.h>
74 #endif /* G_OS_WIN32 */
75
76 #ifdef G_OS_BEOS
77 #include <sys/socket.h>
78 #include <sys/wait.h>
79 #endif /* G_OS_BEOS */
80
81 #include "gmain.h"
82
83 #include "garray.h"
84 #include "giochannel.h"
85 #include "ghash.h"
86 #include "ghook.h"
87 #include "gqueue.h"
88 #include "gstrfuncs.h"
89 #include "gtestutils.h"
90
91 #ifdef G_OS_WIN32
92 #include "gwin32.h"
93 #endif
94
95 #ifdef  G_MAIN_POLL_DEBUG
96 #include "gtimer.h"
97 #endif
98
99 #include "gwakeup.h"
100 #include "gmain-internal.h"
101 #include "glib-private.h"
102
103 /**
104  * SECTION:main
105  * @title: The Main Event Loop
106  * @short_description: manages all available sources of events
107  *
108  * The main event loop manages all the available sources of events for
109  * GLib and GTK+ applications. These events can come from any number of
110  * different types of sources such as file descriptors (plain files,
111  * pipes or sockets) and timeouts. New types of event sources can also
112  * be added using g_source_attach().
113  *
114  * To allow multiple independent sets of sources to be handled in
115  * different threads, each source is associated with a #GMainContext.
116  * A GMainContext can only be running in a single thread, but
117  * sources can be added to it and removed from it from other threads.
118  *
119  * Each event source is assigned a priority. The default priority,
120  * #G_PRIORITY_DEFAULT, is 0. Values less than 0 denote higher priorities.
121  * Values greater than 0 denote lower priorities. Events from high priority
122  * sources are always processed before events from lower priority sources.
123  *
124  * Idle functions can also be added, and assigned a priority. These will
125  * be run whenever no events with a higher priority are ready to be processed.
126  *
127  * The #GMainLoop data type represents a main event loop. A GMainLoop is
128  * created with g_main_loop_new(). After adding the initial event sources,
129  * g_main_loop_run() is called. This continuously checks for new events from
130  * each of the event sources and dispatches them. Finally, the processing of
131  * an event from one of the sources leads to a call to g_main_loop_quit() to
132  * exit the main loop, and g_main_loop_run() returns.
133  *
134  * It is possible to create new instances of #GMainLoop recursively.
135  * This is often used in GTK+ applications when showing modal dialog
136  * boxes. Note that event sources are associated with a particular
137  * #GMainContext, and will be checked and dispatched for all main
138  * loops associated with that GMainContext.
139  *
140  * GTK+ contains wrappers of some of these functions, e.g. gtk_main(),
141  * gtk_main_quit() and gtk_events_pending().
142  *
143  * <refsect2><title>Creating new source types</title>
144  * <para>One of the unusual features of the #GMainLoop functionality
145  * is that new types of event source can be created and used in
146  * addition to the builtin type of event source. A new event source
147  * type is used for handling GDK events. A new source type is created
148  * by <firstterm>deriving</firstterm> from the #GSource structure.
149  * The derived type of source is represented by a structure that has
150  * the #GSource structure as a first element, and other elements specific
151  * to the new source type. To create an instance of the new source type,
152  * call g_source_new() passing in the size of the derived structure and
153  * a table of functions. These #GSourceFuncs determine the behavior of
154  * the new source type.</para>
155  * <para>New source types basically interact with the main context
156  * in two ways. Their prepare function in #GSourceFuncs can set a timeout
157  * to determine the maximum amount of time that the main loop will sleep
158  * before checking the source again. In addition, or as well, the source
159  * can add file descriptors to the set that the main context checks using
160  * g_source_add_poll().</para>
161  * </refsect2>
162  * <refsect2><title>Customizing the main loop iteration</title>
163  * <para>Single iterations of a #GMainContext can be run with
164  * g_main_context_iteration(). In some cases, more detailed control
165  * of exactly how the details of the main loop work is desired, for
166  * instance, when integrating the #GMainLoop with an external main loop.
167  * In such cases, you can call the component functions of
168  * g_main_context_iteration() directly. These functions are
169  * g_main_context_prepare(), g_main_context_query(),
170  * g_main_context_check() and g_main_context_dispatch().</para>
171  * <para>The operation of these functions can best be seen in terms
172  * of a state diagram, as shown in <xref linkend="mainloop-states"/>.</para>
173  * <figure id="mainloop-states"><title>States of a Main Context</title>
174  * <graphic fileref="mainloop-states.gif" format="GIF"></graphic>
175  * </figure>
176  * </refsect2>
177  *
178  * On Unix, the GLib mainloop is incompatible with fork().  Any program
179  * using the mainloop must either exec() or exit() from the child
180  * without returning to the mainloop.
181  */
182
183 /* Types */
184
185 typedef struct _GTimeoutSource GTimeoutSource;
186 typedef struct _GChildWatchSource GChildWatchSource;
187 typedef struct _GUnixSignalWatchSource GUnixSignalWatchSource;
188 typedef struct _GPollRec GPollRec;
189 typedef struct _GSourceCallback GSourceCallback;
190
191 typedef enum
192 {
193   G_SOURCE_READY = 1 << G_HOOK_FLAG_USER_SHIFT,
194   G_SOURCE_CAN_RECURSE = 1 << (G_HOOK_FLAG_USER_SHIFT + 1)
195 } GSourceFlags;
196
197 typedef struct _GMainWaiter GMainWaiter;
198
199 struct _GMainWaiter
200 {
201   GCond *cond;
202   GMutex *mutex;
203 };
204
205 typedef struct _GMainDispatch GMainDispatch;
206
207 struct _GMainDispatch
208 {
209   gint depth;
210   GSList *dispatching_sources; /* stack of current sources */
211 };
212
213 #ifdef G_MAIN_POLL_DEBUG
214 gboolean _g_main_poll_debug = FALSE;
215 #endif
216
217 struct _GMainContext
218 {
219   /* The following lock is used for both the list of sources
220    * and the list of poll records
221    */
222   GMutex mutex;
223   GCond cond;
224   GThread *owner;
225   guint owner_count;
226   GSList *waiters;
227
228   gint ref_count;
229
230   GPtrArray *pending_dispatches;
231   gint timeout;                 /* Timeout for current iteration */
232
233   guint next_id;
234   GSource *source_list;
235   gint in_check_or_prepare;
236
237   GPollRec *poll_records, *poll_records_tail;
238   guint n_poll_records;
239   GPollFD *cached_poll_array;
240   guint cached_poll_array_size;
241
242   GWakeup *wakeup;
243
244   GPollFD wake_up_rec;
245
246 /* Flag indicating whether the set of fd's changed during a poll */
247   gboolean poll_changed;
248
249   GPollFunc poll_func;
250
251   gint64   time;
252   gboolean time_is_fresh;
253 };
254
255 struct _GSourceCallback
256 {
257   guint ref_count;
258   GSourceFunc func;
259   gpointer    data;
260   GDestroyNotify notify;
261 };
262
263 struct _GMainLoop
264 {
265   GMainContext *context;
266   gboolean is_running;
267   gint ref_count;
268 };
269
270 struct _GTimeoutSource
271 {
272   GSource     source;
273   gint64      expiration;
274   guint       interval;
275   gboolean    seconds;
276 };
277
278 struct _GChildWatchSource
279 {
280   GSource     source;
281   GPid        pid;
282   gint        child_status;
283 #ifdef G_OS_WIN32
284   GPollFD     poll;
285 #else /* G_OS_WIN32 */
286   gboolean    child_exited;
287 #endif /* G_OS_WIN32 */
288 };
289
290 struct _GUnixSignalWatchSource
291 {
292   GSource     source;
293   int         signum;
294   gboolean    pending;
295 };
296
297 struct _GPollRec
298 {
299   GPollFD *fd;
300   GPollRec *prev;
301   GPollRec *next;
302   gint priority;
303 };
304
305 struct _GSourcePrivate
306 {
307   GSList *child_sources;
308   GSource *parent_source;
309 };
310
311 #define LOCK_CONTEXT(context) g_mutex_lock (&context->mutex)
312 #define UNLOCK_CONTEXT(context) g_mutex_unlock (&context->mutex)
313 #define G_THREAD_SELF g_thread_self ()
314
315 #define SOURCE_DESTROYED(source) (((source)->flags & G_HOOK_FLAG_ACTIVE) == 0)
316 #define SOURCE_BLOCKED(source) (((source)->flags & G_HOOK_FLAG_IN_CALL) != 0 && \
317                                 ((source)->flags & G_SOURCE_CAN_RECURSE) == 0)
318
319 #define SOURCE_UNREF(source, context)                       \
320    G_STMT_START {                                           \
321     if ((source)->ref_count > 1)                            \
322       (source)->ref_count--;                                \
323     else                                                    \
324       g_source_unref_internal ((source), (context), TRUE);  \
325    } G_STMT_END
326
327
328 /* Forward declarations */
329
330 static void g_source_unref_internal             (GSource      *source,
331                                                  GMainContext *context,
332                                                  gboolean      have_lock);
333 static void g_source_destroy_internal           (GSource      *source,
334                                                  GMainContext *context,
335                                                  gboolean      have_lock);
336 static void g_source_set_priority_unlocked      (GSource      *source,
337                                                  GMainContext *context,
338                                                  gint          priority);
339 static void g_main_context_poll                 (GMainContext *context,
340                                                  gint          timeout,
341                                                  gint          priority,
342                                                  GPollFD      *fds,
343                                                  gint          n_fds);
344 static void g_main_context_add_poll_unlocked    (GMainContext *context,
345                                                  gint          priority,
346                                                  GPollFD      *fd);
347 static void g_main_context_remove_poll_unlocked (GMainContext *context,
348                                                  GPollFD      *fd);
349
350 static gboolean g_timeout_prepare  (GSource     *source,
351                                     gint        *timeout);
352 static gboolean g_timeout_check    (GSource     *source);
353 static gboolean g_timeout_dispatch (GSource     *source,
354                                     GSourceFunc  callback,
355                                     gpointer     user_data);
356 static gboolean g_child_watch_prepare  (GSource     *source,
357                                         gint        *timeout);
358 static gboolean g_child_watch_check    (GSource     *source);
359 static gboolean g_child_watch_dispatch (GSource     *source,
360                                         GSourceFunc  callback,
361                                         gpointer     user_data);
362 static void     g_child_watch_finalize (GSource     *source);
363 #ifdef G_OS_UNIX
364 static void g_unix_signal_handler (int signum);
365 static gboolean g_unix_signal_watch_prepare  (GSource     *source,
366                                               gint        *timeout);
367 static gboolean g_unix_signal_watch_check    (GSource     *source);
368 static gboolean g_unix_signal_watch_dispatch (GSource     *source,
369                                               GSourceFunc  callback,
370                                               gpointer     user_data);
371 static void     g_unix_signal_watch_finalize  (GSource     *source);
372 #endif
373 static gboolean g_idle_prepare     (GSource     *source,
374                                     gint        *timeout);
375 static gboolean g_idle_check       (GSource     *source);
376 static gboolean g_idle_dispatch    (GSource     *source,
377                                     GSourceFunc  callback,
378                                     gpointer     user_data);
379
380 static GMainContext *glib_worker_context;
381
382 G_LOCK_DEFINE_STATIC (main_loop);
383 static GMainContext *default_main_context;
384
385 #ifndef G_OS_WIN32
386
387
388 /* UNIX signals work by marking one of these variables then waking the
389  * worker context to check on them and dispatch accordingly.
390  */
391 static volatile gchar unix_signal_pending[NSIG];
392 static volatile gboolean any_unix_signal_pending;
393
394 /* Guards all the data below */
395 G_LOCK_DEFINE_STATIC (unix_signal_lock);
396 static GSList *unix_signal_watches;
397 static GSList *unix_child_watches;
398
399 static GSourceFuncs g_unix_signal_funcs =
400 {
401   g_unix_signal_watch_prepare,
402   g_unix_signal_watch_check,
403   g_unix_signal_watch_dispatch,
404   g_unix_signal_watch_finalize
405 };
406 #endif /* !G_OS_WIN32 */
407 G_LOCK_DEFINE_STATIC (main_context_list);
408 static GSList *main_context_list = NULL;
409
410 GSourceFuncs g_timeout_funcs =
411 {
412   g_timeout_prepare,
413   g_timeout_check,
414   g_timeout_dispatch,
415   NULL
416 };
417
418 GSourceFuncs g_child_watch_funcs =
419 {
420   g_child_watch_prepare,
421   g_child_watch_check,
422   g_child_watch_dispatch,
423   g_child_watch_finalize
424 };
425
426 GSourceFuncs g_idle_funcs =
427 {
428   g_idle_prepare,
429   g_idle_check,
430   g_idle_dispatch,
431   NULL
432 };
433
434 /**
435  * g_main_context_ref:
436  * @context: a #GMainContext
437  * 
438  * Increases the reference count on a #GMainContext object by one.
439  *
440  * Returns: the @context that was passed in (since 2.6)
441  **/
442 GMainContext *
443 g_main_context_ref (GMainContext *context)
444 {
445   g_return_val_if_fail (context != NULL, NULL);
446   g_return_val_if_fail (g_atomic_int_get (&context->ref_count) > 0, NULL); 
447
448   g_atomic_int_inc (&context->ref_count);
449
450   return context;
451 }
452
453 static inline void
454 poll_rec_list_free (GMainContext *context,
455                     GPollRec     *list)
456 {
457   g_slice_free_chain (GPollRec, list, next);
458 }
459
460 /**
461  * g_main_context_unref:
462  * @context: a #GMainContext
463  * 
464  * Decreases the reference count on a #GMainContext object by one. If
465  * the result is zero, free the context and free all associated memory.
466  **/
467 void
468 g_main_context_unref (GMainContext *context)
469 {
470   GSource *source;
471   g_return_if_fail (context != NULL);
472   g_return_if_fail (g_atomic_int_get (&context->ref_count) > 0); 
473
474   if (!g_atomic_int_dec_and_test (&context->ref_count))
475     return;
476
477   G_LOCK (main_context_list);
478   main_context_list = g_slist_remove (main_context_list, context);
479   G_UNLOCK (main_context_list);
480
481   source = context->source_list;
482   while (source)
483     {
484       GSource *next = source->next;
485       g_source_destroy_internal (source, context, FALSE);
486       source = next;
487     }
488
489   g_mutex_clear (&context->mutex);
490
491   g_ptr_array_free (context->pending_dispatches, TRUE);
492   g_free (context->cached_poll_array);
493
494   poll_rec_list_free (context, context->poll_records);
495
496   g_wakeup_free (context->wakeup);
497   g_cond_clear (&context->cond);
498
499   g_free (context);
500 }
501
502 /**
503  * g_main_context_new:
504  * 
505  * Creates a new #GMainContext structure.
506  * 
507  * Return value: the new #GMainContext
508  **/
509 GMainContext *
510 g_main_context_new (void)
511 {
512   static gsize initialised;
513   GMainContext *context;
514
515   if (g_once_init_enter (&initialised))
516     {
517 #ifdef G_MAIN_POLL_DEBUG
518       if (getenv ("G_MAIN_POLL_DEBUG") != NULL)
519         _g_main_poll_debug = TRUE;
520 #endif
521
522       g_once_init_leave (&initialised, TRUE);
523     }
524
525   context = g_new0 (GMainContext, 1);
526
527   g_mutex_init (&context->mutex);
528   g_cond_init (&context->cond);
529
530   context->owner = NULL;
531   context->waiters = NULL;
532
533   context->ref_count = 1;
534
535   context->next_id = 1;
536   
537   context->source_list = NULL;
538   
539   context->poll_func = g_poll;
540   
541   context->cached_poll_array = NULL;
542   context->cached_poll_array_size = 0;
543   
544   context->pending_dispatches = g_ptr_array_new ();
545   
546   context->time_is_fresh = FALSE;
547   
548   context->wakeup = g_wakeup_new ();
549   g_wakeup_get_pollfd (context->wakeup, &context->wake_up_rec);
550   g_main_context_add_poll_unlocked (context, 0, &context->wake_up_rec);
551
552   G_LOCK (main_context_list);
553   main_context_list = g_slist_append (main_context_list, context);
554
555 #ifdef G_MAIN_POLL_DEBUG
556   if (_g_main_poll_debug)
557     g_print ("created context=%p\n", context);
558 #endif
559
560   G_UNLOCK (main_context_list);
561
562   return context;
563 }
564
565 /**
566  * g_main_context_default:
567  * 
568  * Returns the global default main context. This is the main context
569  * used for main loop functions when a main loop is not explicitly
570  * specified, and corresponds to the "main" main loop. See also
571  * g_main_context_get_thread_default().
572  * 
573  * Return value: (transfer none): the global default main context.
574  **/
575 GMainContext *
576 g_main_context_default (void)
577 {
578   /* Slow, but safe */
579   
580   G_LOCK (main_loop);
581
582   if (!default_main_context)
583     {
584       default_main_context = g_main_context_new ();
585 #ifdef G_MAIN_POLL_DEBUG
586       if (_g_main_poll_debug)
587         g_print ("default context=%p\n", default_main_context);
588 #endif
589     }
590
591   G_UNLOCK (main_loop);
592
593   return default_main_context;
594 }
595
596 static void
597 free_context (gpointer data)
598 {
599   GMainContext *context = data;
600
601   g_main_context_release (context);
602   if (context)
603     g_main_context_unref (context);
604 }
605
606 static void
607 free_context_stack (gpointer data)
608 {
609   g_queue_free_full((GQueue *) data, (GDestroyNotify) free_context);
610 }
611
612 static GPrivate thread_context_stack = G_PRIVATE_INIT (free_context_stack);
613
614 /**
615  * g_main_context_push_thread_default:
616  * @context: a #GMainContext, or %NULL for the global default context
617  *
618  * Acquires @context and sets it as the thread-default context for the
619  * current thread. This will cause certain asynchronous operations
620  * (such as most <link linkend="gio">gio</link>-based I/O) which are
621  * started in this thread to run under @context and deliver their
622  * results to its main loop, rather than running under the global
623  * default context in the main thread. Note that calling this function
624  * changes the context returned by
625  * g_main_context_get_thread_default(), <emphasis>not</emphasis> the
626  * one returned by g_main_context_default(), so it does not affect the
627  * context used by functions like g_idle_add().
628  *
629  * Normally you would call this function shortly after creating a new
630  * thread, passing it a #GMainContext which will be run by a
631  * #GMainLoop in that thread, to set a new default context for all
632  * async operations in that thread. (In this case, you don't need to
633  * ever call g_main_context_pop_thread_default().) In some cases
634  * however, you may want to schedule a single operation in a
635  * non-default context, or temporarily use a non-default context in
636  * the main thread. In that case, you can wrap the call to the
637  * asynchronous operation inside a
638  * g_main_context_push_thread_default() /
639  * g_main_context_pop_thread_default() pair, but it is up to you to
640  * ensure that no other asynchronous operations accidentally get
641  * started while the non-default context is active.
642  *
643  * Beware that libraries that predate this function may not correctly
644  * handle being used from a thread with a thread-default context. Eg,
645  * see g_file_supports_thread_contexts().
646  *
647  * Since: 2.22
648  **/
649 void
650 g_main_context_push_thread_default (GMainContext *context)
651 {
652   GQueue *stack;
653   gboolean acquired_context;
654
655   acquired_context = g_main_context_acquire (context);
656   g_return_if_fail (acquired_context);
657
658   if (context == g_main_context_default ())
659     context = NULL;
660   else if (context)
661     g_main_context_ref (context);
662
663   stack = g_private_get (&thread_context_stack);
664   if (!stack)
665     {
666       stack = g_queue_new ();
667       g_private_set (&thread_context_stack, stack);
668     }
669
670   g_queue_push_head (stack, context);
671 }
672
673 /**
674  * g_main_context_pop_thread_default:
675  * @context: a #GMainContext object, or %NULL
676  *
677  * Pops @context off the thread-default context stack (verifying that
678  * it was on the top of the stack).
679  *
680  * Since: 2.22
681  **/
682 void
683 g_main_context_pop_thread_default (GMainContext *context)
684 {
685   GQueue *stack;
686
687   if (context == g_main_context_default ())
688     context = NULL;
689
690   stack = g_private_get (&thread_context_stack);
691
692   g_return_if_fail (stack != NULL);
693   g_return_if_fail (g_queue_peek_head (stack) == context);
694
695   g_queue_pop_head (stack);
696
697   g_main_context_release (context);
698   if (context)
699     g_main_context_unref (context);
700 }
701
702 /**
703  * g_main_context_get_thread_default:
704  *
705  * Gets the thread-default #GMainContext for this thread. Asynchronous
706  * operations that want to be able to be run in contexts other than
707  * the default one should call this method or
708  * g_main_context_ref_thread_default() to get a #GMainContext to add
709  * their #GSource<!-- -->s to. (Note that even in single-threaded
710  * programs applications may sometimes want to temporarily push a
711  * non-default context, so it is not safe to assume that this will
712  * always return %NULL if you are running in the default thread.)
713  *
714  * If you need to hold a reference on the context, use
715  * g_main_context_ref_thread_default() instead.
716  *
717  * Returns: (transfer none): the thread-default #GMainContext, or
718  * %NULL if the thread-default context is the global default context.
719  *
720  * Since: 2.22
721  **/
722 GMainContext *
723 g_main_context_get_thread_default (void)
724 {
725   GQueue *stack;
726
727   stack = g_private_get (&thread_context_stack);
728   if (stack)
729     return g_queue_peek_head (stack);
730   else
731     return NULL;
732 }
733
734 /**
735  * g_main_context_ref_thread_default:
736  *
737  * Gets the thread-default #GMainContext for this thread, as with
738  * g_main_context_get_thread_default(), but also adds a reference to
739  * it with g_main_context_ref(). In addition, unlike
740  * g_main_context_get_thread_default(), if the thread-default context
741  * is the global default context, this will return that #GMainContext
742  * (with a ref added to it) rather than returning %NULL.
743  *
744  * Returns: (transfer full): the thread-default #GMainContext. Unref
745  *     with g_main_context_unref() when you are done with it.
746  *
747  * Since: 2.32
748  */
749 GMainContext *
750 g_main_context_ref_thread_default (void)
751 {
752   GMainContext *context;
753
754   context = g_main_context_get_thread_default ();
755   if (!context)
756     context = g_main_context_default ();
757   return g_main_context_ref (context);
758 }
759
760 /* Hooks for adding to the main loop */
761
762 /**
763  * g_source_new:
764  * @source_funcs: structure containing functions that implement
765  *                the sources behavior.
766  * @struct_size: size of the #GSource structure to create.
767  * 
768  * Creates a new #GSource structure. The size is specified to
769  * allow creating structures derived from #GSource that contain
770  * additional data. The size passed in must be at least
771  * <literal>sizeof (GSource)</literal>.
772  * 
773  * The source will not initially be associated with any #GMainContext
774  * and must be added to one with g_source_attach() before it will be
775  * executed.
776  * 
777  * Return value: the newly-created #GSource.
778  **/
779 GSource *
780 g_source_new (GSourceFuncs *source_funcs,
781               guint         struct_size)
782 {
783   GSource *source;
784
785   g_return_val_if_fail (source_funcs != NULL, NULL);
786   g_return_val_if_fail (struct_size >= sizeof (GSource), NULL);
787   
788   source = (GSource*) g_malloc0 (struct_size);
789
790   source->source_funcs = source_funcs;
791   source->ref_count = 1;
792   
793   source->priority = G_PRIORITY_DEFAULT;
794
795   source->flags = G_HOOK_FLAG_ACTIVE;
796
797   /* NULL/0 initialization for all other fields */
798   
799   return source;
800 }
801
802 /* Holds context's lock
803  */
804 static void
805 g_source_list_add (GSource      *source,
806                    GMainContext *context)
807 {
808   GSource *tmp_source, *last_source;
809   
810   if (source->priv && source->priv->parent_source)
811     {
812       /* Put the source immediately before its parent */
813       tmp_source = source->priv->parent_source;
814       last_source = source->priv->parent_source->prev;
815     }
816   else
817     {
818       last_source = NULL;
819       tmp_source = context->source_list;
820       while (tmp_source && tmp_source->priority <= source->priority)
821         {
822           last_source = tmp_source;
823           tmp_source = tmp_source->next;
824         }
825     }
826
827   source->next = tmp_source;
828   if (tmp_source)
829     tmp_source->prev = source;
830   
831   source->prev = last_source;
832   if (last_source)
833     last_source->next = source;
834   else
835     context->source_list = source;
836 }
837
838 /* Holds context's lock
839  */
840 static void
841 g_source_list_remove (GSource      *source,
842                       GMainContext *context)
843 {
844   if (source->prev)
845     source->prev->next = source->next;
846   else
847     context->source_list = source->next;
848
849   if (source->next)
850     source->next->prev = source->prev;
851
852   source->prev = NULL;
853   source->next = NULL;
854 }
855
856 static guint
857 g_source_attach_unlocked (GSource      *source,
858                           GMainContext *context)
859 {
860   guint result = 0;
861   GSList *tmp_list;
862
863   source->context = context;
864   result = source->source_id = context->next_id++;
865
866   source->ref_count++;
867   g_source_list_add (source, context);
868
869   tmp_list = source->poll_fds;
870   while (tmp_list)
871     {
872       g_main_context_add_poll_unlocked (context, source->priority, tmp_list->data);
873       tmp_list = tmp_list->next;
874     }
875
876   if (source->priv)
877     {
878       tmp_list = source->priv->child_sources;
879       while (tmp_list)
880         {
881           g_source_attach_unlocked (tmp_list->data, context);
882           tmp_list = tmp_list->next;
883         }
884     }
885
886   return result;
887 }
888
889 /**
890  * g_source_attach:
891  * @source: a #GSource
892  * @context: (allow-none): a #GMainContext (if %NULL, the default context will be used)
893  * 
894  * Adds a #GSource to a @context so that it will be executed within
895  * that context. Remove it by calling g_source_destroy().
896  *
897  * Return value: the ID (greater than 0) for the source within the 
898  *   #GMainContext. 
899  **/
900 guint
901 g_source_attach (GSource      *source,
902                  GMainContext *context)
903 {
904   guint result = 0;
905
906   g_return_val_if_fail (source->context == NULL, 0);
907   g_return_val_if_fail (!SOURCE_DESTROYED (source), 0);
908   
909   if (!context)
910     context = g_main_context_default ();
911
912   LOCK_CONTEXT (context);
913
914   result = g_source_attach_unlocked (source, context);
915
916   /* If another thread has acquired the context, wake it up since it
917    * might be in poll() right now.
918    */
919   if (context->owner && context->owner != G_THREAD_SELF)
920     g_wakeup_signal (context->wakeup);
921
922   UNLOCK_CONTEXT (context);
923
924   return result;
925 }
926
927 static void
928 g_source_destroy_internal (GSource      *source,
929                            GMainContext *context,
930                            gboolean      have_lock)
931 {
932   if (!have_lock)
933     LOCK_CONTEXT (context);
934   
935   if (!SOURCE_DESTROYED (source))
936     {
937       GSList *tmp_list;
938       gpointer old_cb_data;
939       GSourceCallbackFuncs *old_cb_funcs;
940       
941       source->flags &= ~G_HOOK_FLAG_ACTIVE;
942
943       old_cb_data = source->callback_data;
944       old_cb_funcs = source->callback_funcs;
945
946       source->callback_data = NULL;
947       source->callback_funcs = NULL;
948
949       if (old_cb_funcs)
950         {
951           UNLOCK_CONTEXT (context);
952           old_cb_funcs->unref (old_cb_data);
953           LOCK_CONTEXT (context);
954         }
955
956       if (!SOURCE_BLOCKED (source))
957         {
958           tmp_list = source->poll_fds;
959           while (tmp_list)
960             {
961               g_main_context_remove_poll_unlocked (context, tmp_list->data);
962               tmp_list = tmp_list->next;
963             }
964         }
965
966       if (source->priv && source->priv->child_sources)
967         {
968           /* This is safe because even if a child_source finalizer or
969            * closure notify tried to modify source->priv->child_sources
970            * from outside the lock, it would fail since
971            * SOURCE_DESTROYED(source) is now TRUE.
972            */
973           tmp_list = source->priv->child_sources;
974           while (tmp_list)
975             {
976               g_source_destroy_internal (tmp_list->data, context, TRUE);
977               g_source_unref_internal (tmp_list->data, context, TRUE);
978               tmp_list = tmp_list->next;
979             }
980           g_slist_free (source->priv->child_sources);
981           source->priv->child_sources = NULL;
982         }
983           
984       g_source_unref_internal (source, context, TRUE);
985     }
986
987   if (!have_lock)
988     UNLOCK_CONTEXT (context);
989 }
990
991 /**
992  * g_source_destroy:
993  * @source: a #GSource
994  * 
995  * Removes a source from its #GMainContext, if any, and mark it as
996  * destroyed.  The source cannot be subsequently added to another
997  * context.
998  **/
999 void
1000 g_source_destroy (GSource *source)
1001 {
1002   GMainContext *context;
1003   
1004   g_return_if_fail (source != NULL);
1005   
1006   context = source->context;
1007   
1008   if (context)
1009     g_source_destroy_internal (source, context, FALSE);
1010   else
1011     source->flags &= ~G_HOOK_FLAG_ACTIVE;
1012 }
1013
1014 /**
1015  * g_source_get_id:
1016  * @source: a #GSource
1017  * 
1018  * Returns the numeric ID for a particular source. The ID of a source
1019  * is a positive integer which is unique within a particular main loop 
1020  * context. The reverse
1021  * mapping from ID to source is done by g_main_context_find_source_by_id().
1022  *
1023  * Return value: the ID (greater than 0) for the source
1024  **/
1025 guint
1026 g_source_get_id (GSource *source)
1027 {
1028   guint result;
1029   
1030   g_return_val_if_fail (source != NULL, 0);
1031   g_return_val_if_fail (source->context != NULL, 0);
1032
1033   LOCK_CONTEXT (source->context);
1034   result = source->source_id;
1035   UNLOCK_CONTEXT (source->context);
1036   
1037   return result;
1038 }
1039
1040 /**
1041  * g_source_get_context:
1042  * @source: a #GSource
1043  * 
1044  * Gets the #GMainContext with which the source is associated.
1045  * Calling this function on a destroyed source is an error.
1046  * 
1047  * Return value: (transfer none): the #GMainContext with which the
1048  *               source is associated, or %NULL if the context has not
1049  *               yet been added to a source.
1050  **/
1051 GMainContext *
1052 g_source_get_context (GSource *source)
1053 {
1054   g_return_val_if_fail (!SOURCE_DESTROYED (source), NULL);
1055
1056   return source->context;
1057 }
1058
1059 /**
1060  * g_source_add_poll:
1061  * @source:a #GSource 
1062  * @fd: a #GPollFD structure holding information about a file
1063  *      descriptor to watch.
1064  * 
1065  * Adds a file descriptor to the set of file descriptors polled for
1066  * this source. This is usually combined with g_source_new() to add an
1067  * event source. The event source's check function will typically test
1068  * the @revents field in the #GPollFD struct and return %TRUE if events need
1069  * to be processed.
1070  **/
1071 void
1072 g_source_add_poll (GSource *source,
1073                    GPollFD *fd)
1074 {
1075   GMainContext *context;
1076   
1077   g_return_if_fail (source != NULL);
1078   g_return_if_fail (fd != NULL);
1079   g_return_if_fail (!SOURCE_DESTROYED (source));
1080   
1081   context = source->context;
1082
1083   if (context)
1084     LOCK_CONTEXT (context);
1085   
1086   source->poll_fds = g_slist_prepend (source->poll_fds, fd);
1087
1088   if (context)
1089     {
1090       if (!SOURCE_BLOCKED (source))
1091         g_main_context_add_poll_unlocked (context, source->priority, fd);
1092       UNLOCK_CONTEXT (context);
1093     }
1094 }
1095
1096 /**
1097  * g_source_remove_poll:
1098  * @source:a #GSource 
1099  * @fd: a #GPollFD structure previously passed to g_source_add_poll().
1100  * 
1101  * Removes a file descriptor from the set of file descriptors polled for
1102  * this source. 
1103  **/
1104 void
1105 g_source_remove_poll (GSource *source,
1106                       GPollFD *fd)
1107 {
1108   GMainContext *context;
1109   
1110   g_return_if_fail (source != NULL);
1111   g_return_if_fail (fd != NULL);
1112   g_return_if_fail (!SOURCE_DESTROYED (source));
1113   
1114   context = source->context;
1115
1116   if (context)
1117     LOCK_CONTEXT (context);
1118   
1119   source->poll_fds = g_slist_remove (source->poll_fds, fd);
1120
1121   if (context)
1122     {
1123       if (!SOURCE_BLOCKED (source))
1124         g_main_context_remove_poll_unlocked (context, fd);
1125       UNLOCK_CONTEXT (context);
1126     }
1127 }
1128
1129 /**
1130  * g_source_add_child_source:
1131  * @source:a #GSource
1132  * @child_source: a second #GSource that @source should "poll"
1133  *
1134  * Adds @child_source to @source as a "polled" source; when @source is
1135  * added to a #GMainContext, @child_source will be automatically added
1136  * with the same priority, when @child_source is triggered, it will
1137  * cause @source to dispatch (in addition to calling its own
1138  * callback), and when @source is destroyed, it will destroy
1139  * @child_source as well. (@source will also still be dispatched if
1140  * its own prepare/check functions indicate that it is ready.)
1141  *
1142  * If you don't need @child_source to do anything on its own when it
1143  * triggers, you can call g_source_set_dummy_callback() on it to set a
1144  * callback that does nothing (except return %TRUE if appropriate).
1145  *
1146  * @source will hold a reference on @child_source while @child_source
1147  * is attached to it.
1148  *
1149  * Since: 2.28
1150  **/
1151 void
1152 g_source_add_child_source (GSource *source,
1153                            GSource *child_source)
1154 {
1155   GMainContext *context;
1156
1157   g_return_if_fail (source != NULL);
1158   g_return_if_fail (child_source != NULL);
1159   g_return_if_fail (!SOURCE_DESTROYED (source));
1160   g_return_if_fail (!SOURCE_DESTROYED (child_source));
1161   g_return_if_fail (child_source->context == NULL);
1162   g_return_if_fail (child_source->priv == NULL || child_source->priv->parent_source == NULL);
1163
1164   context = source->context;
1165
1166   if (context)
1167     LOCK_CONTEXT (context);
1168
1169   if (!source->priv)
1170     source->priv = g_slice_new0 (GSourcePrivate);
1171   if (!child_source->priv)
1172     child_source->priv = g_slice_new0 (GSourcePrivate);
1173
1174   source->priv->child_sources = g_slist_prepend (source->priv->child_sources,
1175                                                  g_source_ref (child_source));
1176   child_source->priv->parent_source = source;
1177   g_source_set_priority_unlocked (child_source, NULL, source->priority);
1178
1179   if (context)
1180     {
1181       UNLOCK_CONTEXT (context);
1182       g_source_attach (child_source, context);
1183     }
1184 }
1185
1186 /**
1187  * g_source_remove_child_source:
1188  * @source:a #GSource
1189  * @child_source: a #GSource previously passed to
1190  *     g_source_add_child_source().
1191  *
1192  * Detaches @child_source from @source and destroys it.
1193  *
1194  * Since: 2.28
1195  **/
1196 void
1197 g_source_remove_child_source (GSource *source,
1198                               GSource *child_source)
1199 {
1200   GMainContext *context;
1201
1202   g_return_if_fail (source != NULL);
1203   g_return_if_fail (child_source != NULL);
1204   g_return_if_fail (child_source->priv != NULL && child_source->priv->parent_source == source);
1205   g_return_if_fail (!SOURCE_DESTROYED (source));
1206   g_return_if_fail (!SOURCE_DESTROYED (child_source));
1207
1208   context = source->context;
1209
1210   if (context)
1211     LOCK_CONTEXT (context);
1212
1213   source->priv->child_sources = g_slist_remove (source->priv->child_sources, child_source);
1214   g_source_destroy_internal (child_source, context, TRUE);
1215   g_source_unref_internal (child_source, context, TRUE);
1216
1217   if (context)
1218     UNLOCK_CONTEXT (context);
1219 }
1220
1221 /**
1222  * g_source_set_callback_indirect:
1223  * @source: the source
1224  * @callback_data: pointer to callback data "object"
1225  * @callback_funcs: functions for reference counting @callback_data
1226  *                  and getting the callback and data
1227  * 
1228  * Sets the callback function storing the data as a refcounted callback
1229  * "object". This is used internally. Note that calling 
1230  * g_source_set_callback_indirect() assumes
1231  * an initial reference count on @callback_data, and thus
1232  * @callback_funcs->unref will eventually be called once more
1233  * than @callback_funcs->ref.
1234  **/
1235 void
1236 g_source_set_callback_indirect (GSource              *source,
1237                                 gpointer              callback_data,
1238                                 GSourceCallbackFuncs *callback_funcs)
1239 {
1240   GMainContext *context;
1241   gpointer old_cb_data;
1242   GSourceCallbackFuncs *old_cb_funcs;
1243   
1244   g_return_if_fail (source != NULL);
1245   g_return_if_fail (callback_funcs != NULL || callback_data == NULL);
1246
1247   context = source->context;
1248
1249   if (context)
1250     LOCK_CONTEXT (context);
1251
1252   old_cb_data = source->callback_data;
1253   old_cb_funcs = source->callback_funcs;
1254
1255   source->callback_data = callback_data;
1256   source->callback_funcs = callback_funcs;
1257   
1258   if (context)
1259     UNLOCK_CONTEXT (context);
1260   
1261   if (old_cb_funcs)
1262     old_cb_funcs->unref (old_cb_data);
1263 }
1264
1265 static void
1266 g_source_callback_ref (gpointer cb_data)
1267 {
1268   GSourceCallback *callback = cb_data;
1269
1270   callback->ref_count++;
1271 }
1272
1273
1274 static void
1275 g_source_callback_unref (gpointer cb_data)
1276 {
1277   GSourceCallback *callback = cb_data;
1278
1279   callback->ref_count--;
1280   if (callback->ref_count == 0)
1281     {
1282       if (callback->notify)
1283         callback->notify (callback->data);
1284       g_free (callback);
1285     }
1286 }
1287
1288 static void
1289 g_source_callback_get (gpointer     cb_data,
1290                        GSource     *source, 
1291                        GSourceFunc *func,
1292                        gpointer    *data)
1293 {
1294   GSourceCallback *callback = cb_data;
1295
1296   *func = callback->func;
1297   *data = callback->data;
1298 }
1299
1300 static GSourceCallbackFuncs g_source_callback_funcs = {
1301   g_source_callback_ref,
1302   g_source_callback_unref,
1303   g_source_callback_get,
1304 };
1305
1306 /**
1307  * g_source_set_callback:
1308  * @source: the source
1309  * @func: a callback function
1310  * @data: the data to pass to callback function
1311  * @notify: a function to call when @data is no longer in use, or %NULL.
1312  * 
1313  * Sets the callback function for a source. The callback for a source is
1314  * called from the source's dispatch function.
1315  *
1316  * The exact type of @func depends on the type of source; ie. you
1317  * should not count on @func being called with @data as its first
1318  * parameter.
1319  * 
1320  * Typically, you won't use this function. Instead use functions specific
1321  * to the type of source you are using.
1322  **/
1323 void
1324 g_source_set_callback (GSource        *source,
1325                        GSourceFunc     func,
1326                        gpointer        data,
1327                        GDestroyNotify  notify)
1328 {
1329   GSourceCallback *new_callback;
1330
1331   g_return_if_fail (source != NULL);
1332
1333   new_callback = g_new (GSourceCallback, 1);
1334
1335   new_callback->ref_count = 1;
1336   new_callback->func = func;
1337   new_callback->data = data;
1338   new_callback->notify = notify;
1339
1340   g_source_set_callback_indirect (source, new_callback, &g_source_callback_funcs);
1341 }
1342
1343
1344 /**
1345  * g_source_set_funcs:
1346  * @source: a #GSource
1347  * @funcs: the new #GSourceFuncs
1348  * 
1349  * Sets the source functions (can be used to override 
1350  * default implementations) of an unattached source.
1351  * 
1352  * Since: 2.12
1353  */
1354 void
1355 g_source_set_funcs (GSource     *source,
1356                    GSourceFuncs *funcs)
1357 {
1358   g_return_if_fail (source != NULL);
1359   g_return_if_fail (source->context == NULL);
1360   g_return_if_fail (source->ref_count > 0);
1361   g_return_if_fail (funcs != NULL);
1362
1363   source->source_funcs = funcs;
1364 }
1365
1366 static void
1367 g_source_set_priority_unlocked (GSource      *source,
1368                                 GMainContext *context,
1369                                 gint          priority)
1370 {
1371   GSList *tmp_list;
1372   
1373   source->priority = priority;
1374
1375   if (context)
1376     {
1377       /* Remove the source from the context's source and then
1378        * add it back so it is sorted in the correct place
1379        */
1380       g_source_list_remove (source, source->context);
1381       g_source_list_add (source, source->context);
1382
1383       if (!SOURCE_BLOCKED (source))
1384         {
1385           tmp_list = source->poll_fds;
1386           while (tmp_list)
1387             {
1388               g_main_context_remove_poll_unlocked (context, tmp_list->data);
1389               g_main_context_add_poll_unlocked (context, priority, tmp_list->data);
1390               
1391               tmp_list = tmp_list->next;
1392             }
1393         }
1394     }
1395
1396   if (source->priv && source->priv->child_sources)
1397     {
1398       tmp_list = source->priv->child_sources;
1399       while (tmp_list)
1400         {
1401           g_source_set_priority_unlocked (tmp_list->data, context, priority);
1402           tmp_list = tmp_list->next;
1403         }
1404     }
1405 }
1406
1407 /**
1408  * g_source_set_priority:
1409  * @source: a #GSource
1410  * @priority: the new priority.
1411  *
1412  * Sets the priority of a source. While the main loop is being run, a
1413  * source will be dispatched if it is ready to be dispatched and no
1414  * sources at a higher (numerically smaller) priority are ready to be
1415  * dispatched.
1416  **/
1417 void
1418 g_source_set_priority (GSource  *source,
1419                        gint      priority)
1420 {
1421   GMainContext *context;
1422
1423   g_return_if_fail (source != NULL);
1424
1425   context = source->context;
1426
1427   if (context)
1428     LOCK_CONTEXT (context);
1429   g_source_set_priority_unlocked (source, context, priority);
1430   if (context)
1431     UNLOCK_CONTEXT (source->context);
1432 }
1433
1434 /**
1435  * g_source_get_priority:
1436  * @source: a #GSource
1437  * 
1438  * Gets the priority of a source.
1439  * 
1440  * Return value: the priority of the source
1441  **/
1442 gint
1443 g_source_get_priority (GSource *source)
1444 {
1445   g_return_val_if_fail (source != NULL, 0);
1446
1447   return source->priority;
1448 }
1449
1450 /**
1451  * g_source_set_can_recurse:
1452  * @source: a #GSource
1453  * @can_recurse: whether recursion is allowed for this source
1454  * 
1455  * Sets whether a source can be called recursively. If @can_recurse is
1456  * %TRUE, then while the source is being dispatched then this source
1457  * will be processed normally. Otherwise, all processing of this
1458  * source is blocked until the dispatch function returns.
1459  **/
1460 void
1461 g_source_set_can_recurse (GSource  *source,
1462                           gboolean  can_recurse)
1463 {
1464   GMainContext *context;
1465   
1466   g_return_if_fail (source != NULL);
1467
1468   context = source->context;
1469
1470   if (context)
1471     LOCK_CONTEXT (context);
1472   
1473   if (can_recurse)
1474     source->flags |= G_SOURCE_CAN_RECURSE;
1475   else
1476     source->flags &= ~G_SOURCE_CAN_RECURSE;
1477
1478   if (context)
1479     UNLOCK_CONTEXT (context);
1480 }
1481
1482 /**
1483  * g_source_get_can_recurse:
1484  * @source: a #GSource
1485  * 
1486  * Checks whether a source is allowed to be called recursively.
1487  * see g_source_set_can_recurse().
1488  * 
1489  * Return value: whether recursion is allowed.
1490  **/
1491 gboolean
1492 g_source_get_can_recurse (GSource  *source)
1493 {
1494   g_return_val_if_fail (source != NULL, FALSE);
1495   
1496   return (source->flags & G_SOURCE_CAN_RECURSE) != 0;
1497 }
1498
1499
1500 /**
1501  * g_source_set_name:
1502  * @source: a #GSource
1503  * @name: debug name for the source
1504  *
1505  * Sets a name for the source, used in debugging and profiling.
1506  * The name defaults to #NULL.
1507  *
1508  * The source name should describe in a human-readable way
1509  * what the source does. For example, "X11 event queue"
1510  * or "GTK+ repaint idle handler" or whatever it is.
1511  *
1512  * It is permitted to call this function multiple times, but is not
1513  * recommended due to the potential performance impact.  For example,
1514  * one could change the name in the "check" function of a #GSourceFuncs 
1515  * to include details like the event type in the source name.
1516  *
1517  * Since: 2.26
1518  **/
1519 void
1520 g_source_set_name (GSource    *source,
1521                    const char *name)
1522 {
1523   g_return_if_fail (source != NULL);
1524
1525   /* setting back to NULL is allowed, just because it's
1526    * weird if get_name can return NULL but you can't
1527    * set that.
1528    */
1529
1530   g_free (source->name);
1531   source->name = g_strdup (name);
1532 }
1533
1534 /**
1535  * g_source_get_name:
1536  * @source: a #GSource
1537  *
1538  * Gets a name for the source, used in debugging and profiling.
1539  * The name may be #NULL if it has never been set with
1540  * g_source_set_name().
1541  *
1542  * Return value: the name of the source
1543  * Since: 2.26
1544  **/
1545 const char *
1546 g_source_get_name (GSource *source)
1547 {
1548   g_return_val_if_fail (source != NULL, NULL);
1549
1550   return source->name;
1551 }
1552
1553 /**
1554  * g_source_set_name_by_id:
1555  * @tag: a #GSource ID
1556  * @name: debug name for the source
1557  *
1558  * Sets the name of a source using its ID.
1559  *
1560  * This is a convenience utility to set source names from the return
1561  * value of g_idle_add(), g_timeout_add(), etc.
1562  *
1563  * Since: 2.26
1564  **/
1565 void
1566 g_source_set_name_by_id (guint           tag,
1567                          const char     *name)
1568 {
1569   GSource *source;
1570
1571   g_return_if_fail (tag > 0);
1572
1573   source = g_main_context_find_source_by_id (NULL, tag);
1574   if (source == NULL)
1575     return;
1576
1577   g_source_set_name (source, name);
1578 }
1579
1580
1581 /**
1582  * g_source_ref:
1583  * @source: a #GSource
1584  * 
1585  * Increases the reference count on a source by one.
1586  * 
1587  * Return value: @source
1588  **/
1589 GSource *
1590 g_source_ref (GSource *source)
1591 {
1592   GMainContext *context;
1593   
1594   g_return_val_if_fail (source != NULL, NULL);
1595
1596   context = source->context;
1597
1598   if (context)
1599     LOCK_CONTEXT (context);
1600
1601   source->ref_count++;
1602
1603   if (context)
1604     UNLOCK_CONTEXT (context);
1605
1606   return source;
1607 }
1608
1609 /* g_source_unref() but possible to call within context lock
1610  */
1611 static void
1612 g_source_unref_internal (GSource      *source,
1613                          GMainContext *context,
1614                          gboolean      have_lock)
1615 {
1616   gpointer old_cb_data = NULL;
1617   GSourceCallbackFuncs *old_cb_funcs = NULL;
1618
1619   g_return_if_fail (source != NULL);
1620   
1621   if (!have_lock && context)
1622     LOCK_CONTEXT (context);
1623
1624   source->ref_count--;
1625   if (source->ref_count == 0)
1626     {
1627       old_cb_data = source->callback_data;
1628       old_cb_funcs = source->callback_funcs;
1629
1630       source->callback_data = NULL;
1631       source->callback_funcs = NULL;
1632
1633       if (context)
1634         {
1635           if (!SOURCE_DESTROYED (source))
1636             g_warning (G_STRLOC ": ref_count == 0, but source was still attached to a context!");
1637           g_source_list_remove (source, context);
1638         }
1639
1640       if (source->source_funcs->finalize)
1641         {
1642           if (context)
1643             UNLOCK_CONTEXT (context);
1644           source->source_funcs->finalize (source);
1645           if (context)
1646             LOCK_CONTEXT (context);
1647         }
1648
1649       g_free (source->name);
1650       source->name = NULL;
1651
1652       g_slist_free (source->poll_fds);
1653       source->poll_fds = NULL;
1654
1655       if (source->priv)
1656         {
1657           g_slice_free (GSourcePrivate, source->priv);
1658           source->priv = NULL;
1659         }
1660
1661       g_free (source);
1662     }
1663   
1664   if (!have_lock && context)
1665     UNLOCK_CONTEXT (context);
1666
1667   if (old_cb_funcs)
1668     {
1669       if (have_lock)
1670         UNLOCK_CONTEXT (context);
1671       
1672       old_cb_funcs->unref (old_cb_data);
1673
1674       if (have_lock)
1675         LOCK_CONTEXT (context);
1676     }
1677 }
1678
1679 /**
1680  * g_source_unref:
1681  * @source: a #GSource
1682  * 
1683  * Decreases the reference count of a source by one. If the
1684  * resulting reference count is zero the source and associated
1685  * memory will be destroyed. 
1686  **/
1687 void
1688 g_source_unref (GSource *source)
1689 {
1690   g_return_if_fail (source != NULL);
1691
1692   g_source_unref_internal (source, source->context, FALSE);
1693 }
1694
1695 /**
1696  * g_main_context_find_source_by_id:
1697  * @context: a #GMainContext (if %NULL, the default context will be used)
1698  * @source_id: the source ID, as returned by g_source_get_id(). 
1699  * 
1700  * Finds a #GSource given a pair of context and ID.
1701  * 
1702  * Return value: (transfer none): the #GSource if found, otherwise, %NULL
1703  **/
1704 GSource *
1705 g_main_context_find_source_by_id (GMainContext *context,
1706                                   guint         source_id)
1707 {
1708   GSource *source;
1709   
1710   g_return_val_if_fail (source_id > 0, NULL);
1711
1712   if (context == NULL)
1713     context = g_main_context_default ();
1714   
1715   LOCK_CONTEXT (context);
1716   
1717   source = context->source_list;
1718   while (source)
1719     {
1720       if (!SOURCE_DESTROYED (source) &&
1721           source->source_id == source_id)
1722         break;
1723       source = source->next;
1724     }
1725
1726   UNLOCK_CONTEXT (context);
1727
1728   return source;
1729 }
1730
1731 /**
1732  * g_main_context_find_source_by_funcs_user_data:
1733  * @context: a #GMainContext (if %NULL, the default context will be used).
1734  * @funcs: the @source_funcs passed to g_source_new().
1735  * @user_data: the user data from the callback.
1736  * 
1737  * Finds a source with the given source functions and user data.  If
1738  * multiple sources exist with the same source function and user data,
1739  * the first one found will be returned.
1740  * 
1741  * Return value: (transfer none): the source, if one was found, otherwise %NULL
1742  **/
1743 GSource *
1744 g_main_context_find_source_by_funcs_user_data (GMainContext *context,
1745                                                GSourceFuncs *funcs,
1746                                                gpointer      user_data)
1747 {
1748   GSource *source;
1749   
1750   g_return_val_if_fail (funcs != NULL, NULL);
1751
1752   if (context == NULL)
1753     context = g_main_context_default ();
1754   
1755   LOCK_CONTEXT (context);
1756
1757   source = context->source_list;
1758   while (source)
1759     {
1760       if (!SOURCE_DESTROYED (source) &&
1761           source->source_funcs == funcs &&
1762           source->callback_funcs)
1763         {
1764           GSourceFunc callback;
1765           gpointer callback_data;
1766
1767           source->callback_funcs->get (source->callback_data, source, &callback, &callback_data);
1768           
1769           if (callback_data == user_data)
1770             break;
1771         }
1772       source = source->next;
1773     }
1774
1775   UNLOCK_CONTEXT (context);
1776
1777   return source;
1778 }
1779
1780 /**
1781  * g_main_context_find_source_by_user_data:
1782  * @context: a #GMainContext
1783  * @user_data: the user_data for the callback.
1784  * 
1785  * Finds a source with the given user data for the callback.  If
1786  * multiple sources exist with the same user data, the first
1787  * one found will be returned.
1788  * 
1789  * Return value: (transfer none): the source, if one was found, otherwise %NULL
1790  **/
1791 GSource *
1792 g_main_context_find_source_by_user_data (GMainContext *context,
1793                                          gpointer      user_data)
1794 {
1795   GSource *source;
1796   
1797   if (context == NULL)
1798     context = g_main_context_default ();
1799   
1800   LOCK_CONTEXT (context);
1801
1802   source = context->source_list;
1803   while (source)
1804     {
1805       if (!SOURCE_DESTROYED (source) &&
1806           source->callback_funcs)
1807         {
1808           GSourceFunc callback;
1809           gpointer callback_data = NULL;
1810
1811           source->callback_funcs->get (source->callback_data, source, &callback, &callback_data);
1812
1813           if (callback_data == user_data)
1814             break;
1815         }
1816       source = source->next;
1817     }
1818
1819   UNLOCK_CONTEXT (context);
1820
1821   return source;
1822 }
1823
1824 /**
1825  * g_source_remove:
1826  * @tag: the ID of the source to remove.
1827  * 
1828  * Removes the source with the given id from the default main context. 
1829  * The id of
1830  * a #GSource is given by g_source_get_id(), or will be returned by the
1831  * functions g_source_attach(), g_idle_add(), g_idle_add_full(),
1832  * g_timeout_add(), g_timeout_add_full(), g_child_watch_add(),
1833  * g_child_watch_add_full(), g_io_add_watch(), and g_io_add_watch_full().
1834  *
1835  * See also g_source_destroy(). You must use g_source_destroy() for sources
1836  * added to a non-default main context.
1837  *
1838  * Return value: %TRUE if the source was found and removed.
1839  **/
1840 gboolean
1841 g_source_remove (guint tag)
1842 {
1843   GSource *source;
1844   
1845   g_return_val_if_fail (tag > 0, FALSE);
1846
1847   source = g_main_context_find_source_by_id (NULL, tag);
1848   if (source)
1849     g_source_destroy (source);
1850
1851   return source != NULL;
1852 }
1853
1854 /**
1855  * g_source_remove_by_user_data:
1856  * @user_data: the user_data for the callback.
1857  * 
1858  * Removes a source from the default main loop context given the user
1859  * data for the callback. If multiple sources exist with the same user
1860  * data, only one will be destroyed.
1861  * 
1862  * Return value: %TRUE if a source was found and removed. 
1863  **/
1864 gboolean
1865 g_source_remove_by_user_data (gpointer user_data)
1866 {
1867   GSource *source;
1868   
1869   source = g_main_context_find_source_by_user_data (NULL, user_data);
1870   if (source)
1871     {
1872       g_source_destroy (source);
1873       return TRUE;
1874     }
1875   else
1876     return FALSE;
1877 }
1878
1879 /**
1880  * g_source_remove_by_funcs_user_data:
1881  * @funcs: The @source_funcs passed to g_source_new()
1882  * @user_data: the user data for the callback
1883  * 
1884  * Removes a source from the default main loop context given the
1885  * source functions and user data. If multiple sources exist with the
1886  * same source functions and user data, only one will be destroyed.
1887  * 
1888  * Return value: %TRUE if a source was found and removed. 
1889  **/
1890 gboolean
1891 g_source_remove_by_funcs_user_data (GSourceFuncs *funcs,
1892                                     gpointer      user_data)
1893 {
1894   GSource *source;
1895
1896   g_return_val_if_fail (funcs != NULL, FALSE);
1897
1898   source = g_main_context_find_source_by_funcs_user_data (NULL, funcs, user_data);
1899   if (source)
1900     {
1901       g_source_destroy (source);
1902       return TRUE;
1903     }
1904   else
1905     return FALSE;
1906 }
1907
1908 /**
1909  * g_get_current_time:
1910  * @result: #GTimeVal structure in which to store current time.
1911  *
1912  * Equivalent to the UNIX gettimeofday() function, but portable.
1913  *
1914  * You may find g_get_real_time() to be more convenient.
1915  **/
1916 void
1917 g_get_current_time (GTimeVal *result)
1918 {
1919 #ifndef G_OS_WIN32
1920   struct timeval r;
1921
1922   g_return_if_fail (result != NULL);
1923
1924   /*this is required on alpha, there the timeval structs are int's
1925     not longs and a cast only would fail horribly*/
1926   gettimeofday (&r, NULL);
1927   result->tv_sec = r.tv_sec;
1928   result->tv_usec = r.tv_usec;
1929 #else
1930   FILETIME ft;
1931   guint64 time64;
1932
1933   g_return_if_fail (result != NULL);
1934
1935   GetSystemTimeAsFileTime (&ft);
1936   memmove (&time64, &ft, sizeof (FILETIME));
1937
1938   /* Convert from 100s of nanoseconds since 1601-01-01
1939    * to Unix epoch. Yes, this is Y2038 unsafe.
1940    */
1941   time64 -= G_GINT64_CONSTANT (116444736000000000);
1942   time64 /= 10;
1943
1944   result->tv_sec = time64 / 1000000;
1945   result->tv_usec = time64 % 1000000;
1946 #endif
1947 }
1948
1949 /**
1950  * g_get_real_time:
1951  *
1952  * Queries the system wall-clock time.
1953  *
1954  * This call is functionally equivalent to g_get_current_time() except
1955  * that the return value is often more convenient than dealing with a
1956  * #GTimeVal.
1957  *
1958  * You should only use this call if you are actually interested in the real
1959  * wall-clock time.  g_get_monotonic_time() is probably more useful for
1960  * measuring intervals.
1961  *
1962  * Returns: the number of microseconds since January 1, 1970 UTC.
1963  *
1964  * Since: 2.28
1965  **/
1966 gint64
1967 g_get_real_time (void)
1968 {
1969   GTimeVal tv;
1970
1971   g_get_current_time (&tv);
1972
1973   return (((gint64) tv.tv_sec) * 1000000) + tv.tv_usec;
1974 }
1975
1976 #ifdef G_OS_WIN32
1977 static ULONGLONG (*g_GetTickCount64) (void) = NULL;
1978 static guint32 g_win32_tick_epoch = 0;
1979
1980 G_GNUC_INTERNAL void
1981 g_clock_win32_init (void)
1982 {
1983   HMODULE kernel32;
1984
1985   g_GetTickCount64 = NULL;
1986   kernel32 = GetModuleHandle ("KERNEL32.DLL");
1987   if (kernel32 != NULL)
1988     g_GetTickCount64 = (void *) GetProcAddress (kernel32, "GetTickCount64");
1989   g_win32_tick_epoch = ((guint32)GetTickCount()) >> 31;
1990 }
1991 #endif
1992
1993 /**
1994  * g_get_monotonic_time:
1995  *
1996  * Queries the system monotonic time, if available.
1997  *
1998  * On POSIX systems with clock_gettime() and <literal>CLOCK_MONOTONIC</literal> this call
1999  * is a very shallow wrapper for that.  Otherwise, we make a best effort
2000  * that probably involves returning the wall clock time (with at least
2001  * microsecond accuracy, subject to the limitations of the OS kernel).
2002  *
2003  * It's important to note that POSIX <literal>CLOCK_MONOTONIC</literal> does
2004  * not count time spent while the machine is suspended.
2005  *
2006  * On Windows, "limitations of the OS kernel" is a rather substantial
2007  * statement.  Depending on the configuration of the system, the wall
2008  * clock time is updated as infrequently as 64 times a second (which
2009  * is approximately every 16ms). Also, the on XP (not on Vista or later)
2010  * the monitonic clock is locally monotonic, but may differ in exact
2011  * value between processes due to timer wrap handling.
2012  *
2013  * Returns: the monotonic time, in microseconds
2014  *
2015  * Since: 2.28
2016  **/
2017 gint64
2018 g_get_monotonic_time (void)
2019 {
2020 #ifdef HAVE_CLOCK_GETTIME
2021   /* librt clock_gettime() is our first choice */
2022   struct timespec ts;
2023
2024 #ifdef CLOCK_MONOTONIC
2025   clock_gettime (CLOCK_MONOTONIC, &ts);
2026 #else
2027   clock_gettime (CLOCK_REALTIME, &ts);
2028 #endif
2029
2030   /* In theory monotonic time can have any epoch.
2031    *
2032    * glib presently assumes the following:
2033    *
2034    *   1) The epoch comes some time after the birth of Jesus of Nazareth, but
2035    *      not more than 10000 years later.
2036    *
2037    *   2) The current time also falls sometime within this range.
2038    *
2039    * These two reasonable assumptions leave us with a maximum deviation from
2040    * the epoch of 10000 years, or 315569520000000000 seconds.
2041    *
2042    * If we restrict ourselves to this range then the number of microseconds
2043    * will always fit well inside the constraints of a int64 (by a factor of
2044    * about 29).
2045    *
2046    * If you actually hit the following assertion, probably you should file a
2047    * bug against your operating system for being excessively silly.
2048    **/
2049   g_assert (G_GINT64_CONSTANT (-315569520000000000) < ts.tv_sec &&
2050             ts.tv_sec < G_GINT64_CONSTANT (315569520000000000));
2051
2052   return (((gint64) ts.tv_sec) * 1000000) + (ts.tv_nsec / 1000);
2053
2054 #elif defined (G_OS_WIN32)
2055   guint64 ticks;
2056   guint32 ticks32;
2057
2058   /* There are four of sources for the monotonic on windows:
2059    *
2060    * Three are based on a (1 msec accuracy, but only read periodically) clock chip:
2061    * - GetTickCount (GTC)
2062    *    32bit msec counter, updated each ~15msec, wraps in ~50 days
2063    * - GetTickCount64 (GTC64)
2064    *    Same as GetTickCount, but extended to 64bit, so no wrap
2065    *    Only availible in Vista or later
2066    * - timeGetTime (TGT)
2067    *    similar to GetTickCount by default: 15msec, 50 day wrap.
2068    *    availible in winmm.dll (thus known as the multi media timers) 
2069    *    However apps can raise the system timer clock frequency using timeBeginPeriod()
2070    *    increasing the accuracy up to 1 msec, at a cost in general system performancs
2071    *    and battery use.
2072    *
2073    * One is based on high precision clocks:
2074    * - QueryPrecisionCounter (QPC)
2075    *    This has much higher accuracy, but is not guaranteed monotonic, and
2076    *    has lots of complications like clock jumps and different times on different
2077    *    cpus. It also has lower long term accuracy (i.e. it will drift compared to
2078    *    the low precision clocks.
2079    *
2080    * Additionally, the precision availible in the timer-based wakeup such as
2081    * MsgWaitForMultipleObjectsEx (which is what the mainloop is based on) is based
2082    * on the TGT resolution, so by default it is ~15msec, but can be increased by apps.
2083    *
2084    * The QPC timer has too many issues to be used as is. The only way it could be used
2085    * is to use it to interpolate the lower precision clocks. Firefox does something like
2086    * this:
2087    *   https://bugzilla.mozilla.org/show_bug.cgi?id=363258
2088    * 
2089    * However this seems quite complicated, so we're not doing this right now.
2090    *
2091    * The approach we take instead is to use the TGT timer, extenting it to 64bit
2092    * either by using the GTC64 value, or if that is not availible, a process local
2093    * time epoch that we increment when we detect a timer wrap (assumes that we read
2094    * the time at least once every 50 days).
2095    *
2096    * This means that:
2097    *  - We have a globally consistent monotonic clock on Vista and later
2098    *  - We have a locally monotonic clock on XP
2099    *  - Apps that need higher precision in timeouts and clock reads can call 
2100    *    timeBeginPeriod() to increase it as much as they want
2101    */
2102
2103   if (g_GetTickCount64 != NULL)
2104     {
2105       guint32 ticks_as_32bit;
2106
2107       ticks = g_GetTickCount64 ();
2108       ticks32 = timeGetTime();
2109
2110       /* GTC64 and TGT are sampled at different times, however they 
2111        * have the same base and source (msecs since system boot). 
2112        * They can differ with as much as -16 to +16 msecs.
2113        * We can't just inject the low bits into the 64bit counter 
2114        * as one of the counters can have wrapped in 32bit space and
2115        * the other not. Instead we calulate the signed differece
2116        * in 32bit space and apply that difference to the 64bit counter.
2117        */
2118       ticks_as_32bit = (guint32)ticks;
2119
2120       /* We could do some 2s complement hack, but we play it safe */
2121       if (ticks32 - ticks_as_32bit <= G_MAXINT32)
2122         ticks += ticks32 - ticks_as_32bit;
2123       else
2124         ticks -= ticks_as_32bit - ticks32;
2125     }
2126   else
2127     {
2128       guint32 epoch;
2129
2130       epoch = g_atomic_int_get (&g_win32_tick_epoch);
2131
2132       /* Must read ticks after the epoch, then we're guaranteed
2133          that the ticks value we read is higher or equal to any
2134          previous ones that lead to the writing of the epoch. */
2135       ticks32 = timeGetTime();
2136
2137       /* We store the msb of the current time as the lsb
2138        * of the epoch. Comparing these bits lets us detect when
2139        * the 32bit counter has wrapped so we can increase the
2140        * epoch.
2141        * This will work as long as this function is called at
2142        * least once every ~24 days, which is half the wrap time
2143        * of a 32bit msec counter. I think this is pretty likely.
2144        *
2145        * Note that g_win32_tick_epoch is a process local state,
2146        * so the monotonic clock will not be the same between
2147        * processes.
2148        */
2149       if ((ticks32 >> 31) != (epoch & 1))
2150         {
2151           epoch++;
2152           g_atomic_int_set (&g_win32_tick_epoch, epoch);
2153         }
2154
2155
2156       ticks = (guint64)ticks32 | ((guint64)epoch) << 31;
2157     }
2158
2159   return ticks * 1000;
2160
2161 #else /* !HAVE_CLOCK_GETTIME && ! G_OS_WIN32*/
2162
2163   /* It may look like we are discarding accuracy on Windows (since its
2164    * current time is expressed in 100s of nanoseconds) but according to
2165    * many sources, the time is only updated 64 times per second, so
2166    * microsecond accuracy is more than enough.
2167    */
2168   GTimeVal tv;
2169
2170   g_get_current_time (&tv);
2171
2172   return (((gint64) tv.tv_sec) * 1000000) + tv.tv_usec;
2173 #endif
2174 }
2175
2176 static void
2177 g_main_dispatch_free (gpointer dispatch)
2178 {
2179   g_slice_free (GMainDispatch, dispatch);
2180 }
2181
2182 /* Running the main loop */
2183
2184 static GMainDispatch *
2185 get_dispatch (void)
2186 {
2187   static GPrivate depth_private = G_PRIVATE_INIT (g_main_dispatch_free);
2188   GMainDispatch *dispatch;
2189
2190   dispatch = g_private_get (&depth_private);
2191
2192   if (!dispatch)
2193     {
2194       dispatch = g_slice_new0 (GMainDispatch);
2195       g_private_set (&depth_private, dispatch);
2196     }
2197
2198   return dispatch;
2199 }
2200
2201 /**
2202  * g_main_depth:
2203  *
2204  * Returns the depth of the stack of calls to
2205  * g_main_context_dispatch() on any #GMainContext in the current thread.
2206  *  That is, when called from the toplevel, it gives 0. When
2207  * called from within a callback from g_main_context_iteration()
2208  * (or g_main_loop_run(), etc.) it returns 1. When called from within 
2209  * a callback to a recursive call to g_main_context_iteration(),
2210  * it returns 2. And so forth.
2211  *
2212  * This function is useful in a situation like the following:
2213  * Imagine an extremely simple "garbage collected" system.
2214  *
2215  * |[
2216  * static GList *free_list;
2217  * 
2218  * gpointer
2219  * allocate_memory (gsize size)
2220  * { 
2221  *   gpointer result = g_malloc (size);
2222  *   free_list = g_list_prepend (free_list, result);
2223  *   return result;
2224  * }
2225  * 
2226  * void
2227  * free_allocated_memory (void)
2228  * {
2229  *   GList *l;
2230  *   for (l = free_list; l; l = l->next);
2231  *     g_free (l->data);
2232  *   g_list_free (free_list);
2233  *   free_list = NULL;
2234  *  }
2235  * 
2236  * [...]
2237  * 
2238  * while (TRUE); 
2239  *  {
2240  *    g_main_context_iteration (NULL, TRUE);
2241  *    free_allocated_memory();
2242  *   }
2243  * ]|
2244  *
2245  * This works from an application, however, if you want to do the same
2246  * thing from a library, it gets more difficult, since you no longer
2247  * control the main loop. You might think you can simply use an idle
2248  * function to make the call to free_allocated_memory(), but that
2249  * doesn't work, since the idle function could be called from a
2250  * recursive callback. This can be fixed by using g_main_depth()
2251  *
2252  * |[
2253  * gpointer
2254  * allocate_memory (gsize size)
2255  * { 
2256  *   FreeListBlock *block = g_new (FreeListBlock, 1);
2257  *   block->mem = g_malloc (size);
2258  *   block->depth = g_main_depth ();   
2259  *   free_list = g_list_prepend (free_list, block);
2260  *   return block->mem;
2261  * }
2262  * 
2263  * void
2264  * free_allocated_memory (void)
2265  * {
2266  *   GList *l;
2267  *   
2268  *   int depth = g_main_depth ();
2269  *   for (l = free_list; l; );
2270  *     {
2271  *       GList *next = l->next;
2272  *       FreeListBlock *block = l->data;
2273  *       if (block->depth > depth)
2274  *         {
2275  *           g_free (block->mem);
2276  *           g_free (block);
2277  *           free_list = g_list_delete_link (free_list, l);
2278  *         }
2279  *               
2280  *       l = next;
2281  *     }
2282  *   }
2283  * ]|
2284  *
2285  * There is a temptation to use g_main_depth() to solve
2286  * problems with reentrancy. For instance, while waiting for data
2287  * to be received from the network in response to a menu item,
2288  * the menu item might be selected again. It might seem that
2289  * one could make the menu item's callback return immediately
2290  * and do nothing if g_main_depth() returns a value greater than 1.
2291  * However, this should be avoided since the user then sees selecting
2292  * the menu item do nothing. Furthermore, you'll find yourself adding
2293  * these checks all over your code, since there are doubtless many,
2294  * many things that the user could do. Instead, you can use the
2295  * following techniques:
2296  *
2297  * <orderedlist>
2298  *  <listitem>
2299  *   <para>
2300  *     Use gtk_widget_set_sensitive() or modal dialogs to prevent
2301  *     the user from interacting with elements while the main
2302  *     loop is recursing.
2303  *   </para>
2304  *  </listitem>
2305  *  <listitem>
2306  *   <para>
2307  *     Avoid main loop recursion in situations where you can't handle
2308  *     arbitrary  callbacks. Instead, structure your code so that you
2309  *     simply return to the main loop and then get called again when
2310  *     there is more work to do.
2311  *   </para>
2312  *  </listitem>
2313  * </orderedlist>
2314  * 
2315  * Return value: The main loop recursion level in the current thread
2316  **/
2317 int
2318 g_main_depth (void)
2319 {
2320   GMainDispatch *dispatch = get_dispatch ();
2321   return dispatch->depth;
2322 }
2323
2324 /**
2325  * g_main_current_source:
2326  *
2327  * Returns the currently firing source for this thread.
2328  * 
2329  * Return value: (transfer none): The currently firing source or %NULL.
2330  *
2331  * Since: 2.12
2332  */
2333 GSource *
2334 g_main_current_source (void)
2335 {
2336   GMainDispatch *dispatch = get_dispatch ();
2337   return dispatch->dispatching_sources ? dispatch->dispatching_sources->data : NULL;
2338 }
2339
2340 /**
2341  * g_source_is_destroyed:
2342  * @source: a #GSource
2343  *
2344  * Returns whether @source has been destroyed.
2345  *
2346  * This is important when you operate upon your objects 
2347  * from within idle handlers, but may have freed the object 
2348  * before the dispatch of your idle handler.
2349  *
2350  * |[
2351  * static gboolean 
2352  * idle_callback (gpointer data)
2353  * {
2354  *   SomeWidget *self = data;
2355  *    
2356  *   GDK_THREADS_ENTER (<!-- -->);
2357  *   /<!-- -->* do stuff with self *<!-- -->/
2358  *   self->idle_id = 0;
2359  *   GDK_THREADS_LEAVE (<!-- -->);
2360  *    
2361  *   return G_SOURCE_REMOVE;
2362  * }
2363  *  
2364  * static void 
2365  * some_widget_do_stuff_later (SomeWidget *self)
2366  * {
2367  *   self->idle_id = g_idle_add (idle_callback, self);
2368  * }
2369  *  
2370  * static void 
2371  * some_widget_finalize (GObject *object)
2372  * {
2373  *   SomeWidget *self = SOME_WIDGET (object);
2374  *    
2375  *   if (self->idle_id)
2376  *     g_source_remove (self->idle_id);
2377  *    
2378  *   G_OBJECT_CLASS (parent_class)->finalize (object);
2379  * }
2380  * ]|
2381  *
2382  * This will fail in a multi-threaded application if the 
2383  * widget is destroyed before the idle handler fires due 
2384  * to the use after free in the callback. A solution, to 
2385  * this particular problem, is to check to if the source
2386  * has already been destroy within the callback.
2387  *
2388  * |[
2389  * static gboolean 
2390  * idle_callback (gpointer data)
2391  * {
2392  *   SomeWidget *self = data;
2393  *   
2394  *   GDK_THREADS_ENTER ();
2395  *   if (!g_source_is_destroyed (g_main_current_source ()))
2396  *     {
2397  *       /<!-- -->* do stuff with self *<!-- -->/
2398  *     }
2399  *   GDK_THREADS_LEAVE ();
2400  *   
2401  *   return FALSE;
2402  * }
2403  * ]|
2404  *
2405  * Return value: %TRUE if the source has been destroyed
2406  *
2407  * Since: 2.12
2408  */
2409 gboolean
2410 g_source_is_destroyed (GSource *source)
2411 {
2412   return SOURCE_DESTROYED (source);
2413 }
2414
2415 /* Temporarily remove all this source's file descriptors from the
2416  * poll(), so that if data comes available for one of the file descriptors
2417  * we don't continually spin in the poll()
2418  */
2419 /* HOLDS: source->context's lock */
2420 static void
2421 block_source (GSource *source)
2422 {
2423   GSList *tmp_list;
2424
2425   g_return_if_fail (!SOURCE_BLOCKED (source));
2426
2427   tmp_list = source->poll_fds;
2428   while (tmp_list)
2429     {
2430       g_main_context_remove_poll_unlocked (source->context, tmp_list->data);
2431       tmp_list = tmp_list->next;
2432     }
2433 }
2434
2435 /* HOLDS: source->context's lock */
2436 static void
2437 unblock_source (GSource *source)
2438 {
2439   GSList *tmp_list;
2440   
2441   g_return_if_fail (!SOURCE_BLOCKED (source)); /* Source already unblocked */
2442   g_return_if_fail (!SOURCE_DESTROYED (source));
2443   
2444   tmp_list = source->poll_fds;
2445   while (tmp_list)
2446     {
2447       g_main_context_add_poll_unlocked (source->context, source->priority, tmp_list->data);
2448       tmp_list = tmp_list->next;
2449     }
2450 }
2451
2452 /* HOLDS: context's lock */
2453 static void
2454 g_main_dispatch (GMainContext *context)
2455 {
2456   GMainDispatch *current = get_dispatch ();
2457   guint i;
2458
2459   for (i = 0; i < context->pending_dispatches->len; i++)
2460     {
2461       GSource *source = context->pending_dispatches->pdata[i];
2462
2463       context->pending_dispatches->pdata[i] = NULL;
2464       g_assert (source);
2465
2466       source->flags &= ~G_SOURCE_READY;
2467
2468       if (!SOURCE_DESTROYED (source))
2469         {
2470           gboolean was_in_call;
2471           gpointer user_data = NULL;
2472           GSourceFunc callback = NULL;
2473           GSourceCallbackFuncs *cb_funcs;
2474           gpointer cb_data;
2475           gboolean need_destroy;
2476
2477           gboolean (*dispatch) (GSource *,
2478                                 GSourceFunc,
2479                                 gpointer);
2480           GSList current_source_link;
2481
2482           dispatch = source->source_funcs->dispatch;
2483           cb_funcs = source->callback_funcs;
2484           cb_data = source->callback_data;
2485
2486           if (cb_funcs)
2487             cb_funcs->ref (cb_data);
2488           
2489           if ((source->flags & G_SOURCE_CAN_RECURSE) == 0)
2490             block_source (source);
2491           
2492           was_in_call = source->flags & G_HOOK_FLAG_IN_CALL;
2493           source->flags |= G_HOOK_FLAG_IN_CALL;
2494
2495           if (cb_funcs)
2496             cb_funcs->get (cb_data, source, &callback, &user_data);
2497
2498           UNLOCK_CONTEXT (context);
2499
2500           current->depth++;
2501           /* The on-stack allocation of the GSList is unconventional, but
2502            * we know that the lifetime of the link is bounded to this
2503            * function as the link is kept in a thread specific list and
2504            * not manipulated outside of this function and its descendants.
2505            * Avoiding the overhead of a g_slist_alloc() is useful as many
2506            * applications do little more than dispatch events.
2507            *
2508            * This is a performance hack - do not revert to g_slist_prepend()!
2509            */
2510           current_source_link.data = source;
2511           current_source_link.next = current->dispatching_sources;
2512           current->dispatching_sources = &current_source_link;
2513           need_destroy = ! dispatch (source,
2514                                      callback,
2515                                      user_data);
2516           g_assert (current->dispatching_sources == &current_source_link);
2517           current->dispatching_sources = current_source_link.next;
2518           current->depth--;
2519           
2520           if (cb_funcs)
2521             cb_funcs->unref (cb_data);
2522
2523           LOCK_CONTEXT (context);
2524           
2525           if (!was_in_call)
2526             source->flags &= ~G_HOOK_FLAG_IN_CALL;
2527
2528           if ((source->flags & G_SOURCE_CAN_RECURSE) == 0 &&
2529               !SOURCE_DESTROYED (source))
2530             unblock_source (source);
2531           
2532           /* Note: this depends on the fact that we can't switch
2533            * sources from one main context to another
2534            */
2535           if (need_destroy && !SOURCE_DESTROYED (source))
2536             {
2537               g_assert (source->context == context);
2538               g_source_destroy_internal (source, context, TRUE);
2539             }
2540         }
2541       
2542       SOURCE_UNREF (source, context);
2543     }
2544
2545   g_ptr_array_set_size (context->pending_dispatches, 0);
2546 }
2547
2548 /* Holds context's lock */
2549 static inline GSource *
2550 next_valid_source (GMainContext *context,
2551                    GSource      *source)
2552 {
2553   GSource *new_source = source ? source->next : context->source_list;
2554
2555   while (new_source)
2556     {
2557       if (!SOURCE_DESTROYED (new_source))
2558         {
2559           new_source->ref_count++;
2560           break;
2561         }
2562       
2563       new_source = new_source->next;
2564     }
2565
2566   if (source)
2567     SOURCE_UNREF (source, context);
2568           
2569   return new_source;
2570 }
2571
2572 /**
2573  * g_main_context_acquire:
2574  * @context: a #GMainContext
2575  * 
2576  * Tries to become the owner of the specified context.
2577  * If some other thread is the owner of the context,
2578  * returns %FALSE immediately. Ownership is properly
2579  * recursive: the owner can require ownership again
2580  * and will release ownership when g_main_context_release()
2581  * is called as many times as g_main_context_acquire().
2582  *
2583  * You must be the owner of a context before you
2584  * can call g_main_context_prepare(), g_main_context_query(),
2585  * g_main_context_check(), g_main_context_dispatch().
2586  * 
2587  * Return value: %TRUE if the operation succeeded, and
2588  *   this thread is now the owner of @context.
2589  **/
2590 gboolean 
2591 g_main_context_acquire (GMainContext *context)
2592 {
2593   gboolean result = FALSE;
2594   GThread *self = G_THREAD_SELF;
2595
2596   if (context == NULL)
2597     context = g_main_context_default ();
2598   
2599   LOCK_CONTEXT (context);
2600
2601   if (!context->owner)
2602     {
2603       context->owner = self;
2604       g_assert (context->owner_count == 0);
2605     }
2606
2607   if (context->owner == self)
2608     {
2609       context->owner_count++;
2610       result = TRUE;
2611     }
2612
2613   UNLOCK_CONTEXT (context); 
2614   
2615   return result;
2616 }
2617
2618 /**
2619  * g_main_context_release:
2620  * @context: a #GMainContext
2621  * 
2622  * Releases ownership of a context previously acquired by this thread
2623  * with g_main_context_acquire(). If the context was acquired multiple
2624  * times, the ownership will be released only when g_main_context_release()
2625  * is called as many times as it was acquired.
2626  **/
2627 void
2628 g_main_context_release (GMainContext *context)
2629 {
2630   if (context == NULL)
2631     context = g_main_context_default ();
2632   
2633   LOCK_CONTEXT (context);
2634
2635   context->owner_count--;
2636   if (context->owner_count == 0)
2637     {
2638       context->owner = NULL;
2639
2640       if (context->waiters)
2641         {
2642           GMainWaiter *waiter = context->waiters->data;
2643           gboolean loop_internal_waiter = (waiter->mutex == &context->mutex);
2644           context->waiters = g_slist_delete_link (context->waiters,
2645                                                   context->waiters);
2646           if (!loop_internal_waiter)
2647             g_mutex_lock (waiter->mutex);
2648           
2649           g_cond_signal (waiter->cond);
2650           
2651           if (!loop_internal_waiter)
2652             g_mutex_unlock (waiter->mutex);
2653         }
2654     }
2655
2656   UNLOCK_CONTEXT (context); 
2657 }
2658
2659 /**
2660  * g_main_context_wait:
2661  * @context: a #GMainContext
2662  * @cond: a condition variable
2663  * @mutex: a mutex, currently held
2664  * 
2665  * Tries to become the owner of the specified context,
2666  * as with g_main_context_acquire(). But if another thread
2667  * is the owner, atomically drop @mutex and wait on @cond until 
2668  * that owner releases ownership or until @cond is signaled, then
2669  * try again (once) to become the owner.
2670  * 
2671  * Return value: %TRUE if the operation succeeded, and
2672  *   this thread is now the owner of @context.
2673  **/
2674 gboolean
2675 g_main_context_wait (GMainContext *context,
2676                      GCond        *cond,
2677                      GMutex       *mutex)
2678 {
2679   gboolean result = FALSE;
2680   GThread *self = G_THREAD_SELF;
2681   gboolean loop_internal_waiter;
2682   
2683   if (context == NULL)
2684     context = g_main_context_default ();
2685
2686   loop_internal_waiter = (mutex == &context->mutex);
2687   
2688   if (!loop_internal_waiter)
2689     LOCK_CONTEXT (context);
2690
2691   if (context->owner && context->owner != self)
2692     {
2693       GMainWaiter waiter;
2694
2695       waiter.cond = cond;
2696       waiter.mutex = mutex;
2697
2698       context->waiters = g_slist_append (context->waiters, &waiter);
2699       
2700       if (!loop_internal_waiter)
2701         UNLOCK_CONTEXT (context);
2702       g_cond_wait (cond, mutex);
2703       if (!loop_internal_waiter)      
2704         LOCK_CONTEXT (context);
2705
2706       context->waiters = g_slist_remove (context->waiters, &waiter);
2707     }
2708
2709   if (!context->owner)
2710     {
2711       context->owner = self;
2712       g_assert (context->owner_count == 0);
2713     }
2714
2715   if (context->owner == self)
2716     {
2717       context->owner_count++;
2718       result = TRUE;
2719     }
2720
2721   if (!loop_internal_waiter)
2722     UNLOCK_CONTEXT (context); 
2723   
2724   return result;
2725 }
2726
2727 /**
2728  * g_main_context_prepare:
2729  * @context: a #GMainContext
2730  * @priority: location to store priority of highest priority
2731  *            source already ready.
2732  * 
2733  * Prepares to poll sources within a main loop. The resulting information
2734  * for polling is determined by calling g_main_context_query ().
2735  * 
2736  * Return value: %TRUE if some source is ready to be dispatched
2737  *               prior to polling.
2738  **/
2739 gboolean
2740 g_main_context_prepare (GMainContext *context,
2741                         gint         *priority)
2742 {
2743   gint i;
2744   gint n_ready = 0;
2745   gint current_priority = G_MAXINT;
2746   GSource *source;
2747
2748   if (context == NULL)
2749     context = g_main_context_default ();
2750   
2751   LOCK_CONTEXT (context);
2752
2753   context->time_is_fresh = FALSE;
2754
2755   if (context->in_check_or_prepare)
2756     {
2757       g_warning ("g_main_context_prepare() called recursively from within a source's check() or "
2758                  "prepare() member.");
2759       UNLOCK_CONTEXT (context);
2760       return FALSE;
2761     }
2762
2763 #if 0
2764   /* If recursing, finish up current dispatch, before starting over */
2765   if (context->pending_dispatches)
2766     {
2767       if (dispatch)
2768         g_main_dispatch (context, &current_time);
2769       
2770       UNLOCK_CONTEXT (context);
2771       return TRUE;
2772     }
2773 #endif
2774
2775   /* If recursing, clear list of pending dispatches */
2776
2777   for (i = 0; i < context->pending_dispatches->len; i++)
2778     {
2779       if (context->pending_dispatches->pdata[i])
2780         SOURCE_UNREF ((GSource *)context->pending_dispatches->pdata[i], context);
2781     }
2782   g_ptr_array_set_size (context->pending_dispatches, 0);
2783   
2784   /* Prepare all sources */
2785
2786   context->timeout = -1;
2787   
2788   source = next_valid_source (context, NULL);
2789   while (source)
2790     {
2791       gint source_timeout = -1;
2792
2793       if ((n_ready > 0) && (source->priority > current_priority))
2794         {
2795           SOURCE_UNREF (source, context);
2796           break;
2797         }
2798       if (SOURCE_BLOCKED (source))
2799         goto next;
2800
2801       if (!(source->flags & G_SOURCE_READY))
2802         {
2803           gboolean result;
2804           gboolean (*prepare)  (GSource  *source, 
2805                                 gint     *timeout);
2806
2807           prepare = source->source_funcs->prepare;
2808           context->in_check_or_prepare++;
2809           UNLOCK_CONTEXT (context);
2810
2811           result = (*prepare) (source, &source_timeout);
2812
2813           LOCK_CONTEXT (context);
2814           context->in_check_or_prepare--;
2815
2816           if (result)
2817             {
2818               GSource *ready_source = source;
2819
2820               while (ready_source)
2821                 {
2822                   ready_source->flags |= G_SOURCE_READY;
2823                   ready_source = ready_source->priv ? ready_source->priv->parent_source : NULL;
2824                 }
2825             }
2826         }
2827
2828       if (source->flags & G_SOURCE_READY)
2829         {
2830           n_ready++;
2831           current_priority = source->priority;
2832           context->timeout = 0;
2833         }
2834       
2835       if (source_timeout >= 0)
2836         {
2837           if (context->timeout < 0)
2838             context->timeout = source_timeout;
2839           else
2840             context->timeout = MIN (context->timeout, source_timeout);
2841         }
2842
2843     next:
2844       source = next_valid_source (context, source);
2845     }
2846
2847   UNLOCK_CONTEXT (context);
2848   
2849   if (priority)
2850     *priority = current_priority;
2851   
2852   return (n_ready > 0);
2853 }
2854
2855 /**
2856  * g_main_context_query:
2857  * @context: a #GMainContext
2858  * @max_priority: maximum priority source to check
2859  * @timeout_: (out): location to store timeout to be used in polling
2860  * @fds: (out caller-allocates) (array length=n_fds): location to
2861  *       store #GPollFD records that need to be polled.
2862  * @n_fds: length of @fds.
2863  * 
2864  * Determines information necessary to poll this main loop.
2865  * 
2866  * Return value: the number of records actually stored in @fds,
2867  *   or, if more than @n_fds records need to be stored, the number
2868  *   of records that need to be stored.
2869  **/
2870 gint
2871 g_main_context_query (GMainContext *context,
2872                       gint          max_priority,
2873                       gint         *timeout,
2874                       GPollFD      *fds,
2875                       gint          n_fds)
2876 {
2877   gint n_poll;
2878   GPollRec *pollrec;
2879   
2880   LOCK_CONTEXT (context);
2881
2882   pollrec = context->poll_records;
2883   n_poll = 0;
2884   while (pollrec && max_priority >= pollrec->priority)
2885     {
2886       /* We need to include entries with fd->events == 0 in the array because
2887        * otherwise if the application changes fd->events behind our back and 
2888        * makes it non-zero, we'll be out of sync when we check the fds[] array.
2889        * (Changing fd->events after adding an FD wasn't an anticipated use of 
2890        * this API, but it occurs in practice.) */
2891       if (n_poll < n_fds)
2892         {
2893           fds[n_poll].fd = pollrec->fd->fd;
2894           /* In direct contradiction to the Unix98 spec, IRIX runs into
2895            * difficulty if you pass in POLLERR, POLLHUP or POLLNVAL
2896            * flags in the events field of the pollfd while it should
2897            * just ignoring them. So we mask them out here.
2898            */
2899           fds[n_poll].events = pollrec->fd->events & ~(G_IO_ERR|G_IO_HUP|G_IO_NVAL);
2900           fds[n_poll].revents = 0;
2901         }
2902
2903       pollrec = pollrec->next;
2904       n_poll++;
2905     }
2906
2907   context->poll_changed = FALSE;
2908   
2909   if (timeout)
2910     {
2911       *timeout = context->timeout;
2912       if (*timeout != 0)
2913         context->time_is_fresh = FALSE;
2914     }
2915   
2916   UNLOCK_CONTEXT (context);
2917
2918   return n_poll;
2919 }
2920
2921 /**
2922  * g_main_context_check:
2923  * @context: a #GMainContext
2924  * @max_priority: the maximum numerical priority of sources to check
2925  * @fds: (array length=n_fds): array of #GPollFD's that was passed to
2926  *       the last call to g_main_context_query()
2927  * @n_fds: return value of g_main_context_query()
2928  * 
2929  * Passes the results of polling back to the main loop.
2930  * 
2931  * Return value: %TRUE if some sources are ready to be dispatched.
2932  **/
2933 gboolean
2934 g_main_context_check (GMainContext *context,
2935                       gint          max_priority,
2936                       GPollFD      *fds,
2937                       gint          n_fds)
2938 {
2939   GSource *source;
2940   GPollRec *pollrec;
2941   gint n_ready = 0;
2942   gint i;
2943    
2944   LOCK_CONTEXT (context);
2945
2946   if (context->in_check_or_prepare)
2947     {
2948       g_warning ("g_main_context_check() called recursively from within a source's check() or "
2949                  "prepare() member.");
2950       UNLOCK_CONTEXT (context);
2951       return FALSE;
2952     }
2953
2954   if (context->wake_up_rec.events)
2955     g_wakeup_acknowledge (context->wakeup);
2956
2957   /* If the set of poll file descriptors changed, bail out
2958    * and let the main loop rerun
2959    */
2960   if (context->poll_changed)
2961     {
2962       UNLOCK_CONTEXT (context);
2963       return FALSE;
2964     }
2965   
2966   pollrec = context->poll_records;
2967   i = 0;
2968   while (i < n_fds)
2969     {
2970       if (pollrec->fd->events)
2971         pollrec->fd->revents = fds[i].revents;
2972
2973       pollrec = pollrec->next;
2974       i++;
2975     }
2976
2977   source = next_valid_source (context, NULL);
2978   while (source)
2979     {
2980       if ((n_ready > 0) && (source->priority > max_priority))
2981         {
2982           SOURCE_UNREF (source, context);
2983           break;
2984         }
2985       if (SOURCE_BLOCKED (source))
2986         goto next;
2987
2988       if (!(source->flags & G_SOURCE_READY))
2989         {
2990           gboolean result;
2991           gboolean (*check) (GSource  *source);
2992
2993           check = source->source_funcs->check;
2994           
2995           context->in_check_or_prepare++;
2996           UNLOCK_CONTEXT (context);
2997           
2998           result = (*check) (source);
2999           
3000           LOCK_CONTEXT (context);
3001           context->in_check_or_prepare--;
3002           
3003           if (result)
3004             {
3005               GSource *ready_source = source;
3006
3007               while (ready_source)
3008                 {
3009                   ready_source->flags |= G_SOURCE_READY;
3010                   ready_source = ready_source->priv ? ready_source->priv->parent_source : NULL;
3011                 }
3012             }
3013         }
3014
3015       if (source->flags & G_SOURCE_READY)
3016         {
3017           source->ref_count++;
3018           g_ptr_array_add (context->pending_dispatches, source);
3019
3020           n_ready++;
3021
3022           /* never dispatch sources with less priority than the first
3023            * one we choose to dispatch
3024            */
3025           max_priority = source->priority;
3026         }
3027
3028     next:
3029       source = next_valid_source (context, source);
3030     }
3031
3032   UNLOCK_CONTEXT (context);
3033
3034   return n_ready > 0;
3035 }
3036
3037 /**
3038  * g_main_context_dispatch:
3039  * @context: a #GMainContext
3040  * 
3041  * Dispatches all pending sources.
3042  **/
3043 void
3044 g_main_context_dispatch (GMainContext *context)
3045 {
3046   LOCK_CONTEXT (context);
3047
3048   if (context->pending_dispatches->len > 0)
3049     {
3050       g_main_dispatch (context);
3051     }
3052
3053   UNLOCK_CONTEXT (context);
3054 }
3055
3056 /* HOLDS context lock */
3057 static gboolean
3058 g_main_context_iterate (GMainContext *context,
3059                         gboolean      block,
3060                         gboolean      dispatch,
3061                         GThread      *self)
3062 {
3063   gint max_priority;
3064   gint timeout;
3065   gboolean some_ready;
3066   gint nfds, allocated_nfds;
3067   GPollFD *fds = NULL;
3068
3069   UNLOCK_CONTEXT (context);
3070
3071   if (!g_main_context_acquire (context))
3072     {
3073       gboolean got_ownership;
3074
3075       LOCK_CONTEXT (context);
3076
3077       if (!block)
3078         return FALSE;
3079
3080       got_ownership = g_main_context_wait (context,
3081                                            &context->cond,
3082                                            &context->mutex);
3083
3084       if (!got_ownership)
3085         return FALSE;
3086     }
3087   else
3088     LOCK_CONTEXT (context);
3089   
3090   if (!context->cached_poll_array)
3091     {
3092       context->cached_poll_array_size = context->n_poll_records;
3093       context->cached_poll_array = g_new (GPollFD, context->n_poll_records);
3094     }
3095
3096   allocated_nfds = context->cached_poll_array_size;
3097   fds = context->cached_poll_array;
3098   
3099   UNLOCK_CONTEXT (context);
3100
3101   g_main_context_prepare (context, &max_priority); 
3102   
3103   while ((nfds = g_main_context_query (context, max_priority, &timeout, fds, 
3104                                        allocated_nfds)) > allocated_nfds)
3105     {
3106       LOCK_CONTEXT (context);
3107       g_free (fds);
3108       context->cached_poll_array_size = allocated_nfds = nfds;
3109       context->cached_poll_array = fds = g_new (GPollFD, nfds);
3110       UNLOCK_CONTEXT (context);
3111     }
3112
3113   if (!block)
3114     timeout = 0;
3115   
3116   g_main_context_poll (context, timeout, max_priority, fds, nfds);
3117   
3118   some_ready = g_main_context_check (context, max_priority, fds, nfds);
3119   
3120   if (dispatch)
3121     g_main_context_dispatch (context);
3122   
3123   g_main_context_release (context);
3124
3125   LOCK_CONTEXT (context);
3126
3127   return some_ready;
3128 }
3129
3130 /**
3131  * g_main_context_pending:
3132  * @context: a #GMainContext (if %NULL, the default context will be used)
3133  *
3134  * Checks if any sources have pending events for the given context.
3135  * 
3136  * Return value: %TRUE if events are pending.
3137  **/
3138 gboolean 
3139 g_main_context_pending (GMainContext *context)
3140 {
3141   gboolean retval;
3142
3143   if (!context)
3144     context = g_main_context_default();
3145
3146   LOCK_CONTEXT (context);
3147   retval = g_main_context_iterate (context, FALSE, FALSE, G_THREAD_SELF);
3148   UNLOCK_CONTEXT (context);
3149   
3150   return retval;
3151 }
3152
3153 /**
3154  * g_main_context_iteration:
3155  * @context: a #GMainContext (if %NULL, the default context will be used) 
3156  * @may_block: whether the call may block.
3157  * 
3158  * Runs a single iteration for the given main loop. This involves
3159  * checking to see if any event sources are ready to be processed,
3160  * then if no events sources are ready and @may_block is %TRUE, waiting
3161  * for a source to become ready, then dispatching the highest priority
3162  * events sources that are ready. Otherwise, if @may_block is %FALSE 
3163  * sources are not waited to become ready, only those highest priority 
3164  * events sources will be dispatched (if any), that are ready at this 
3165  * given moment without further waiting.
3166  *
3167  * Note that even when @may_block is %TRUE, it is still possible for 
3168  * g_main_context_iteration() to return %FALSE, since the the wait may 
3169  * be interrupted for other reasons than an event source becoming ready.
3170  * 
3171  * Return value: %TRUE if events were dispatched.
3172  **/
3173 gboolean
3174 g_main_context_iteration (GMainContext *context, gboolean may_block)
3175 {
3176   gboolean retval;
3177
3178   if (!context)
3179     context = g_main_context_default();
3180   
3181   LOCK_CONTEXT (context);
3182   retval = g_main_context_iterate (context, may_block, TRUE, G_THREAD_SELF);
3183   UNLOCK_CONTEXT (context);
3184   
3185   return retval;
3186 }
3187
3188 /**
3189  * g_main_loop_new:
3190  * @context: (allow-none): a #GMainContext  (if %NULL, the default context will be used).
3191  * @is_running: set to %TRUE to indicate that the loop is running. This
3192  * is not very important since calling g_main_loop_run() will set this to
3193  * %TRUE anyway.
3194  * 
3195  * Creates a new #GMainLoop structure.
3196  * 
3197  * Return value: a new #GMainLoop.
3198  **/
3199 GMainLoop *
3200 g_main_loop_new (GMainContext *context,
3201                  gboolean      is_running)
3202 {
3203   GMainLoop *loop;
3204
3205   if (!context)
3206     context = g_main_context_default();
3207   
3208   g_main_context_ref (context);
3209
3210   loop = g_new0 (GMainLoop, 1);
3211   loop->context = context;
3212   loop->is_running = is_running != FALSE;
3213   loop->ref_count = 1;
3214   
3215   return loop;
3216 }
3217
3218 /**
3219  * g_main_loop_ref:
3220  * @loop: a #GMainLoop
3221  * 
3222  * Increases the reference count on a #GMainLoop object by one.
3223  * 
3224  * Return value: @loop
3225  **/
3226 GMainLoop *
3227 g_main_loop_ref (GMainLoop *loop)
3228 {
3229   g_return_val_if_fail (loop != NULL, NULL);
3230   g_return_val_if_fail (g_atomic_int_get (&loop->ref_count) > 0, NULL);
3231
3232   g_atomic_int_inc (&loop->ref_count);
3233
3234   return loop;
3235 }
3236
3237 /**
3238  * g_main_loop_unref:
3239  * @loop: a #GMainLoop
3240  * 
3241  * Decreases the reference count on a #GMainLoop object by one. If
3242  * the result is zero, free the loop and free all associated memory.
3243  **/
3244 void
3245 g_main_loop_unref (GMainLoop *loop)
3246 {
3247   g_return_if_fail (loop != NULL);
3248   g_return_if_fail (g_atomic_int_get (&loop->ref_count) > 0);
3249
3250   if (!g_atomic_int_dec_and_test (&loop->ref_count))
3251     return;
3252
3253   g_main_context_unref (loop->context);
3254   g_free (loop);
3255 }
3256
3257 /**
3258  * g_main_loop_run:
3259  * @loop: a #GMainLoop
3260  * 
3261  * Runs a main loop until g_main_loop_quit() is called on the loop.
3262  * If this is called for the thread of the loop's #GMainContext,
3263  * it will process events from the loop, otherwise it will
3264  * simply wait.
3265  **/
3266 void 
3267 g_main_loop_run (GMainLoop *loop)
3268 {
3269   GThread *self = G_THREAD_SELF;
3270
3271   g_return_if_fail (loop != NULL);
3272   g_return_if_fail (g_atomic_int_get (&loop->ref_count) > 0);
3273
3274   if (!g_main_context_acquire (loop->context))
3275     {
3276       gboolean got_ownership = FALSE;
3277       
3278       /* Another thread owns this context */
3279       LOCK_CONTEXT (loop->context);
3280
3281       g_atomic_int_inc (&loop->ref_count);
3282
3283       if (!loop->is_running)
3284         loop->is_running = TRUE;
3285
3286       while (loop->is_running && !got_ownership)
3287         got_ownership = g_main_context_wait (loop->context,
3288                                              &loop->context->cond,
3289                                              &loop->context->mutex);
3290       
3291       if (!loop->is_running)
3292         {
3293           UNLOCK_CONTEXT (loop->context);
3294           if (got_ownership)
3295             g_main_context_release (loop->context);
3296           g_main_loop_unref (loop);
3297           return;
3298         }
3299
3300       g_assert (got_ownership);
3301     }
3302   else
3303     LOCK_CONTEXT (loop->context);
3304
3305   if (loop->context->in_check_or_prepare)
3306     {
3307       g_warning ("g_main_loop_run(): called recursively from within a source's "
3308                  "check() or prepare() member, iteration not possible.");
3309       return;
3310     }
3311
3312   g_atomic_int_inc (&loop->ref_count);
3313   loop->is_running = TRUE;
3314   while (loop->is_running)
3315     g_main_context_iterate (loop->context, TRUE, TRUE, self);
3316
3317   UNLOCK_CONTEXT (loop->context);
3318   
3319   g_main_context_release (loop->context);
3320   
3321   g_main_loop_unref (loop);
3322 }
3323
3324 /**
3325  * g_main_loop_quit:
3326  * @loop: a #GMainLoop
3327  * 
3328  * Stops a #GMainLoop from running. Any calls to g_main_loop_run()
3329  * for the loop will return. 
3330  *
3331  * Note that sources that have already been dispatched when 
3332  * g_main_loop_quit() is called will still be executed.
3333  **/
3334 void 
3335 g_main_loop_quit (GMainLoop *loop)
3336 {
3337   g_return_if_fail (loop != NULL);
3338   g_return_if_fail (g_atomic_int_get (&loop->ref_count) > 0);
3339
3340   LOCK_CONTEXT (loop->context);
3341   loop->is_running = FALSE;
3342   g_wakeup_signal (loop->context->wakeup);
3343
3344   g_cond_broadcast (&loop->context->cond);
3345
3346   UNLOCK_CONTEXT (loop->context);
3347 }
3348
3349 /**
3350  * g_main_loop_is_running:
3351  * @loop: a #GMainLoop.
3352  * 
3353  * Checks to see if the main loop is currently being run via g_main_loop_run().
3354  * 
3355  * Return value: %TRUE if the mainloop is currently being run.
3356  **/
3357 gboolean
3358 g_main_loop_is_running (GMainLoop *loop)
3359 {
3360   g_return_val_if_fail (loop != NULL, FALSE);
3361   g_return_val_if_fail (g_atomic_int_get (&loop->ref_count) > 0, FALSE);
3362
3363   return loop->is_running;
3364 }
3365
3366 /**
3367  * g_main_loop_get_context:
3368  * @loop: a #GMainLoop.
3369  * 
3370  * Returns the #GMainContext of @loop.
3371  * 
3372  * Return value: (transfer none): the #GMainContext of @loop
3373  **/
3374 GMainContext *
3375 g_main_loop_get_context (GMainLoop *loop)
3376 {
3377   g_return_val_if_fail (loop != NULL, NULL);
3378   g_return_val_if_fail (g_atomic_int_get (&loop->ref_count) > 0, NULL);
3379  
3380   return loop->context;
3381 }
3382
3383 /* HOLDS: context's lock */
3384 static void
3385 g_main_context_poll (GMainContext *context,
3386                      gint          timeout,
3387                      gint          priority,
3388                      GPollFD      *fds,
3389                      gint          n_fds)
3390 {
3391 #ifdef  G_MAIN_POLL_DEBUG
3392   GTimer *poll_timer;
3393   GPollRec *pollrec;
3394   gint i;
3395 #endif
3396
3397   GPollFunc poll_func;
3398
3399   if (n_fds || timeout != 0)
3400     {
3401 #ifdef  G_MAIN_POLL_DEBUG
3402       if (_g_main_poll_debug)
3403         {
3404           g_print ("polling context=%p n=%d timeout=%d\n",
3405                    context, n_fds, timeout);
3406           poll_timer = g_timer_new ();
3407         }
3408 #endif
3409
3410       LOCK_CONTEXT (context);
3411
3412       poll_func = context->poll_func;
3413       
3414       UNLOCK_CONTEXT (context);
3415       if ((*poll_func) (fds, n_fds, timeout) < 0 && errno != EINTR)
3416         {
3417 #ifndef G_OS_WIN32
3418           g_warning ("poll(2) failed due to: %s.",
3419                      g_strerror (errno));
3420 #else
3421           /* If g_poll () returns -1, it has already called g_warning() */
3422 #endif
3423         }
3424       
3425 #ifdef  G_MAIN_POLL_DEBUG
3426       if (_g_main_poll_debug)
3427         {
3428           LOCK_CONTEXT (context);
3429
3430           g_print ("g_main_poll(%d) timeout: %d - elapsed %12.10f seconds",
3431                    n_fds,
3432                    timeout,
3433                    g_timer_elapsed (poll_timer, NULL));
3434           g_timer_destroy (poll_timer);
3435           pollrec = context->poll_records;
3436
3437           while (pollrec != NULL)
3438             {
3439               i = 0;
3440               while (i < n_fds)
3441                 {
3442                   if (fds[i].fd == pollrec->fd->fd &&
3443                       pollrec->fd->events &&
3444                       fds[i].revents)
3445                     {
3446                       g_print (" [" G_POLLFD_FORMAT " :", fds[i].fd);
3447                       if (fds[i].revents & G_IO_IN)
3448                         g_print ("i");
3449                       if (fds[i].revents & G_IO_OUT)
3450                         g_print ("o");
3451                       if (fds[i].revents & G_IO_PRI)
3452                         g_print ("p");
3453                       if (fds[i].revents & G_IO_ERR)
3454                         g_print ("e");
3455                       if (fds[i].revents & G_IO_HUP)
3456                         g_print ("h");
3457                       if (fds[i].revents & G_IO_NVAL)
3458                         g_print ("n");
3459                       g_print ("]");
3460                     }
3461                   i++;
3462                 }
3463               pollrec = pollrec->next;
3464             }
3465           g_print ("\n");
3466
3467           UNLOCK_CONTEXT (context);
3468         }
3469 #endif
3470     } /* if (n_fds || timeout != 0) */
3471 }
3472
3473 /**
3474  * g_main_context_add_poll:
3475  * @context: a #GMainContext (or %NULL for the default context)
3476  * @fd: a #GPollFD structure holding information about a file
3477  *      descriptor to watch.
3478  * @priority: the priority for this file descriptor which should be
3479  *      the same as the priority used for g_source_attach() to ensure that the
3480  *      file descriptor is polled whenever the results may be needed.
3481  * 
3482  * Adds a file descriptor to the set of file descriptors polled for
3483  * this context. This will very seldom be used directly. Instead
3484  * a typical event source will use g_source_add_poll() instead.
3485  **/
3486 void
3487 g_main_context_add_poll (GMainContext *context,
3488                          GPollFD      *fd,
3489                          gint          priority)
3490 {
3491   if (!context)
3492     context = g_main_context_default ();
3493   
3494   g_return_if_fail (g_atomic_int_get (&context->ref_count) > 0);
3495   g_return_if_fail (fd);
3496
3497   LOCK_CONTEXT (context);
3498   g_main_context_add_poll_unlocked (context, priority, fd);
3499   UNLOCK_CONTEXT (context);
3500 }
3501
3502 /* HOLDS: main_loop_lock */
3503 static void 
3504 g_main_context_add_poll_unlocked (GMainContext *context,
3505                                   gint          priority,
3506                                   GPollFD      *fd)
3507 {
3508   GPollRec *prevrec, *nextrec;
3509   GPollRec *newrec = g_slice_new (GPollRec);
3510
3511   /* This file descriptor may be checked before we ever poll */
3512   fd->revents = 0;
3513   newrec->fd = fd;
3514   newrec->priority = priority;
3515
3516   prevrec = context->poll_records_tail;
3517   nextrec = NULL;
3518   while (prevrec && priority < prevrec->priority)
3519     {
3520       nextrec = prevrec;
3521       prevrec = prevrec->prev;
3522     }
3523
3524   if (prevrec)
3525     prevrec->next = newrec;
3526   else
3527     context->poll_records = newrec;
3528
3529   newrec->prev = prevrec;
3530   newrec->next = nextrec;
3531
3532   if (nextrec)
3533     nextrec->prev = newrec;
3534   else 
3535     context->poll_records_tail = newrec;
3536
3537   context->n_poll_records++;
3538
3539   context->poll_changed = TRUE;
3540
3541   /* Now wake up the main loop if it is waiting in the poll() */
3542   g_wakeup_signal (context->wakeup);
3543 }
3544
3545 /**
3546  * g_main_context_remove_poll:
3547  * @context:a #GMainContext 
3548  * @fd: a #GPollFD descriptor previously added with g_main_context_add_poll()
3549  * 
3550  * Removes file descriptor from the set of file descriptors to be
3551  * polled for a particular context.
3552  **/
3553 void
3554 g_main_context_remove_poll (GMainContext *context,
3555                             GPollFD      *fd)
3556 {
3557   if (!context)
3558     context = g_main_context_default ();
3559   
3560   g_return_if_fail (g_atomic_int_get (&context->ref_count) > 0);
3561   g_return_if_fail (fd);
3562
3563   LOCK_CONTEXT (context);
3564   g_main_context_remove_poll_unlocked (context, fd);
3565   UNLOCK_CONTEXT (context);
3566 }
3567
3568 static void
3569 g_main_context_remove_poll_unlocked (GMainContext *context,
3570                                      GPollFD      *fd)
3571 {
3572   GPollRec *pollrec, *prevrec, *nextrec;
3573
3574   prevrec = NULL;
3575   pollrec = context->poll_records;
3576
3577   while (pollrec)
3578     {
3579       nextrec = pollrec->next;
3580       if (pollrec->fd == fd)
3581         {
3582           if (prevrec != NULL)
3583             prevrec->next = nextrec;
3584           else
3585             context->poll_records = nextrec;
3586
3587           if (nextrec != NULL)
3588             nextrec->prev = prevrec;
3589           else
3590             context->poll_records_tail = prevrec;
3591
3592           g_slice_free (GPollRec, pollrec);
3593
3594           context->n_poll_records--;
3595           break;
3596         }
3597       prevrec = pollrec;
3598       pollrec = nextrec;
3599     }
3600
3601   context->poll_changed = TRUE;
3602   
3603   /* Now wake up the main loop if it is waiting in the poll() */
3604   g_wakeup_signal (context->wakeup);
3605 }
3606
3607 /**
3608  * g_source_get_current_time:
3609  * @source:  a #GSource
3610  * @timeval: #GTimeVal structure in which to store current time.
3611  *
3612  * This function ignores @source and is otherwise the same as
3613  * g_get_current_time().
3614  *
3615  * Deprecated: 2.28: use g_source_get_time() instead
3616  **/
3617 void
3618 g_source_get_current_time (GSource  *source,
3619                            GTimeVal *timeval)
3620 {
3621   g_get_current_time (timeval);
3622 }
3623
3624 /**
3625  * g_source_get_time:
3626  * @source: a #GSource
3627  *
3628  * Gets the time to be used when checking this source. The advantage of
3629  * calling this function over calling g_get_monotonic_time() directly is
3630  * that when checking multiple sources, GLib can cache a single value
3631  * instead of having to repeatedly get the system monotonic time.
3632  *
3633  * The time here is the system monotonic time, if available, or some
3634  * other reasonable alternative otherwise.  See g_get_monotonic_time().
3635  *
3636  * Returns: the monotonic time in microseconds
3637  *
3638  * Since: 2.28
3639  **/
3640 gint64
3641 g_source_get_time (GSource *source)
3642 {
3643   GMainContext *context;
3644   gint64 result;
3645
3646   g_return_val_if_fail (source->context != NULL, 0);
3647
3648   context = source->context;
3649
3650   LOCK_CONTEXT (context);
3651
3652   if (!context->time_is_fresh)
3653     {
3654       context->time = g_get_monotonic_time ();
3655       context->time_is_fresh = TRUE;
3656     }
3657
3658   result = context->time;
3659
3660   UNLOCK_CONTEXT (context);
3661
3662   return result;
3663 }
3664
3665 /**
3666  * g_main_context_set_poll_func:
3667  * @context: a #GMainContext
3668  * @func: the function to call to poll all file descriptors
3669  * 
3670  * Sets the function to use to handle polling of file descriptors. It
3671  * will be used instead of the poll() system call 
3672  * (or GLib's replacement function, which is used where 
3673  * poll() isn't available).
3674  *
3675  * This function could possibly be used to integrate the GLib event
3676  * loop with an external event loop.
3677  **/
3678 void
3679 g_main_context_set_poll_func (GMainContext *context,
3680                               GPollFunc     func)
3681 {
3682   if (!context)
3683     context = g_main_context_default ();
3684   
3685   g_return_if_fail (g_atomic_int_get (&context->ref_count) > 0);
3686
3687   LOCK_CONTEXT (context);
3688   
3689   if (func)
3690     context->poll_func = func;
3691   else
3692     context->poll_func = g_poll;
3693
3694   UNLOCK_CONTEXT (context);
3695 }
3696
3697 /**
3698  * g_main_context_get_poll_func:
3699  * @context: a #GMainContext
3700  * 
3701  * Gets the poll function set by g_main_context_set_poll_func().
3702  * 
3703  * Return value: the poll function
3704  **/
3705 GPollFunc
3706 g_main_context_get_poll_func (GMainContext *context)
3707 {
3708   GPollFunc result;
3709   
3710   if (!context)
3711     context = g_main_context_default ();
3712   
3713   g_return_val_if_fail (g_atomic_int_get (&context->ref_count) > 0, NULL);
3714
3715   LOCK_CONTEXT (context);
3716   result = context->poll_func;
3717   UNLOCK_CONTEXT (context);
3718
3719   return result;
3720 }
3721
3722 /**
3723  * g_main_context_wakeup:
3724  * @context: a #GMainContext
3725  * 
3726  * If @context is currently waiting in a poll(), interrupt
3727  * the poll(), and continue the iteration process.
3728  **/
3729 void
3730 g_main_context_wakeup (GMainContext *context)
3731 {
3732   if (!context)
3733     context = g_main_context_default ();
3734
3735   g_return_if_fail (g_atomic_int_get (&context->ref_count) > 0);
3736
3737   g_wakeup_signal (context->wakeup);
3738 }
3739
3740 /**
3741  * g_main_context_is_owner:
3742  * @context: a #GMainContext
3743  * 
3744  * Determines whether this thread holds the (recursive)
3745  * ownership of this #GMainContext. This is useful to
3746  * know before waiting on another thread that may be
3747  * blocking to get ownership of @context.
3748  *
3749  * Returns: %TRUE if current thread is owner of @context.
3750  *
3751  * Since: 2.10
3752  **/
3753 gboolean
3754 g_main_context_is_owner (GMainContext *context)
3755 {
3756   gboolean is_owner;
3757
3758   if (!context)
3759     context = g_main_context_default ();
3760
3761   LOCK_CONTEXT (context);
3762   is_owner = context->owner == G_THREAD_SELF;
3763   UNLOCK_CONTEXT (context);
3764
3765   return is_owner;
3766 }
3767
3768 /* Timeouts */
3769
3770 static void
3771 g_timeout_set_expiration (GTimeoutSource *timeout_source,
3772                           gint64          current_time)
3773 {
3774   timeout_source->expiration = current_time +
3775                                (guint64) timeout_source->interval * 1000;
3776
3777   if (timeout_source->seconds)
3778     {
3779       gint64 remainder;
3780       static gint timer_perturb = -1;
3781
3782       if (timer_perturb == -1)
3783         {
3784           /*
3785            * we want a per machine/session unique 'random' value; try the dbus
3786            * address first, that has a UUID in it. If there is no dbus, use the
3787            * hostname for hashing.
3788            */
3789           const char *session_bus_address = g_getenv ("DBUS_SESSION_BUS_ADDRESS");
3790           if (!session_bus_address)
3791             session_bus_address = g_getenv ("HOSTNAME");
3792           if (session_bus_address)
3793             timer_perturb = ABS ((gint) g_str_hash (session_bus_address)) % 1000000;
3794           else
3795             timer_perturb = 0;
3796         }
3797
3798       /* We want the microseconds part of the timeout to land on the
3799        * 'timer_perturb' mark, but we need to make sure we don't try to
3800        * set the timeout in the past.  We do this by ensuring that we
3801        * always only *increase* the expiration time by adding a full
3802        * second in the case that the microsecond portion decreases.
3803        */
3804       timeout_source->expiration -= timer_perturb;
3805
3806       remainder = timeout_source->expiration % 1000000;
3807       if (remainder >= 1000000/4)
3808         timeout_source->expiration += 1000000;
3809
3810       timeout_source->expiration -= remainder;
3811       timeout_source->expiration += timer_perturb;
3812     }
3813 }
3814
3815 static gboolean
3816 g_timeout_prepare (GSource *source,
3817                    gint    *timeout)
3818 {
3819   GTimeoutSource *timeout_source = (GTimeoutSource *) source;
3820   gint64 now = g_source_get_time (source);
3821
3822   if (now < timeout_source->expiration)
3823     {
3824       /* Round up to ensure that we don't try again too early */
3825       *timeout = (timeout_source->expiration - now + 999) / 1000;
3826       return FALSE;
3827     }
3828
3829   *timeout = 0;
3830   return TRUE;
3831 }
3832
3833 static gboolean 
3834 g_timeout_check (GSource *source)
3835 {
3836   GTimeoutSource *timeout_source = (GTimeoutSource *) source;
3837   gint64 now = g_source_get_time (source);
3838
3839   return timeout_source->expiration <= now;
3840 }
3841
3842 static gboolean
3843 g_timeout_dispatch (GSource     *source,
3844                     GSourceFunc  callback,
3845                     gpointer     user_data)
3846 {
3847   GTimeoutSource *timeout_source = (GTimeoutSource *)source;
3848   gboolean again;
3849
3850   if (!callback)
3851     {
3852       g_warning ("Timeout source dispatched without callback\n"
3853                  "You must call g_source_set_callback().");
3854       return FALSE;
3855     }
3856
3857   again = callback (user_data);
3858
3859   if (again)
3860     g_timeout_set_expiration (timeout_source, g_source_get_time (source));
3861
3862   return again;
3863 }
3864
3865 /**
3866  * g_timeout_source_new:
3867  * @interval: the timeout interval in milliseconds.
3868  * 
3869  * Creates a new timeout source.
3870  *
3871  * The source will not initially be associated with any #GMainContext
3872  * and must be added to one with g_source_attach() before it will be
3873  * executed.
3874  *
3875  * The interval given is in terms of monotonic time, not wall clock
3876  * time.  See g_get_monotonic_time().
3877  * 
3878  * Return value: the newly-created timeout source
3879  **/
3880 GSource *
3881 g_timeout_source_new (guint interval)
3882 {
3883   GSource *source = g_source_new (&g_timeout_funcs, sizeof (GTimeoutSource));
3884   GTimeoutSource *timeout_source = (GTimeoutSource *)source;
3885
3886   timeout_source->interval = interval;
3887   g_timeout_set_expiration (timeout_source, g_get_monotonic_time ());
3888
3889   return source;
3890 }
3891
3892 /**
3893  * g_timeout_source_new_seconds:
3894  * @interval: the timeout interval in seconds
3895  *
3896  * Creates a new timeout source.
3897  *
3898  * The source will not initially be associated with any #GMainContext
3899  * and must be added to one with g_source_attach() before it will be
3900  * executed.
3901  *
3902  * The scheduling granularity/accuracy of this timeout source will be
3903  * in seconds.
3904  *
3905  * The interval given in terms of monotonic time, not wall clock time.
3906  * See g_get_monotonic_time().
3907  *
3908  * Return value: the newly-created timeout source
3909  *
3910  * Since: 2.14  
3911  **/
3912 GSource *
3913 g_timeout_source_new_seconds (guint interval)
3914 {
3915   GSource *source = g_source_new (&g_timeout_funcs, sizeof (GTimeoutSource));
3916   GTimeoutSource *timeout_source = (GTimeoutSource *)source;
3917
3918   timeout_source->interval = 1000 * interval;
3919   timeout_source->seconds = TRUE;
3920
3921   g_timeout_set_expiration (timeout_source, g_get_monotonic_time ());
3922
3923   return source;
3924 }
3925
3926
3927 /**
3928  * g_timeout_add_full:
3929  * @priority: the priority of the timeout source. Typically this will be in
3930  *            the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
3931  * @interval: the time between calls to the function, in milliseconds
3932  *             (1/1000ths of a second)
3933  * @function: function to call
3934  * @data:     data to pass to @function
3935  * @notify:   function to call when the timeout is removed, or %NULL
3936  * 
3937  * Sets a function to be called at regular intervals, with the given
3938  * priority.  The function is called repeatedly until it returns
3939  * %FALSE, at which point the timeout is automatically destroyed and
3940  * the function will not be called again.  The @notify function is
3941  * called when the timeout is destroyed.  The first call to the
3942  * function will be at the end of the first @interval.
3943  *
3944  * Note that timeout functions may be delayed, due to the processing of other
3945  * event sources. Thus they should not be relied on for precise timing.
3946  * After each call to the timeout function, the time of the next
3947  * timeout is recalculated based on the current time and the given interval
3948  * (it does not try to 'catch up' time lost in delays).
3949  *
3950  * This internally creates a main loop source using g_timeout_source_new()
3951  * and attaches it to the main loop context using g_source_attach(). You can
3952  * do these steps manually if you need greater control.
3953  *
3954  * The interval given in terms of monotonic time, not wall clock time.
3955  * See g_get_monotonic_time().
3956  * 
3957  * Return value: the ID (greater than 0) of the event source.
3958  * Rename to: g_timeout_add
3959  **/
3960 guint
3961 g_timeout_add_full (gint           priority,
3962                     guint          interval,
3963                     GSourceFunc    function,
3964                     gpointer       data,
3965                     GDestroyNotify notify)
3966 {
3967   GSource *source;
3968   guint id;
3969   
3970   g_return_val_if_fail (function != NULL, 0);
3971
3972   source = g_timeout_source_new (interval);
3973
3974   if (priority != G_PRIORITY_DEFAULT)
3975     g_source_set_priority (source, priority);
3976
3977   g_source_set_callback (source, function, data, notify);
3978   id = g_source_attach (source, NULL);
3979   g_source_unref (source);
3980
3981   return id;
3982 }
3983
3984 /**
3985  * g_timeout_add:
3986  * @interval: the time between calls to the function, in milliseconds
3987  *             (1/1000ths of a second)
3988  * @function: function to call
3989  * @data:     data to pass to @function
3990  * 
3991  * Sets a function to be called at regular intervals, with the default
3992  * priority, #G_PRIORITY_DEFAULT.  The function is called repeatedly
3993  * until it returns %FALSE, at which point the timeout is automatically
3994  * destroyed and the function will not be called again.  The first call
3995  * to the function will be at the end of the first @interval.
3996  *
3997  * Note that timeout functions may be delayed, due to the processing of other
3998  * event sources. Thus they should not be relied on for precise timing.
3999  * After each call to the timeout function, the time of the next
4000  * timeout is recalculated based on the current time and the given interval
4001  * (it does not try to 'catch up' time lost in delays).
4002  *
4003  * If you want to have a timer in the "seconds" range and do not care
4004  * about the exact time of the first call of the timer, use the
4005  * g_timeout_add_seconds() function; this function allows for more
4006  * optimizations and more efficient system power usage.
4007  *
4008  * This internally creates a main loop source using g_timeout_source_new()
4009  * and attaches it to the main loop context using g_source_attach(). You can
4010  * do these steps manually if you need greater control.
4011  * 
4012  * The interval given is in terms of monotonic time, not wall clock
4013  * time.  See g_get_monotonic_time().
4014  * 
4015  * Return value: the ID (greater than 0) of the event source.
4016  **/
4017 guint
4018 g_timeout_add (guint32        interval,
4019                GSourceFunc    function,
4020                gpointer       data)
4021 {
4022   return g_timeout_add_full (G_PRIORITY_DEFAULT, 
4023                              interval, function, data, NULL);
4024 }
4025
4026 /**
4027  * g_timeout_add_seconds_full:
4028  * @priority: the priority of the timeout source. Typically this will be in
4029  *            the range between #G_PRIORITY_DEFAULT and #G_PRIORITY_HIGH.
4030  * @interval: the time between calls to the function, in seconds
4031  * @function: function to call
4032  * @data:     data to pass to @function
4033  * @notify:   function to call when the timeout is removed, or %NULL
4034  *
4035  * Sets a function to be called at regular intervals, with @priority.
4036  * The function is called repeatedly until it returns %FALSE, at which
4037  * point the timeout is automatically destroyed and the function will
4038  * not be called again.
4039  *
4040  * Unlike g_timeout_add(), this function operates at whole second granularity.
4041  * The initial starting point of the timer is determined by the implementation
4042  * and the implementation is expected to group multiple timers together so that
4043  * they fire all at the same time.
4044  * To allow this grouping, the @interval to the first timer is rounded
4045  * and can deviate up to one second from the specified interval.
4046  * Subsequent timer iterations will generally run at the specified interval.
4047  *
4048  * Note that timeout functions may be delayed, due to the processing of other
4049  * event sources. Thus they should not be relied on for precise timing.
4050  * After each call to the timeout function, the time of the next
4051  * timeout is recalculated based on the current time and the given @interval
4052  *
4053  * If you want timing more precise than whole seconds, use g_timeout_add()
4054  * instead.
4055  *
4056  * The grouping of timers to fire at the same time results in a more power
4057  * and CPU efficient behavior so if your timer is in multiples of seconds
4058  * and you don't require the first timer exactly one second from now, the
4059  * use of g_timeout_add_seconds() is preferred over g_timeout_add().
4060  *
4061  * This internally creates a main loop source using 
4062  * g_timeout_source_new_seconds() and attaches it to the main loop context 
4063  * using g_source_attach(). You can do these steps manually if you need 
4064  * greater control.
4065  * 
4066  * The interval given is in terms of monotonic time, not wall clock
4067  * time.  See g_get_monotonic_time().
4068  * 
4069  * Return value: the ID (greater than 0) of the event source.
4070  *
4071  * Rename to: g_timeout_add_seconds
4072  * Since: 2.14
4073  **/
4074 guint
4075 g_timeout_add_seconds_full (gint           priority,
4076                             guint32        interval,
4077                             GSourceFunc    function,
4078                             gpointer       data,
4079                             GDestroyNotify notify)
4080 {
4081   GSource *source;
4082   guint id;
4083
4084   g_return_val_if_fail (function != NULL, 0);
4085
4086   source = g_timeout_source_new_seconds (interval);
4087
4088   if (priority != G_PRIORITY_DEFAULT)
4089     g_source_set_priority (source, priority);
4090
4091   g_source_set_callback (source, function, data, notify);
4092   id = g_source_attach (source, NULL);
4093   g_source_unref (source);
4094
4095   return id;
4096 }
4097
4098 /**
4099  * g_timeout_add_seconds:
4100  * @interval: the time between calls to the function, in seconds
4101  * @function: function to call
4102  * @data: data to pass to @function
4103  *
4104  * Sets a function to be called at regular intervals with the default
4105  * priority, #G_PRIORITY_DEFAULT. The function is called repeatedly until
4106  * it returns %FALSE, at which point the timeout is automatically destroyed
4107  * and the function will not be called again.
4108  *
4109  * This internally creates a main loop source using
4110  * g_timeout_source_new_seconds() and attaches it to the main loop context
4111  * using g_source_attach(). You can do these steps manually if you need
4112  * greater control. Also see g_timeout_add_seconds_full().
4113  *
4114  * Note that the first call of the timer may not be precise for timeouts
4115  * of one second. If you need finer precision and have such a timeout,
4116  * you may want to use g_timeout_add() instead.
4117  *
4118  * The interval given is in terms of monotonic time, not wall clock
4119  * time.  See g_get_monotonic_time().
4120  * 
4121  * Return value: the ID (greater than 0) of the event source.
4122  *
4123  * Since: 2.14
4124  **/
4125 guint
4126 g_timeout_add_seconds (guint       interval,
4127                        GSourceFunc function,
4128                        gpointer    data)
4129 {
4130   g_return_val_if_fail (function != NULL, 0);
4131
4132   return g_timeout_add_seconds_full (G_PRIORITY_DEFAULT, interval, function, data, NULL);
4133 }
4134
4135 /* Child watch functions */
4136
4137 #ifdef G_OS_WIN32
4138
4139 static gboolean
4140 g_child_watch_prepare (GSource *source,
4141                        gint    *timeout)
4142 {
4143   *timeout = -1;
4144   return FALSE;
4145 }
4146
4147 static gboolean 
4148 g_child_watch_check (GSource  *source)
4149 {
4150   GChildWatchSource *child_watch_source;
4151   gboolean child_exited;
4152
4153   child_watch_source = (GChildWatchSource *) source;
4154
4155   child_exited = child_watch_source->poll.revents & G_IO_IN;
4156
4157   if (child_exited)
4158     {
4159       DWORD child_status;
4160
4161       /*
4162        * Note: We do _not_ check for the special value of STILL_ACTIVE
4163        * since we know that the process has exited and doing so runs into
4164        * problems if the child process "happens to return STILL_ACTIVE(259)"
4165        * as Microsoft's Platform SDK puts it.
4166        */
4167       if (!GetExitCodeProcess (child_watch_source->pid, &child_status))
4168         {
4169           gchar *emsg = g_win32_error_message (GetLastError ());
4170           g_warning (G_STRLOC ": GetExitCodeProcess() failed: %s", emsg);
4171           g_free (emsg);
4172
4173           child_watch_source->child_status = -1;
4174         }
4175       else
4176         child_watch_source->child_status = child_status;
4177     }
4178
4179   return child_exited;
4180 }
4181
4182 static void
4183 g_child_watch_finalize (GSource *source)
4184 {
4185 }
4186
4187 #else /* G_OS_WIN32 */
4188
4189 static void
4190 wake_source (GSource *source)
4191 {
4192   GMainContext *context;
4193
4194   /* This should be thread-safe:
4195    *
4196    *  - if the source is currently being added to a context, that
4197    *    context will be woken up anyway
4198    *
4199    *  - if the source is currently being destroyed, we simply need not
4200    *    to crash:
4201    *
4202    *    - the memory for the source will remain valid until after the
4203    *      source finalize function was called (which would remove the
4204    *      source from the global list which we are currently holding the
4205    *      lock for)
4206    *
4207    *    - the GMainContext will either be NULL or point to a live
4208    *      GMainContext
4209    *
4210    *    - the GMainContext will remain valid since we hold the
4211    *      main_context_list lock
4212    *
4213    *  Since we are holding a lot of locks here, don't try to enter any
4214    *  more GMainContext functions for fear of dealock -- just hit the
4215    *  GWakeup and run.  Even if that's safe now, it could easily become
4216    *  unsafe with some very minor changes in the future, and signal
4217    *  handling is not the most well-tested codepath.
4218    */
4219   G_LOCK(main_context_list);
4220   context = source->context;
4221   if (context)
4222     g_wakeup_signal (context->wakeup);
4223   G_UNLOCK(main_context_list);
4224 }
4225
4226 static void
4227 dispatch_unix_signals (void)
4228 {
4229   GSList *node;
4230
4231   /* clear this first incase another one arrives while we're processing */
4232   any_unix_signal_pending = FALSE;
4233
4234   G_LOCK(unix_signal_lock);
4235
4236   /* handle GChildWatchSource instances */
4237   if (unix_signal_pending[SIGCHLD])
4238     {
4239       unix_signal_pending[SIGCHLD] = FALSE;
4240
4241       /* The only way we can do this is to scan all of the children.
4242        *
4243        * The docs promise that we will not reap children that we are not
4244        * explicitly watching, so that ties our hands from calling
4245        * waitpid(-1).  We also can't use siginfo's si_pid field since if
4246        * multiple SIGCHLD arrive at the same time, one of them can be
4247        * dropped (since a given UNIX signal can only be pending once).
4248        */
4249       for (node = unix_child_watches; node; node = node->next)
4250         {
4251           GChildWatchSource *source = node->data;
4252
4253           if (!source->child_exited)
4254             {
4255               if (waitpid (source->pid, &source->child_status, WNOHANG) > 0)
4256                 {
4257                   source->child_exited = TRUE;
4258
4259                   wake_source ((GSource *) source);
4260                 }
4261             }
4262         }
4263     }
4264
4265   /* handle GUnixSignalWatchSource instances */
4266   for (node = unix_signal_watches; node; node = node->next)
4267     {
4268       GUnixSignalWatchSource *source = node->data;
4269
4270       if (!source->pending)
4271         {
4272           if (unix_signal_pending[source->signum])
4273             {
4274               unix_signal_pending[source->signum] = FALSE;
4275               source->pending = TRUE;
4276
4277               wake_source ((GSource *) source);
4278             }
4279         }
4280     }
4281
4282   G_UNLOCK(unix_signal_lock);
4283 }
4284
4285 static gboolean
4286 g_child_watch_prepare (GSource *source,
4287                        gint    *timeout)
4288 {
4289   GChildWatchSource *child_watch_source;
4290
4291   child_watch_source = (GChildWatchSource *) source;
4292
4293   return child_watch_source->child_exited;
4294 }
4295
4296 static gboolean
4297 g_child_watch_check (GSource *source)
4298 {
4299   GChildWatchSource *child_watch_source;
4300
4301   child_watch_source = (GChildWatchSource *) source;
4302
4303   return child_watch_source->child_exited;
4304 }
4305
4306 static gboolean
4307 g_unix_signal_watch_prepare (GSource *source,
4308                              gint    *timeout)
4309 {
4310   GUnixSignalWatchSource *unix_signal_source;
4311
4312   unix_signal_source = (GUnixSignalWatchSource *) source;
4313
4314   return unix_signal_source->pending;
4315 }
4316
4317 static gboolean
4318 g_unix_signal_watch_check (GSource  *source)
4319 {
4320   GUnixSignalWatchSource *unix_signal_source;
4321
4322   unix_signal_source = (GUnixSignalWatchSource *) source;
4323
4324   return unix_signal_source->pending;
4325 }
4326
4327 static gboolean
4328 g_unix_signal_watch_dispatch (GSource    *source, 
4329                               GSourceFunc callback,
4330                               gpointer    user_data)
4331 {
4332   GUnixSignalWatchSource *unix_signal_source;
4333
4334   unix_signal_source = (GUnixSignalWatchSource *) source;
4335
4336   if (!callback)
4337     {
4338       g_warning ("Unix signal source dispatched without callback\n"
4339                  "You must call g_source_set_callback().");
4340       return FALSE;
4341     }
4342
4343   (callback) (user_data);
4344
4345   unix_signal_source->pending = FALSE;
4346
4347   return TRUE;
4348 }
4349
4350 static void
4351 ensure_unix_signal_handler_installed_unlocked (int signum)
4352 {
4353   static sigset_t installed_signal_mask;
4354   static gboolean initialized;
4355   struct sigaction action;
4356
4357   if (!initialized)
4358     {
4359       sigemptyset (&installed_signal_mask);
4360       g_get_worker_context ();
4361       initialized = TRUE;
4362     }
4363
4364   if (sigismember (&installed_signal_mask, signum))
4365     return;
4366
4367   sigaddset (&installed_signal_mask, signum);
4368
4369   action.sa_handler = g_unix_signal_handler;
4370   sigemptyset (&action.sa_mask);
4371   action.sa_flags = SA_RESTART | SA_NOCLDSTOP;
4372   sigaction (signum, &action, NULL);
4373 }
4374
4375 GSource *
4376 _g_main_create_unix_signal_watch (int signum)
4377 {
4378   GSource *source;
4379   GUnixSignalWatchSource *unix_signal_source;
4380
4381   source = g_source_new (&g_unix_signal_funcs, sizeof (GUnixSignalWatchSource));
4382   unix_signal_source = (GUnixSignalWatchSource *) source;
4383
4384   unix_signal_source->signum = signum;
4385   unix_signal_source->pending = FALSE;
4386
4387   G_LOCK (unix_signal_lock);
4388   ensure_unix_signal_handler_installed_unlocked (signum);
4389   unix_signal_watches = g_slist_prepend (unix_signal_watches, unix_signal_source);
4390   if (unix_signal_pending[signum])
4391     unix_signal_source->pending = TRUE;
4392   unix_signal_pending[signum] = FALSE;
4393   G_UNLOCK (unix_signal_lock);
4394
4395   return source;
4396 }
4397
4398 static void
4399 g_unix_signal_watch_finalize (GSource    *source)
4400 {
4401   G_LOCK (unix_signal_lock);
4402   unix_signal_watches = g_slist_remove (unix_signal_watches, source);
4403   G_UNLOCK (unix_signal_lock);
4404 }
4405
4406 static void
4407 g_child_watch_finalize (GSource *source)
4408 {
4409   G_LOCK (unix_signal_lock);
4410   unix_child_watches = g_slist_remove (unix_child_watches, source);
4411   G_UNLOCK (unix_signal_lock);
4412 }
4413
4414 #endif /* G_OS_WIN32 */
4415
4416 static gboolean
4417 g_child_watch_dispatch (GSource    *source, 
4418                         GSourceFunc callback,
4419                         gpointer    user_data)
4420 {
4421   GChildWatchSource *child_watch_source;
4422   GChildWatchFunc child_watch_callback = (GChildWatchFunc) callback;
4423
4424   child_watch_source = (GChildWatchSource *) source;
4425
4426   if (!callback)
4427     {
4428       g_warning ("Child watch source dispatched without callback\n"
4429                  "You must call g_source_set_callback().");
4430       return FALSE;
4431     }
4432
4433   (child_watch_callback) (child_watch_source->pid, child_watch_source->child_status, user_data);
4434
4435   /* We never keep a child watch source around as the child is gone */
4436   return FALSE;
4437 }
4438
4439 #ifndef G_OS_WIN32
4440
4441 static void
4442 g_unix_signal_handler (int signum)
4443 {
4444   unix_signal_pending[signum] = TRUE;
4445   any_unix_signal_pending = TRUE;
4446
4447   g_wakeup_signal (glib_worker_context->wakeup);
4448 }
4449
4450 #endif /* !G_OS_WIN32 */
4451
4452 /**
4453  * g_child_watch_source_new:
4454  * @pid: process to watch. On POSIX the pid of a child process. On
4455  * Windows a handle for a process (which doesn't have to be a child).
4456  * 
4457  * Creates a new child_watch source.
4458  *
4459  * The source will not initially be associated with any #GMainContext
4460  * and must be added to one with g_source_attach() before it will be
4461  * executed.
4462  * 
4463  * Note that child watch sources can only be used in conjunction with
4464  * <literal>g_spawn...</literal> when the %G_SPAWN_DO_NOT_REAP_CHILD
4465  * flag is used.
4466  *
4467  * Note that on platforms where #GPid must be explicitly closed
4468  * (see g_spawn_close_pid()) @pid must not be closed while the
4469  * source is still active. Typically, you will want to call
4470  * g_spawn_close_pid() in the callback function for the source.
4471  *
4472  * Note further that using g_child_watch_source_new() is not 
4473  * compatible with calling <literal>waitpid(-1)</literal> in 
4474  * the application. Calling waitpid() for individual pids will
4475  * still work fine. 
4476  * 
4477  * Return value: the newly-created child watch source
4478  *
4479  * Since: 2.4
4480  **/
4481 GSource *
4482 g_child_watch_source_new (GPid pid)
4483 {
4484   GSource *source = g_source_new (&g_child_watch_funcs, sizeof (GChildWatchSource));
4485   GChildWatchSource *child_watch_source = (GChildWatchSource *)source;
4486
4487   child_watch_source->pid = pid;
4488
4489 #ifdef G_OS_WIN32
4490   child_watch_source->poll.fd = (gintptr) pid;
4491   child_watch_source->poll.events = G_IO_IN;
4492
4493   g_source_add_poll (source, &child_watch_source->poll);
4494 #else /* G_OS_WIN32 */
4495   G_LOCK (unix_signal_lock);
4496   ensure_unix_signal_handler_installed_unlocked (SIGCHLD);
4497   unix_child_watches = g_slist_prepend (unix_child_watches, child_watch_source);
4498   if (waitpid (pid, &child_watch_source->child_status, WNOHANG) > 0)
4499     child_watch_source->child_exited = TRUE;
4500   G_UNLOCK (unix_signal_lock);
4501 #endif /* G_OS_WIN32 */
4502
4503   return source;
4504 }
4505
4506 /**
4507  * g_child_watch_add_full:
4508  * @priority: the priority of the idle source. Typically this will be in the
4509  *            range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
4510  * @pid:      process to watch. On POSIX the pid of a child process. On
4511  * Windows a handle for a process (which doesn't have to be a child).
4512  * @function: function to call
4513  * @data:     data to pass to @function
4514  * @notify:   function to call when the idle is removed, or %NULL
4515  * 
4516  * Sets a function to be called when the child indicated by @pid 
4517  * exits, at the priority @priority.
4518  *
4519  * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() 
4520  * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to 
4521  * the spawn function for the child watching to work.
4522  * 
4523  * Note that on platforms where #GPid must be explicitly closed
4524  * (see g_spawn_close_pid()) @pid must not be closed while the
4525  * source is still active. Typically, you will want to call
4526  * g_spawn_close_pid() in the callback function for the source.
4527  * 
4528  * GLib supports only a single callback per process id.
4529  *
4530  * This internally creates a main loop source using 
4531  * g_child_watch_source_new() and attaches it to the main loop context 
4532  * using g_source_attach(). You can do these steps manually if you 
4533  * need greater control.
4534  *
4535  * Return value: the ID (greater than 0) of the event source.
4536  *
4537  * Rename to: g_child_watch_add
4538  * Since: 2.4
4539  **/
4540 guint
4541 g_child_watch_add_full (gint            priority,
4542                         GPid            pid,
4543                         GChildWatchFunc function,
4544                         gpointer        data,
4545                         GDestroyNotify  notify)
4546 {
4547   GSource *source;
4548   guint id;
4549   
4550   g_return_val_if_fail (function != NULL, 0);
4551
4552   source = g_child_watch_source_new (pid);
4553
4554   if (priority != G_PRIORITY_DEFAULT)
4555     g_source_set_priority (source, priority);
4556
4557   g_source_set_callback (source, (GSourceFunc) function, data, notify);
4558   id = g_source_attach (source, NULL);
4559   g_source_unref (source);
4560
4561   return id;
4562 }
4563
4564 /**
4565  * g_child_watch_add:
4566  * @pid:      process id to watch. On POSIX the pid of a child process. On
4567  * Windows a handle for a process (which doesn't have to be a child).
4568  * @function: function to call
4569  * @data:     data to pass to @function
4570  * 
4571  * Sets a function to be called when the child indicated by @pid 
4572  * exits, at a default priority, #G_PRIORITY_DEFAULT.
4573  * 
4574  * If you obtain @pid from g_spawn_async() or g_spawn_async_with_pipes() 
4575  * you will need to pass #G_SPAWN_DO_NOT_REAP_CHILD as flag to 
4576  * the spawn function for the child watching to work.
4577  * 
4578  * Note that on platforms where #GPid must be explicitly closed
4579  * (see g_spawn_close_pid()) @pid must not be closed while the
4580  * source is still active. Typically, you will want to call
4581  * g_spawn_close_pid() in the callback function for the source.
4582  *
4583  * GLib supports only a single callback per process id.
4584  *
4585  * This internally creates a main loop source using 
4586  * g_child_watch_source_new() and attaches it to the main loop context 
4587  * using g_source_attach(). You can do these steps manually if you 
4588  * need greater control.
4589  *
4590  * Return value: the ID (greater than 0) of the event source.
4591  *
4592  * Since: 2.4
4593  **/
4594 guint 
4595 g_child_watch_add (GPid            pid,
4596                    GChildWatchFunc function,
4597                    gpointer        data)
4598 {
4599   return g_child_watch_add_full (G_PRIORITY_DEFAULT, pid, function, data, NULL);
4600 }
4601
4602
4603 /* Idle functions */
4604
4605 static gboolean 
4606 g_idle_prepare  (GSource  *source,
4607                  gint     *timeout)
4608 {
4609   *timeout = 0;
4610
4611   return TRUE;
4612 }
4613
4614 static gboolean 
4615 g_idle_check    (GSource  *source)
4616 {
4617   return TRUE;
4618 }
4619
4620 static gboolean
4621 g_idle_dispatch (GSource    *source, 
4622                  GSourceFunc callback,
4623                  gpointer    user_data)
4624 {
4625   if (!callback)
4626     {
4627       g_warning ("Idle source dispatched without callback\n"
4628                  "You must call g_source_set_callback().");
4629       return FALSE;
4630     }
4631   
4632   return callback (user_data);
4633 }
4634
4635 /**
4636  * g_idle_source_new:
4637  * 
4638  * Creates a new idle source.
4639  *
4640  * The source will not initially be associated with any #GMainContext
4641  * and must be added to one with g_source_attach() before it will be
4642  * executed. Note that the default priority for idle sources is
4643  * %G_PRIORITY_DEFAULT_IDLE, as compared to other sources which
4644  * have a default priority of %G_PRIORITY_DEFAULT.
4645  * 
4646  * Return value: the newly-created idle source
4647  **/
4648 GSource *
4649 g_idle_source_new (void)
4650 {
4651   GSource *source;
4652
4653   source = g_source_new (&g_idle_funcs, sizeof (GSource));
4654   g_source_set_priority (source, G_PRIORITY_DEFAULT_IDLE);
4655
4656   return source;
4657 }
4658
4659 /**
4660  * g_idle_add_full:
4661  * @priority: the priority of the idle source. Typically this will be in the
4662  *            range between #G_PRIORITY_DEFAULT_IDLE and #G_PRIORITY_HIGH_IDLE.
4663  * @function: function to call
4664  * @data:     data to pass to @function
4665  * @notify:   function to call when the idle is removed, or %NULL
4666  * 
4667  * Adds a function to be called whenever there are no higher priority
4668  * events pending.  If the function returns %FALSE it is automatically
4669  * removed from the list of event sources and will not be called again.
4670  * 
4671  * This internally creates a main loop source using g_idle_source_new()
4672  * and attaches it to the main loop context using g_source_attach(). 
4673  * You can do these steps manually if you need greater control.
4674  * 
4675  * Return value: the ID (greater than 0) of the event source.
4676  * Rename to: g_idle_add
4677  **/
4678 guint 
4679 g_idle_add_full (gint           priority,
4680                  GSourceFunc    function,
4681                  gpointer       data,
4682                  GDestroyNotify notify)
4683 {
4684   GSource *source;
4685   guint id;
4686   
4687   g_return_val_if_fail (function != NULL, 0);
4688
4689   source = g_idle_source_new ();
4690
4691   if (priority != G_PRIORITY_DEFAULT_IDLE)
4692     g_source_set_priority (source, priority);
4693
4694   g_source_set_callback (source, function, data, notify);
4695   id = g_source_attach (source, NULL);
4696   g_source_unref (source);
4697
4698   return id;
4699 }
4700
4701 /**
4702  * g_idle_add:
4703  * @function: function to call 
4704  * @data: data to pass to @function.
4705  * 
4706  * Adds a function to be called whenever there are no higher priority
4707  * events pending to the default main loop. The function is given the
4708  * default idle priority, #G_PRIORITY_DEFAULT_IDLE.  If the function
4709  * returns %FALSE it is automatically removed from the list of event
4710  * sources and will not be called again.
4711  * 
4712  * This internally creates a main loop source using g_idle_source_new()
4713  * and attaches it to the main loop context using g_source_attach(). 
4714  * You can do these steps manually if you need greater control.
4715  * 
4716  * Return value: the ID (greater than 0) of the event source.
4717  **/
4718 guint 
4719 g_idle_add (GSourceFunc    function,
4720             gpointer       data)
4721 {
4722   return g_idle_add_full (G_PRIORITY_DEFAULT_IDLE, function, data, NULL);
4723 }
4724
4725 /**
4726  * g_idle_remove_by_data:
4727  * @data: the data for the idle source's callback.
4728  * 
4729  * Removes the idle function with the given data.
4730  * 
4731  * Return value: %TRUE if an idle source was found and removed.
4732  **/
4733 gboolean
4734 g_idle_remove_by_data (gpointer data)
4735 {
4736   return g_source_remove_by_funcs_user_data (&g_idle_funcs, data);
4737 }
4738
4739 /**
4740  * g_main_context_invoke:
4741  * @context: (allow-none): a #GMainContext, or %NULL
4742  * @function: function to call
4743  * @data: data to pass to @function
4744  *
4745  * Invokes a function in such a way that @context is owned during the
4746  * invocation of @function.
4747  *
4748  * If @context is %NULL then the global default main context — as
4749  * returned by g_main_context_default() — is used.
4750  *
4751  * If @context is owned by the current thread, @function is called
4752  * directly.  Otherwise, if @context is the thread-default main context
4753  * of the current thread and g_main_context_acquire() succeeds, then
4754  * @function is called and g_main_context_release() is called
4755  * afterwards.
4756  *
4757  * In any other case, an idle source is created to call @function and
4758  * that source is attached to @context (presumably to be run in another
4759  * thread).  The idle source is attached with #G_PRIORITY_DEFAULT
4760  * priority.  If you want a different priority, use
4761  * g_main_context_invoke_full().
4762  *
4763  * Note that, as with normal idle functions, @function should probably
4764  * return %FALSE.  If it returns %TRUE, it will be continuously run in a
4765  * loop (and may prevent this call from returning).
4766  *
4767  * Since: 2.28
4768  **/
4769 void
4770 g_main_context_invoke (GMainContext *context,
4771                        GSourceFunc   function,
4772                        gpointer      data)
4773 {
4774   g_main_context_invoke_full (context,
4775                               G_PRIORITY_DEFAULT,
4776                               function, data, NULL);
4777 }
4778
4779 /**
4780  * g_main_context_invoke_full:
4781  * @context: (allow-none): a #GMainContext, or %NULL
4782  * @priority: the priority at which to run @function
4783  * @function: function to call
4784  * @data: data to pass to @function
4785  * @notify: a function to call when @data is no longer in use, or %NULL.
4786  *
4787  * Invokes a function in such a way that @context is owned during the
4788  * invocation of @function.
4789  *
4790  * This function is the same as g_main_context_invoke() except that it
4791  * lets you specify the priority incase @function ends up being
4792  * scheduled as an idle and also lets you give a #GDestroyNotify for @data.
4793  *
4794  * @notify should not assume that it is called from any particular
4795  * thread or with any particular context acquired.
4796  *
4797  * Since: 2.28
4798  **/
4799 void
4800 g_main_context_invoke_full (GMainContext   *context,
4801                             gint            priority,
4802                             GSourceFunc     function,
4803                             gpointer        data,
4804                             GDestroyNotify  notify)
4805 {
4806   g_return_if_fail (function != NULL);
4807
4808   if (!context)
4809     context = g_main_context_default ();
4810
4811   if (g_main_context_is_owner (context))
4812     {
4813       while (function (data));
4814       if (notify != NULL)
4815         notify (data);
4816     }
4817
4818   else
4819     {
4820       GMainContext *thread_default;
4821
4822       thread_default = g_main_context_get_thread_default ();
4823
4824       if (!thread_default)
4825         thread_default = g_main_context_default ();
4826
4827       if (thread_default == context && g_main_context_acquire (context))
4828         {
4829           while (function (data));
4830
4831           g_main_context_release (context);
4832
4833           if (notify != NULL)
4834             notify (data);
4835         }
4836       else
4837         {
4838           GSource *source;
4839
4840           source = g_idle_source_new ();
4841           g_source_set_priority (source, priority);
4842           g_source_set_callback (source, function, data, notify);
4843           g_source_attach (source, context);
4844           g_source_unref (source);
4845         }
4846     }
4847 }
4848
4849 static gpointer
4850 glib_worker_main (gpointer data)
4851 {
4852   while (TRUE)
4853     {
4854       g_main_context_iteration (glib_worker_context, TRUE);
4855
4856 #ifdef G_OS_UNIX
4857       if (any_unix_signal_pending)
4858         dispatch_unix_signals ();
4859 #endif
4860     }
4861
4862   return NULL; /* worst GCC warning message ever... */
4863 }
4864
4865 GMainContext *
4866 g_get_worker_context (void)
4867 {
4868   static gsize initialised;
4869
4870   if (g_once_init_enter (&initialised))
4871     {
4872       /* mask all signals in the worker thread */
4873 #ifdef G_OS_UNIX
4874       sigset_t prev_mask;
4875       sigset_t all;
4876
4877       sigfillset (&all);
4878       pthread_sigmask (SIG_SETMASK, &all, &prev_mask);
4879 #endif
4880       glib_worker_context = g_main_context_new ();
4881       g_thread_new ("gmain", glib_worker_main, NULL);
4882 #ifdef G_OS_UNIX
4883       pthread_sigmask (SIG_SETMASK, &prev_mask, NULL);
4884 #endif
4885       g_once_init_leave (&initialised, TRUE);
4886     }
4887
4888   return glib_worker_context;
4889 }