source: appstream-generator/build/girepo/glib/Source.d @ 4841

Last change on this file since 4841 was 4841, checked in by Juanma, 2 years ago

Initial release

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