1 /*
2  * This file is part of gtkD.
3  *
4  * gtkD is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU Lesser General Public License
6  * as published by the Free Software Foundation; either version 3
7  * of the License, or (at your option) any later version, with
8  * some exceptions, please read the COPYING file.
9  *
10  * gtkD is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13  * GNU Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public License
16  * along with gtkD; if not, write to the Free Software
17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA
18  */
19 
20 // generated automatically - do not change
21 // find conversion definition on APILookup.txt
22 // implement new conversion functionalities on the wrap.utils pakage
23 
24 
25 module glib.Source;
26 
27 private import glib.ConstructionException;
28 private import glib.MainContext;
29 private import glib.Str;
30 private import glib.TimeVal;
31 private import glib.c.functions;
32 public  import glib.c.types;
33 public  import gtkc.glibtypes;
34 private import gtkd.Loader;
35 
36 
37 /**
38  * The `GSource` struct is an opaque data type
39  * representing an event source.
40  */
41 public class Source
42 {
43 	/** the main Gtk struct */
44 	protected GSource* gSource;
45 	protected bool ownedRef;
46 
47 	/** Get the main Gtk struct */
48 	public GSource* getSourceStruct(bool transferOwnership = false)
49 	{
50 		if (transferOwnership)
51 			ownedRef = false;
52 		return gSource;
53 	}
54 
55 	/** the main Gtk struct as a void* */
56 	protected void* getStruct()
57 	{
58 		return cast(void*)gSource;
59 	}
60 
61 	/**
62 	 * Sets our main struct and passes it to the parent class.
63 	 */
64 	public this (GSource* gSource, bool ownedRef = false)
65 	{
66 		this.gSource = gSource;
67 		this.ownedRef = ownedRef;
68 	}
69 
70 	~this ()
71 	{
72 		if ( Linker.isLoaded(LIBRARY_GLIB) && ownedRef )
73 			g_source_unref(gSource);
74 	}
75 
76 
77 	/**
78 	 * Creates a new #GSource structure. The size is specified to
79 	 * allow creating structures derived from #GSource that contain
80 	 * additional data. The size passed in must be at least
81 	 * `sizeof (GSource)`.
82 	 *
83 	 * The source will not initially be associated with any #GMainContext
84 	 * and must be added to one with g_source_attach() before it will be
85 	 * executed.
86 	 *
87 	 * Params:
88 	 *     sourceFuncs = structure containing functions that implement
89 	 *         the sources behavior.
90 	 *     structSize = size of the #GSource structure to create.
91 	 *
92 	 * Returns: the newly-created #GSource.
93 	 *
94 	 * Throws: ConstructionException GTK+ fails to create the object.
95 	 */
96 	public this(GSourceFuncs* sourceFuncs, uint structSize)
97 	{
98 		auto p = g_source_new(sourceFuncs, structSize);
99 
100 		if(p is null)
101 		{
102 			throw new ConstructionException("null returned by new");
103 		}
104 
105 		this(cast(GSource*) p);
106 	}
107 
108 	/**
109 	 * Adds @child_source to @source as a "polled" source; when @source is
110 	 * added to a #GMainContext, @child_source will be automatically added
111 	 * with the same priority, when @child_source is triggered, it will
112 	 * cause @source to dispatch (in addition to calling its own
113 	 * callback), and when @source is destroyed, it will destroy
114 	 * @child_source as well. (@source will also still be dispatched if
115 	 * its own prepare/check functions indicate that it is ready.)
116 	 *
117 	 * If you don't need @child_source to do anything on its own when it
118 	 * triggers, you can call g_source_set_dummy_callback() on it to set a
119 	 * callback that does nothing (except return %TRUE if appropriate).
120 	 *
121 	 * @source will hold a reference on @child_source while @child_source
122 	 * is attached to it.
123 	 *
124 	 * This API is only intended to be used by implementations of #GSource.
125 	 * Do not call this API on a #GSource that you did not create.
126 	 *
127 	 * Params:
128 	 *     childSource = a second #GSource that @source should "poll"
129 	 *
130 	 * Since: 2.28
131 	 */
132 	public void addChildSource(Source childSource)
133 	{
134 		g_source_add_child_source(gSource, (childSource is null) ? null : childSource.getSourceStruct());
135 	}
136 
137 	/**
138 	 * Adds a file descriptor to the set of file descriptors polled for
139 	 * this source. This is usually combined with g_source_new() to add an
140 	 * event source. The event source's check function will typically test
141 	 * the @revents field in the #GPollFD struct and return %TRUE if events need
142 	 * to be processed.
143 	 *
144 	 * This API is only intended to be used by implementations of #GSource.
145 	 * Do not call this API on a #GSource that you did not create.
146 	 *
147 	 * Using this API forces the linear scanning of event sources on each
148 	 * main loop iteration.  Newly-written event sources should try to use
149 	 * g_source_add_unix_fd() instead of this API.
150 	 *
151 	 * Params:
152 	 *     fd = a #GPollFD structure holding information about a file
153 	 *         descriptor to watch.
154 	 */
155 	public void addPoll(GPollFD* fd)
156 	{
157 		g_source_add_poll(gSource, fd);
158 	}
159 
160 	/**
161 	 * Monitors @fd for the IO events in @events.
162 	 *
163 	 * The tag returned by this function can be used to remove or modify the
164 	 * monitoring of the fd using g_source_remove_unix_fd() or
165 	 * g_source_modify_unix_fd().
166 	 *
167 	 * It is not necessary to remove the fd before destroying the source; it
168 	 * will be cleaned up automatically.
169 	 *
170 	 * This API is only intended to be used by implementations of #GSource.
171 	 * Do not call this API on a #GSource that you did not create.
172 	 *
173 	 * As the name suggests, this function is not available on Windows.
174 	 *
175 	 * Params:
176 	 *     fd = the fd to monitor
177 	 *     events = an event mask
178 	 *
179 	 * Returns: an opaque tag
180 	 *
181 	 * Since: 2.36
182 	 */
183 	public void* addUnixFd(int fd, GIOCondition events)
184 	{
185 		return g_source_add_unix_fd(gSource, fd, events);
186 	}
187 
188 	/**
189 	 * Adds a #GSource to a @context so that it will be executed within
190 	 * that context. Remove it by calling g_source_destroy().
191 	 *
192 	 * Params:
193 	 *     context = a #GMainContext (if %NULL, the default context will be used)
194 	 *
195 	 * Returns: the ID (greater than 0) for the source within the
196 	 *     #GMainContext.
197 	 */
198 	public uint attach(MainContext context)
199 	{
200 		return g_source_attach(gSource, (context is null) ? null : context.getMainContextStruct());
201 	}
202 
203 	/**
204 	 * Removes a source from its #GMainContext, if any, and mark it as
205 	 * destroyed.  The source cannot be subsequently added to another
206 	 * context. It is safe to call this on sources which have already been
207 	 * removed from their context.
208 	 */
209 	public void destroy()
210 	{
211 		g_source_destroy(gSource);
212 	}
213 
214 	/**
215 	 * Checks whether a source is allowed to be called recursively.
216 	 * see g_source_set_can_recurse().
217 	 *
218 	 * Returns: whether recursion is allowed.
219 	 */
220 	public bool getCanRecurse()
221 	{
222 		return g_source_get_can_recurse(gSource) != 0;
223 	}
224 
225 	/**
226 	 * Gets the #GMainContext with which the source is associated.
227 	 *
228 	 * You can call this on a source that has been destroyed, provided
229 	 * that the #GMainContext it was attached to still exists (in which
230 	 * case it will return that #GMainContext). In particular, you can
231 	 * always call this function on the source returned from
232 	 * g_main_current_source(). But calling this function on a source
233 	 * whose #GMainContext has been destroyed is an error.
234 	 *
235 	 * Returns: the #GMainContext with which the
236 	 *     source is associated, or %NULL if the context has not
237 	 *     yet been added to a source.
238 	 */
239 	public MainContext getContext()
240 	{
241 		auto p = g_source_get_context(gSource);
242 
243 		if(p is null)
244 		{
245 			return null;
246 		}
247 
248 		return new MainContext(cast(GMainContext*) p);
249 	}
250 
251 	/**
252 	 * This function ignores @source and is otherwise the same as
253 	 * g_get_current_time().
254 	 *
255 	 * Deprecated: use g_source_get_time() instead
256 	 *
257 	 * Params:
258 	 *     timeval = #GTimeVal structure in which to store current time.
259 	 */
260 	public void getCurrentTime(TimeVal timeval)
261 	{
262 		g_source_get_current_time(gSource, (timeval is null) ? null : timeval.getTimeValStruct());
263 	}
264 
265 	/**
266 	 * Returns the numeric ID for a particular source. The ID of a source
267 	 * is a positive integer which is unique within a particular main loop
268 	 * context. The reverse
269 	 * mapping from ID to source is done by g_main_context_find_source_by_id().
270 	 *
271 	 * You can only call this function while the source is associated to a
272 	 * #GMainContext instance; calling this function before g_source_attach()
273 	 * or after g_source_destroy() yields undefined behavior. The ID returned
274 	 * is unique within the #GMainContext instance passed to g_source_attach().
275 	 *
276 	 * Returns: the ID (greater than 0) for the source
277 	 */
278 	public uint getId()
279 	{
280 		return g_source_get_id(gSource);
281 	}
282 
283 	/**
284 	 * Gets a name for the source, used in debugging and profiling.  The
285 	 * name may be #NULL if it has never been set with g_source_set_name().
286 	 *
287 	 * Returns: the name of the source
288 	 *
289 	 * Since: 2.26
290 	 */
291 	public string getName()
292 	{
293 		return Str.toString(g_source_get_name(gSource));
294 	}
295 
296 	/**
297 	 * Gets the priority of a source.
298 	 *
299 	 * Returns: the priority of the source
300 	 */
301 	public int getPriority()
302 	{
303 		return g_source_get_priority(gSource);
304 	}
305 
306 	/**
307 	 * Gets the "ready time" of @source, as set by
308 	 * g_source_set_ready_time().
309 	 *
310 	 * Any time before the current monotonic time (including 0) is an
311 	 * indication that the source will fire immediately.
312 	 *
313 	 * Returns: the monotonic ready time, -1 for "never"
314 	 */
315 	public long getReadyTime()
316 	{
317 		return g_source_get_ready_time(gSource);
318 	}
319 
320 	/**
321 	 * Gets the time to be used when checking this source. The advantage of
322 	 * calling this function over calling g_get_monotonic_time() directly is
323 	 * that when checking multiple sources, GLib can cache a single value
324 	 * instead of having to repeatedly get the system monotonic time.
325 	 *
326 	 * The time here is the system monotonic time, if available, or some
327 	 * other reasonable alternative otherwise.  See g_get_monotonic_time().
328 	 *
329 	 * Returns: the monotonic time in microseconds
330 	 *
331 	 * Since: 2.28
332 	 */
333 	public long getTime()
334 	{
335 		return g_source_get_time(gSource);
336 	}
337 
338 	/**
339 	 * Returns whether @source has been destroyed.
340 	 *
341 	 * This is important when you operate upon your objects
342 	 * from within idle handlers, but may have freed the object
343 	 * before the dispatch of your idle handler.
344 	 *
345 	 * |[<!-- language="C" -->
346 	 * static gboolean
347 	 * idle_callback (gpointer data)
348 	 * {
349 	 * SomeWidget *self = data;
350 	 *
351 	 * GDK_THREADS_ENTER ();
352 	 * // do stuff with self
353 	 * self->idle_id = 0;
354 	 * GDK_THREADS_LEAVE ();
355 	 *
356 	 * return G_SOURCE_REMOVE;
357 	 * }
358 	 *
359 	 * static void
360 	 * some_widget_do_stuff_later (SomeWidget *self)
361 	 * {
362 	 * self->idle_id = g_idle_add (idle_callback, self);
363 	 * }
364 	 *
365 	 * static void
366 	 * some_widget_finalize (GObject *object)
367 	 * {
368 	 * SomeWidget *self = SOME_WIDGET (object);
369 	 *
370 	 * if (self->idle_id)
371 	 * g_source_remove (self->idle_id);
372 	 *
373 	 * G_OBJECT_CLASS (parent_class)->finalize (object);
374 	 * }
375 	 * ]|
376 	 *
377 	 * This will fail in a multi-threaded application if the
378 	 * widget is destroyed before the idle handler fires due
379 	 * to the use after free in the callback. A solution, to
380 	 * this particular problem, is to check to if the source
381 	 * has already been destroy within the callback.
382 	 *
383 	 * |[<!-- language="C" -->
384 	 * static gboolean
385 	 * idle_callback (gpointer data)
386 	 * {
387 	 * SomeWidget *self = data;
388 	 *
389 	 * GDK_THREADS_ENTER ();
390 	 * if (!g_source_is_destroyed (g_main_current_source ()))
391 	 * {
392 	 * // do stuff with self
393 	 * }
394 	 * GDK_THREADS_LEAVE ();
395 	 *
396 	 * return FALSE;
397 	 * }
398 	 * ]|
399 	 *
400 	 * Calls to this function from a thread other than the one acquired by the
401 	 * #GMainContext the #GSource is attached to are typically redundant, as the
402 	 * source could be destroyed immediately after this function returns. However,
403 	 * once a source is destroyed it cannot be un-destroyed, so this function can be
404 	 * used for opportunistic checks from any thread.
405 	 *
406 	 * Returns: %TRUE if the source has been destroyed
407 	 *
408 	 * Since: 2.12
409 	 */
410 	public bool isDestroyed()
411 	{
412 		return g_source_is_destroyed(gSource) != 0;
413 	}
414 
415 	/**
416 	 * Updates the event mask to watch for the fd identified by @tag.
417 	 *
418 	 * @tag is the tag returned from g_source_add_unix_fd().
419 	 *
420 	 * If you want to remove a fd, don't set its event mask to zero.
421 	 * Instead, call g_source_remove_unix_fd().
422 	 *
423 	 * This API is only intended to be used by implementations of #GSource.
424 	 * Do not call this API on a #GSource that you did not create.
425 	 *
426 	 * As the name suggests, this function is not available on Windows.
427 	 *
428 	 * Params:
429 	 *     tag = the tag from g_source_add_unix_fd()
430 	 *     newEvents = the new event mask to watch
431 	 *
432 	 * Since: 2.36
433 	 */
434 	public void modifyUnixFd(void* tag, GIOCondition newEvents)
435 	{
436 		g_source_modify_unix_fd(gSource, tag, newEvents);
437 	}
438 
439 	/**
440 	 * Queries the events reported for the fd corresponding to @tag on
441 	 * @source during the last poll.
442 	 *
443 	 * The return value of this function is only defined when the function
444 	 * is called from the check or dispatch functions for @source.
445 	 *
446 	 * This API is only intended to be used by implementations of #GSource.
447 	 * Do not call this API on a #GSource that you did not create.
448 	 *
449 	 * As the name suggests, this function is not available on Windows.
450 	 *
451 	 * Params:
452 	 *     tag = the tag from g_source_add_unix_fd()
453 	 *
454 	 * Returns: the conditions reported on the fd
455 	 *
456 	 * Since: 2.36
457 	 */
458 	public GIOCondition queryUnixFd(void* tag)
459 	{
460 		return g_source_query_unix_fd(gSource, tag);
461 	}
462 
463 	alias doref = ref_;
464 	/**
465 	 * Increases the reference count on a source by one.
466 	 *
467 	 * Returns: @source
468 	 */
469 	public Source ref_()
470 	{
471 		auto p = g_source_ref(gSource);
472 
473 		if(p is null)
474 		{
475 			return null;
476 		}
477 
478 		return new Source(cast(GSource*) p, true);
479 	}
480 
481 	/**
482 	 * Detaches @child_source from @source and destroys it.
483 	 *
484 	 * This API is only intended to be used by implementations of #GSource.
485 	 * Do not call this API on a #GSource that you did not create.
486 	 *
487 	 * Params:
488 	 *     childSource = a #GSource previously passed to
489 	 *         g_source_add_child_source().
490 	 *
491 	 * Since: 2.28
492 	 */
493 	public void removeChildSource(Source childSource)
494 	{
495 		g_source_remove_child_source(gSource, (childSource is null) ? null : childSource.getSourceStruct());
496 	}
497 
498 	/**
499 	 * Removes a file descriptor from the set of file descriptors polled for
500 	 * this source.
501 	 *
502 	 * This API is only intended to be used by implementations of #GSource.
503 	 * Do not call this API on a #GSource that you did not create.
504 	 *
505 	 * Params:
506 	 *     fd = a #GPollFD structure previously passed to g_source_add_poll().
507 	 */
508 	public void removePoll(GPollFD* fd)
509 	{
510 		g_source_remove_poll(gSource, fd);
511 	}
512 
513 	/**
514 	 * Reverses the effect of a previous call to g_source_add_unix_fd().
515 	 *
516 	 * You only need to call this if you want to remove an fd from being
517 	 * watched while keeping the same source around.  In the normal case you
518 	 * will just want to destroy the source.
519 	 *
520 	 * This API is only intended to be used by implementations of #GSource.
521 	 * Do not call this API on a #GSource that you did not create.
522 	 *
523 	 * As the name suggests, this function is not available on Windows.
524 	 *
525 	 * Params:
526 	 *     tag = the tag from g_source_add_unix_fd()
527 	 *
528 	 * Since: 2.36
529 	 */
530 	public void removeUnixFd(void* tag)
531 	{
532 		g_source_remove_unix_fd(gSource, tag);
533 	}
534 
535 	/**
536 	 * Sets the callback function for a source. The callback for a source is
537 	 * called from the source's dispatch function.
538 	 *
539 	 * The exact type of @func depends on the type of source; ie. you
540 	 * should not count on @func being called with @data as its first
541 	 * parameter. Cast @func with G_SOURCE_FUNC() to avoid warnings about
542 	 * incompatible function types.
543 	 *
544 	 * See [memory management of sources][mainloop-memory-management] for details
545 	 * on how to handle memory management of @data.
546 	 *
547 	 * Typically, you won't use this function. Instead use functions specific
548 	 * to the type of source you are using, such as g_idle_add() or g_timeout_add().
549 	 *
550 	 * It is safe to call this function multiple times on a source which has already
551 	 * been attached to a context. The changes will take effect for the next time
552 	 * the source is dispatched after this call returns.
553 	 *
554 	 * Params:
555 	 *     func = a callback function
556 	 *     data = the data to pass to callback function
557 	 *     notify = a function to call when @data is no longer in use, or %NULL.
558 	 */
559 	public void setCallback(GSourceFunc func, void* data, GDestroyNotify notify)
560 	{
561 		g_source_set_callback(gSource, func, data, notify);
562 	}
563 
564 	/**
565 	 * Sets the callback function storing the data as a refcounted callback
566 	 * "object". This is used internally. Note that calling
567 	 * g_source_set_callback_indirect() assumes
568 	 * an initial reference count on @callback_data, and thus
569 	 * @callback_funcs->unref will eventually be called once more
570 	 * than @callback_funcs->ref.
571 	 *
572 	 * It is safe to call this function multiple times on a source which has already
573 	 * been attached to a context. The changes will take effect for the next time
574 	 * the source is dispatched after this call returns.
575 	 *
576 	 * Params:
577 	 *     callbackData = pointer to callback data "object"
578 	 *     callbackFuncs = functions for reference counting @callback_data
579 	 *         and getting the callback and data
580 	 */
581 	public void setCallbackIndirect(void* callbackData, GSourceCallbackFuncs* callbackFuncs)
582 	{
583 		g_source_set_callback_indirect(gSource, callbackData, callbackFuncs);
584 	}
585 
586 	/**
587 	 * Sets whether a source can be called recursively. If @can_recurse is
588 	 * %TRUE, then while the source is being dispatched then this source
589 	 * will be processed normally. Otherwise, all processing of this
590 	 * source is blocked until the dispatch function returns.
591 	 *
592 	 * Params:
593 	 *     canRecurse = whether recursion is allowed for this source
594 	 */
595 	public void setCanRecurse(bool canRecurse)
596 	{
597 		g_source_set_can_recurse(gSource, canRecurse);
598 	}
599 
600 	/**
601 	 * Sets the source functions (can be used to override
602 	 * default implementations) of an unattached source.
603 	 *
604 	 * Params:
605 	 *     funcs = the new #GSourceFuncs
606 	 *
607 	 * Since: 2.12
608 	 */
609 	public void setFuncs(GSourceFuncs* funcs)
610 	{
611 		g_source_set_funcs(gSource, funcs);
612 	}
613 
614 	/**
615 	 * Sets a name for the source, used in debugging and profiling.
616 	 * The name defaults to #NULL.
617 	 *
618 	 * The source name should describe in a human-readable way
619 	 * what the source does. For example, "X11 event queue"
620 	 * or "GTK+ repaint idle handler" or whatever it is.
621 	 *
622 	 * It is permitted to call this function multiple times, but is not
623 	 * recommended due to the potential performance impact.  For example,
624 	 * one could change the name in the "check" function of a #GSourceFuncs
625 	 * to include details like the event type in the source name.
626 	 *
627 	 * Use caution if changing the name while another thread may be
628 	 * accessing it with g_source_get_name(); that function does not copy
629 	 * the value, and changing the value will free it while the other thread
630 	 * may be attempting to use it.
631 	 *
632 	 * Params:
633 	 *     name = debug name for the source
634 	 *
635 	 * Since: 2.26
636 	 */
637 	public void setName(string name)
638 	{
639 		g_source_set_name(gSource, Str.toStringz(name));
640 	}
641 
642 	/**
643 	 * Sets the priority of a source. While the main loop is being run, a
644 	 * source will be dispatched if it is ready to be dispatched and no
645 	 * sources at a higher (numerically smaller) priority are ready to be
646 	 * dispatched.
647 	 *
648 	 * A child source always has the same priority as its parent.  It is not
649 	 * permitted to change the priority of a source once it has been added
650 	 * as a child of another source.
651 	 *
652 	 * Params:
653 	 *     priority = the new priority.
654 	 */
655 	public void setPriority(int priority)
656 	{
657 		g_source_set_priority(gSource, priority);
658 	}
659 
660 	/**
661 	 * Sets a #GSource to be dispatched when the given monotonic time is
662 	 * reached (or passed).  If the monotonic time is in the past (as it
663 	 * always will be if @ready_time is 0) then the source will be
664 	 * dispatched immediately.
665 	 *
666 	 * If @ready_time is -1 then the source is never woken up on the basis
667 	 * of the passage of time.
668 	 *
669 	 * Dispatching the source does not reset the ready time.  You should do
670 	 * so yourself, from the source dispatch function.
671 	 *
672 	 * Note that if you have a pair of sources where the ready time of one
673 	 * suggests that it will be delivered first but the priority for the
674 	 * other suggests that it would be delivered first, and the ready time
675 	 * for both sources is reached during the same main context iteration,
676 	 * then the order of dispatch is undefined.
677 	 *
678 	 * It is a no-op to call this function on a #GSource which has already been
679 	 * destroyed with g_source_destroy().
680 	 *
681 	 * This API is only intended to be used by implementations of #GSource.
682 	 * Do not call this API on a #GSource that you did not create.
683 	 *
684 	 * Params:
685 	 *     readyTime = the monotonic time at which the source will be ready,
686 	 *         0 for "immediately", -1 for "never"
687 	 *
688 	 * Since: 2.36
689 	 */
690 	public void setReadyTime(long readyTime)
691 	{
692 		g_source_set_ready_time(gSource, readyTime);
693 	}
694 
695 	/**
696 	 * Decreases the reference count of a source by one. If the
697 	 * resulting reference count is zero the source and associated
698 	 * memory will be destroyed.
699 	 */
700 	public void unref()
701 	{
702 		g_source_unref(gSource);
703 	}
704 
705 	/**
706 	 * Removes the source with the given ID from the default main context. You must
707 	 * use g_source_destroy() for sources added to a non-default main context.
708 	 *
709 	 * The ID of a #GSource is given by g_source_get_id(), or will be
710 	 * returned by the functions g_source_attach(), g_idle_add(),
711 	 * g_idle_add_full(), g_timeout_add(), g_timeout_add_full(),
712 	 * g_child_watch_add(), g_child_watch_add_full(), g_io_add_watch(), and
713 	 * g_io_add_watch_full().
714 	 *
715 	 * It is a programmer error to attempt to remove a non-existent source.
716 	 *
717 	 * More specifically: source IDs can be reissued after a source has been
718 	 * destroyed and therefore it is never valid to use this function with a
719 	 * source ID which may have already been removed.  An example is when
720 	 * scheduling an idle to run in another thread with g_idle_add(): the
721 	 * idle may already have run and been removed by the time this function
722 	 * is called on its (now invalid) source ID.  This source ID may have
723 	 * been reissued, leading to the operation being performed against the
724 	 * wrong source.
725 	 *
726 	 * Params:
727 	 *     tag = the ID of the source to remove.
728 	 *
729 	 * Returns: For historical reasons, this function always returns %TRUE
730 	 */
731 	public static bool remove(uint tag)
732 	{
733 		return g_source_remove(tag) != 0;
734 	}
735 
736 	/**
737 	 * Removes a source from the default main loop context given the
738 	 * source functions and user data. If multiple sources exist with the
739 	 * same source functions and user data, only one will be destroyed.
740 	 *
741 	 * Params:
742 	 *     funcs = The @source_funcs passed to g_source_new()
743 	 *     userData = the user data for the callback
744 	 *
745 	 * Returns: %TRUE if a source was found and removed.
746 	 */
747 	public static bool removeByFuncsUserData(GSourceFuncs* funcs, void* userData)
748 	{
749 		return g_source_remove_by_funcs_user_data(funcs, userData) != 0;
750 	}
751 
752 	/**
753 	 * Removes a source from the default main loop context given the user
754 	 * data for the callback. If multiple sources exist with the same user
755 	 * data, only one will be destroyed.
756 	 *
757 	 * Params:
758 	 *     userData = the user_data for the callback.
759 	 *
760 	 * Returns: %TRUE if a source was found and removed.
761 	 */
762 	public static bool removeByUserData(void* userData)
763 	{
764 		return g_source_remove_by_user_data(userData) != 0;
765 	}
766 
767 	/**
768 	 * Sets the name of a source using its ID.
769 	 *
770 	 * This is a convenience utility to set source names from the return
771 	 * value of g_idle_add(), g_timeout_add(), etc.
772 	 *
773 	 * It is a programmer error to attempt to set the name of a non-existent
774 	 * source.
775 	 *
776 	 * More specifically: source IDs can be reissued after a source has been
777 	 * destroyed and therefore it is never valid to use this function with a
778 	 * source ID which may have already been removed.  An example is when
779 	 * scheduling an idle to run in another thread with g_idle_add(): the
780 	 * idle may already have run and been removed by the time this function
781 	 * is called on its (now invalid) source ID.  This source ID may have
782 	 * been reissued, leading to the operation being performed against the
783 	 * wrong source.
784 	 *
785 	 * Params:
786 	 *     tag = a #GSource ID
787 	 *     name = debug name for the source
788 	 *
789 	 * Since: 2.26
790 	 */
791 	public static void setNameById(uint tag, string name)
792 	{
793 		g_source_set_name_by_id(tag, Str.toStringz(name));
794 	}
795 }