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

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

Initial release

File size: 8.8 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.MainLoop;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.ConstructionException;
26private import glib.MainContext;
27private import glib.Source;
28
29
30/**
31 * The `GMainLoop` struct is an opaque data type
32 * representing the main event loop of a GLib or GTK+ application.
33 */
34public class MainLoop
35{
36        /** the main Gtk struct */
37        protected GMainLoop* gMainLoop;
38        protected bool ownedRef;
39
40        /** Get the main Gtk struct */
41        public GMainLoop* getMainLoopStruct()
42        {
43                return gMainLoop;
44        }
45
46        /** the main Gtk struct as a void* */
47        protected void* getStruct()
48        {
49                return cast(void*)gMainLoop;
50        }
51
52        /**
53         * Sets our main struct and passes it to the parent class.
54         */
55        public this (GMainLoop* gMainLoop, bool ownedRef = false)
56        {
57                this.gMainLoop = gMainLoop;
58                this.ownedRef = ownedRef;
59        }
60
61
62        /**
63         * Creates a new #GMainLoop structure.
64         *
65         * Params:
66         *     context = a #GMainContext  (if %NULL, the default context will be used).
67         *     isRunning = set to %TRUE to indicate that the loop is running. This
68         *         is not very important since calling g_main_loop_run() will set this to
69         *         %TRUE anyway.
70         *
71         * Returns: a new #GMainLoop.
72         *
73         * Throws: ConstructionException GTK+ fails to create the object.
74         */
75        public this(MainContext context, bool isRunning)
76        {
77                auto p = g_main_loop_new((context is null) ? null : context.getMainContextStruct(), isRunning);
78               
79                if(p is null)
80                {
81                        throw new ConstructionException("null returned by new");
82                }
83               
84                this(cast(GMainLoop*) p);
85        }
86
87        /**
88         * Returns the #GMainContext of @loop.
89         *
90         * Returns: the #GMainContext of @loop
91         */
92        public MainContext getContext()
93        {
94                auto p = g_main_loop_get_context(gMainLoop);
95               
96                if(p is null)
97                {
98                        return null;
99                }
100               
101                return new MainContext(cast(GMainContext*) p);
102        }
103
104        /**
105         * Checks to see if the main loop is currently being run via g_main_loop_run().
106         *
107         * Returns: %TRUE if the mainloop is currently being run.
108         */
109        public bool isRunning()
110        {
111                return g_main_loop_is_running(gMainLoop) != 0;
112        }
113
114        /**
115         * Stops a #GMainLoop from running. Any calls to g_main_loop_run()
116         * for the loop will return.
117         *
118         * Note that sources that have already been dispatched when
119         * g_main_loop_quit() is called will still be executed.
120         */
121        public void quit()
122        {
123                g_main_loop_quit(gMainLoop);
124        }
125
126        /**
127         * Increases the reference count on a #GMainLoop object by one.
128         *
129         * Returns: @loop
130         */
131        public MainLoop doref()
132        {
133                auto p = g_main_loop_ref(gMainLoop);
134               
135                if(p is null)
136                {
137                        return null;
138                }
139               
140                return new MainLoop(cast(GMainLoop*) p, true);
141        }
142
143        /**
144         * Runs a main loop until g_main_loop_quit() is called on the loop.
145         * If this is called for the thread of the loop's #GMainContext,
146         * it will process events from the loop, otherwise it will
147         * simply wait.
148         */
149        public void run()
150        {
151                g_main_loop_run(gMainLoop);
152        }
153
154        /**
155         * Decreases the reference count on a #GMainLoop object by one. If
156         * the result is zero, free the loop and free all associated memory.
157         */
158        public void unref()
159        {
160                g_main_loop_unref(gMainLoop);
161        }
162
163        /**
164         * Returns the currently firing source for this thread.
165         *
166         * Returns: The currently firing source or %NULL.
167         *
168         * Since: 2.12
169         */
170        public static Source mainCurrentSource()
171        {
172                auto p = g_main_current_source();
173               
174                if(p is null)
175                {
176                        return null;
177                }
178               
179                return new Source(cast(GSource*) p);
180        }
181
182        /**
183         * Returns the depth of the stack of calls to
184         * g_main_context_dispatch() on any #GMainContext in the current thread.
185         * That is, when called from the toplevel, it gives 0. When
186         * called from within a callback from g_main_context_iteration()
187         * (or g_main_loop_run(), etc.) it returns 1. When called from within
188         * a callback to a recursive call to g_main_context_iteration(),
189         * it returns 2. And so forth.
190         *
191         * This function is useful in a situation like the following:
192         * Imagine an extremely simple "garbage collected" system.
193         *
194         * |[<!-- language="C" -->
195         * static GList *free_list;
196         *
197         * gpointer
198         * allocate_memory (gsize size)
199         * {
200         * gpointer result = g_malloc (size);
201         * free_list = g_list_prepend (free_list, result);
202         * return result;
203         * }
204         *
205         * void
206         * free_allocated_memory (void)
207         * {
208         * GList *l;
209         * for (l = free_list; l; l = l->next);
210         * g_free (l->data);
211         * g_list_free (free_list);
212         * free_list = NULL;
213         * }
214         *
215         * [...]
216         *
217         * while (TRUE);
218         * {
219         * g_main_context_iteration (NULL, TRUE);
220         * free_allocated_memory();
221         * }
222         * ]|
223         *
224         * This works from an application, however, if you want to do the same
225         * thing from a library, it gets more difficult, since you no longer
226         * control the main loop. You might think you can simply use an idle
227         * function to make the call to free_allocated_memory(), but that
228         * doesn't work, since the idle function could be called from a
229         * recursive callback. This can be fixed by using g_main_depth()
230         *
231         * |[<!-- language="C" -->
232         * gpointer
233         * allocate_memory (gsize size)
234         * {
235         * FreeListBlock *block = g_new (FreeListBlock, 1);
236         * block->mem = g_malloc (size);
237         * block->depth = g_main_depth ();
238         * free_list = g_list_prepend (free_list, block);
239         * return block->mem;
240         * }
241         *
242         * void
243         * free_allocated_memory (void)
244         * {
245         * GList *l;
246         *
247         * int depth = g_main_depth ();
248         * for (l = free_list; l; );
249         * {
250         * GList *next = l->next;
251         * FreeListBlock *block = l->data;
252         * if (block->depth > depth)
253         * {
254         * g_free (block->mem);
255         * g_free (block);
256         * free_list = g_list_delete_link (free_list, l);
257         * }
258         *
259         * l = next;
260         * }
261         * }
262         * ]|
263         *
264         * There is a temptation to use g_main_depth() to solve
265         * problems with reentrancy. For instance, while waiting for data
266         * to be received from the network in response to a menu item,
267         * the menu item might be selected again. It might seem that
268         * one could make the menu item's callback return immediately
269         * and do nothing if g_main_depth() returns a value greater than 1.
270         * However, this should be avoided since the user then sees selecting
271         * the menu item do nothing. Furthermore, you'll find yourself adding
272         * these checks all over your code, since there are doubtless many,
273         * many things that the user could do. Instead, you can use the
274         * following techniques:
275         *
276         * 1. Use gtk_widget_set_sensitive() or modal dialogs to prevent
277         * the user from interacting with elements while the main
278         * loop is recursing.
279         *
280         * 2. Avoid main loop recursion in situations where you can't handle
281         * arbitrary  callbacks. Instead, structure your code so that you
282         * simply return to the main loop and then get called again when
283         * there is more work to do.
284         *
285         * Returns: The main loop recursion level in the current thread
286         */
287        public static int mainDepth()
288        {
289                return g_main_depth();
290        }
291
292        /**
293         * Polls @fds, as with the poll() system call, but portably. (On
294         * systems that don't have poll(), it is emulated using select().)
295         * This is used internally by #GMainContext, but it can be called
296         * directly if you need to block until a file descriptor is ready, but
297         * don't want to run the full main loop.
298         *
299         * Each element of @fds is a #GPollFD describing a single file
300         * descriptor to poll. The %fd field indicates the file descriptor,
301         * and the %events field indicates the events to poll for. On return,
302         * the %revents fields will be filled with the events that actually
303         * occurred.
304         *
305         * On POSIX systems, the file descriptors in @fds can be any sort of
306         * file descriptor, but the situation is much more complicated on
307         * Windows. If you need to use g_poll() in code that has to run on
308         * Windows, the easiest solution is to construct all of your
309         * #GPollFDs with g_io_channel_win32_make_pollfd().
310         *
311         * Params:
312         *     fds = file descriptors to poll
313         *     nfds = the number of file descriptors in @fds
314         *     timeout = amount of time to wait, in milliseconds, or -1 to wait forever
315         *
316         * Returns: the number of entries in @fds whose %revents fields
317         *     were filled in, or 0 if the operation timed out, or -1 on error or
318         *     if the call was interrupted.
319         *
320         * Since: 2.20
321         */
322        public static int poll(GPollFD* fds, uint nfds, int timeout)
323        {
324                return g_poll(fds, nfds, timeout);
325        }
326}
Note: See TracBrowser for help on using the repository browser.