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

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

Initial release

File size: 18.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.MainContext;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.Cond;
26private import glib.ConstructionException;
27private import glib.Mutex;
28private import glib.Source;
29
30
31/**
32 * The `GMainContext` struct is an opaque data
33 * type representing a set of sources to be handled in a main loop.
34 */
35public class MainContext
36{
37        /** the main Gtk struct */
38        protected GMainContext* gMainContext;
39        protected bool ownedRef;
40
41        /** Get the main Gtk struct */
42        public GMainContext* getMainContextStruct()
43        {
44                return gMainContext;
45        }
46
47        /** the main Gtk struct as a void* */
48        protected void* getStruct()
49        {
50                return cast(void*)gMainContext;
51        }
52
53        /**
54         * Sets our main struct and passes it to the parent class.
55         */
56        public this (GMainContext* gMainContext, bool ownedRef = false)
57        {
58                this.gMainContext = gMainContext;
59                this.ownedRef = ownedRef;
60        }
61
62
63        /**
64         * Creates a new #GMainContext structure.
65         *
66         * Returns: the new #GMainContext
67         *
68         * Throws: ConstructionException GTK+ fails to create the object.
69         */
70        public this()
71        {
72                auto p = g_main_context_new();
73               
74                if(p is null)
75                {
76                        throw new ConstructionException("null returned by new");
77                }
78               
79                this(cast(GMainContext*) p);
80        }
81
82        /**
83         * Tries to become the owner of the specified context.
84         * If some other thread is the owner of the context,
85         * returns %FALSE immediately. Ownership is properly
86         * recursive: the owner can require ownership again
87         * and will release ownership when g_main_context_release()
88         * is called as many times as g_main_context_acquire().
89         *
90         * You must be the owner of a context before you
91         * can call g_main_context_prepare(), g_main_context_query(),
92         * g_main_context_check(), g_main_context_dispatch().
93         *
94         * Returns: %TRUE if the operation succeeded, and
95         *     this thread is now the owner of @context.
96         */
97        public bool acquire()
98        {
99                return g_main_context_acquire(gMainContext) != 0;
100        }
101
102        /**
103         * Adds a file descriptor to the set of file descriptors polled for
104         * this context. This will very seldom be used directly. Instead
105         * a typical event source will use g_source_add_unix_fd() instead.
106         *
107         * Params:
108         *     fd = a #GPollFD structure holding information about a file
109         *         descriptor to watch.
110         *     priority = the priority for this file descriptor which should be
111         *         the same as the priority used for g_source_attach() to ensure that the
112         *         file descriptor is polled whenever the results may be needed.
113         */
114        public void addPoll(GPollFD* fd, int priority)
115        {
116                g_main_context_add_poll(gMainContext, fd, priority);
117        }
118
119        /**
120         * Passes the results of polling back to the main loop.
121         *
122         * You must have successfully acquired the context with
123         * g_main_context_acquire() before you may call this function.
124         *
125         * Params:
126         *     maxPriority = the maximum numerical priority of sources to check
127         *     fds = array of #GPollFD's that was passed to
128         *         the last call to g_main_context_query()
129         *     nFds = return value of g_main_context_query()
130         *
131         * Returns: %TRUE if some sources are ready to be dispatched.
132         */
133        public int check(int maxPriority, GPollFD[] fds)
134        {
135                return g_main_context_check(gMainContext, maxPriority, fds.ptr, cast(int)fds.length);
136        }
137
138        /**
139         * Dispatches all pending sources.
140         *
141         * You must have successfully acquired the context with
142         * g_main_context_acquire() before you may call this function.
143         */
144        public void dispatch()
145        {
146                g_main_context_dispatch(gMainContext);
147        }
148
149        /**
150         * Finds a source with the given source functions and user data.  If
151         * multiple sources exist with the same source function and user data,
152         * the first one found will be returned.
153         *
154         * Params:
155         *     funcs = the @source_funcs passed to g_source_new().
156         *     userData = the user data from the callback.
157         *
158         * Returns: the source, if one was found, otherwise %NULL
159         */
160        public Source findSourceByFuncsUserData(GSourceFuncs* funcs, void* userData)
161        {
162                auto p = g_main_context_find_source_by_funcs_user_data(gMainContext, funcs, userData);
163               
164                if(p is null)
165                {
166                        return null;
167                }
168               
169                return new Source(cast(GSource*) p);
170        }
171
172        /**
173         * Finds a #GSource given a pair of context and ID.
174         *
175         * It is a programmer error to attempt to lookup a non-existent source.
176         *
177         * More specifically: source IDs can be reissued after a source has been
178         * destroyed and therefore it is never valid to use this function with a
179         * source ID which may have already been removed.  An example is when
180         * scheduling an idle to run in another thread with g_idle_add(): the
181         * idle may already have run and been removed by the time this function
182         * is called on its (now invalid) source ID.  This source ID may have
183         * been reissued, leading to the operation being performed against the
184         * wrong source.
185         *
186         * Params:
187         *     sourceId = the source ID, as returned by g_source_get_id().
188         *
189         * Returns: the #GSource
190         */
191        public Source findSourceById(uint sourceId)
192        {
193                auto p = g_main_context_find_source_by_id(gMainContext, sourceId);
194               
195                if(p is null)
196                {
197                        return null;
198                }
199               
200                return new Source(cast(GSource*) p);
201        }
202
203        /**
204         * Finds a source with the given user data for the callback.  If
205         * multiple sources exist with the same user data, the first
206         * one found will be returned.
207         *
208         * Params:
209         *     userData = the user_data for the callback.
210         *
211         * Returns: the source, if one was found, otherwise %NULL
212         */
213        public Source findSourceByUserData(void* userData)
214        {
215                auto p = g_main_context_find_source_by_user_data(gMainContext, userData);
216               
217                if(p is null)
218                {
219                        return null;
220                }
221               
222                return new Source(cast(GSource*) p);
223        }
224
225        /**
226         * Gets the poll function set by g_main_context_set_poll_func().
227         *
228         * Returns: the poll function
229         */
230        public GPollFunc getPollFunc()
231        {
232                return g_main_context_get_poll_func(gMainContext);
233        }
234
235        /**
236         * Invokes a function in such a way that @context is owned during the
237         * invocation of @function.
238         *
239         * If @context is %NULL then the global default main context — as
240         * returned by g_main_context_default() — is used.
241         *
242         * If @context is owned by the current thread, @function is called
243         * directly.  Otherwise, if @context is the thread-default main context
244         * of the current thread and g_main_context_acquire() succeeds, then
245         * @function is called and g_main_context_release() is called
246         * afterwards.
247         *
248         * In any other case, an idle source is created to call @function and
249         * that source is attached to @context (presumably to be run in another
250         * thread).  The idle source is attached with #G_PRIORITY_DEFAULT
251         * priority.  If you want a different priority, use
252         * g_main_context_invoke_full().
253         *
254         * Note that, as with normal idle functions, @function should probably
255         * return %FALSE.  If it returns %TRUE, it will be continuously run in a
256         * loop (and may prevent this call from returning).
257         *
258         * Params:
259         *     funct = function to call
260         *     data = data to pass to @function
261         *
262         * Since: 2.28
263         */
264        public void invoke(GSourceFunc funct, void* data)
265        {
266                g_main_context_invoke(gMainContext, funct, data);
267        }
268
269        /**
270         * Invokes a function in such a way that @context is owned during the
271         * invocation of @function.
272         *
273         * This function is the same as g_main_context_invoke() except that it
274         * lets you specify the priority incase @function ends up being
275         * scheduled as an idle and also lets you give a #GDestroyNotify for @data.
276         *
277         * @notify should not assume that it is called from any particular
278         * thread or with any particular context acquired.
279         *
280         * Params:
281         *     priority = the priority at which to run @function
282         *     funct = function to call
283         *     data = data to pass to @function
284         *     notify = a function to call when @data is no longer in use, or %NULL.
285         *
286         * Since: 2.28
287         */
288        public void invokeFull(int priority, GSourceFunc funct, void* data, GDestroyNotify notify)
289        {
290                g_main_context_invoke_full(gMainContext, priority, funct, data, notify);
291        }
292
293        /**
294         * Determines whether this thread holds the (recursive)
295         * ownership of this #GMainContext. This is useful to
296         * know before waiting on another thread that may be
297         * blocking to get ownership of @context.
298         *
299         * Returns: %TRUE if current thread is owner of @context.
300         *
301         * Since: 2.10
302         */
303        public bool isOwner()
304        {
305                return g_main_context_is_owner(gMainContext) != 0;
306        }
307
308        /**
309         * Runs a single iteration for the given main loop. This involves
310         * checking to see if any event sources are ready to be processed,
311         * then if no events sources are ready and @may_block is %TRUE, waiting
312         * for a source to become ready, then dispatching the highest priority
313         * events sources that are ready. Otherwise, if @may_block is %FALSE
314         * sources are not waited to become ready, only those highest priority
315         * events sources will be dispatched (if any), that are ready at this
316         * given moment without further waiting.
317         *
318         * Note that even when @may_block is %TRUE, it is still possible for
319         * g_main_context_iteration() to return %FALSE, since the wait may
320         * be interrupted for other reasons than an event source becoming ready.
321         *
322         * Params:
323         *     mayBlock = whether the call may block.
324         *
325         * Returns: %TRUE if events were dispatched.
326         */
327        public bool iteration(bool mayBlock)
328        {
329                return g_main_context_iteration(gMainContext, mayBlock) != 0;
330        }
331
332        /**
333         * Checks if any sources have pending events for the given context.
334         *
335         * Returns: %TRUE if events are pending.
336         */
337        public bool pending()
338        {
339                return g_main_context_pending(gMainContext) != 0;
340        }
341
342        /**
343         * Pops @context off the thread-default context stack (verifying that
344         * it was on the top of the stack).
345         *
346         * Since: 2.22
347         */
348        public void popThreadDefault()
349        {
350                g_main_context_pop_thread_default(gMainContext);
351        }
352
353        /**
354         * Prepares to poll sources within a main loop. The resulting information
355         * for polling is determined by calling g_main_context_query ().
356         *
357         * You must have successfully acquired the context with
358         * g_main_context_acquire() before you may call this function.
359         *
360         * Params:
361         *     priority = location to store priority of highest priority
362         *         source already ready.
363         *
364         * Returns: %TRUE if some source is ready to be dispatched
365         *     prior to polling.
366         */
367        public bool prepare(int* priority)
368        {
369                return g_main_context_prepare(gMainContext, priority) != 0;
370        }
371
372        /**
373         * Acquires @context and sets it as the thread-default context for the
374         * current thread. This will cause certain asynchronous operations
375         * (such as most [gio][gio]-based I/O) which are
376         * started in this thread to run under @context and deliver their
377         * results to its main loop, rather than running under the global
378         * default context in the main thread. Note that calling this function
379         * changes the context returned by g_main_context_get_thread_default(),
380         * not the one returned by g_main_context_default(), so it does not affect
381         * the context used by functions like g_idle_add().
382         *
383         * Normally you would call this function shortly after creating a new
384         * thread, passing it a #GMainContext which will be run by a
385         * #GMainLoop in that thread, to set a new default context for all
386         * async operations in that thread. (In this case, you don't need to
387         * ever call g_main_context_pop_thread_default().) In some cases
388         * however, you may want to schedule a single operation in a
389         * non-default context, or temporarily use a non-default context in
390         * the main thread. In that case, you can wrap the call to the
391         * asynchronous operation inside a
392         * g_main_context_push_thread_default() /
393         * g_main_context_pop_thread_default() pair, but it is up to you to
394         * ensure that no other asynchronous operations accidentally get
395         * started while the non-default context is active.
396         *
397         * Beware that libraries that predate this function may not correctly
398         * handle being used from a thread with a thread-default context. Eg,
399         * see g_file_supports_thread_contexts().
400         *
401         * Since: 2.22
402         */
403        public void pushThreadDefault()
404        {
405                g_main_context_push_thread_default(gMainContext);
406        }
407
408        /**
409         * Determines information necessary to poll this main loop.
410         *
411         * You must have successfully acquired the context with
412         * g_main_context_acquire() before you may call this function.
413         *
414         * Params:
415         *     maxPriority = maximum priority source to check
416         *     timeout = location to store timeout to be used in polling
417         *     fds = location to
418         *         store #GPollFD records that need to be polled.
419         *     nFds = length of @fds.
420         *
421         * Returns: the number of records actually stored in @fds,
422         *     or, if more than @n_fds records need to be stored, the number
423         *     of records that need to be stored.
424         */
425        public int query(int maxPriority, out int timeout, GPollFD[] fds)
426        {
427                return g_main_context_query(gMainContext, maxPriority, &timeout, fds.ptr, cast(int)fds.length);
428        }
429
430        /**
431         * Increases the reference count on a #GMainContext object by one.
432         *
433         * Returns: the @context that was passed in (since 2.6)
434         */
435        public MainContext doref()
436        {
437                auto p = g_main_context_ref(gMainContext);
438               
439                if(p is null)
440                {
441                        return null;
442                }
443               
444                return new MainContext(cast(GMainContext*) p, true);
445        }
446
447        /**
448         * Releases ownership of a context previously acquired by this thread
449         * with g_main_context_acquire(). If the context was acquired multiple
450         * times, the ownership will be released only when g_main_context_release()
451         * is called as many times as it was acquired.
452         */
453        public void release()
454        {
455                g_main_context_release(gMainContext);
456        }
457
458        /**
459         * Removes file descriptor from the set of file descriptors to be
460         * polled for a particular context.
461         *
462         * Params:
463         *     fd = a #GPollFD descriptor previously added with g_main_context_add_poll()
464         */
465        public void removePoll(GPollFD* fd)
466        {
467                g_main_context_remove_poll(gMainContext, fd);
468        }
469
470        /**
471         * Sets the function to use to handle polling of file descriptors. It
472         * will be used instead of the poll() system call
473         * (or GLib's replacement function, which is used where
474         * poll() isn't available).
475         *
476         * This function could possibly be used to integrate the GLib event
477         * loop with an external event loop.
478         *
479         * Params:
480         *     func = the function to call to poll all file descriptors
481         */
482        public void setPollFunc(GPollFunc func)
483        {
484                g_main_context_set_poll_func(gMainContext, func);
485        }
486
487        /**
488         * Decreases the reference count on a #GMainContext object by one. If
489         * the result is zero, free the context and free all associated memory.
490         */
491        public void unref()
492        {
493                g_main_context_unref(gMainContext);
494        }
495
496        /**
497         * Tries to become the owner of the specified context,
498         * as with g_main_context_acquire(). But if another thread
499         * is the owner, atomically drop @mutex and wait on @cond until
500         * that owner releases ownership or until @cond is signaled, then
501         * try again (once) to become the owner.
502         *
503         * Params:
504         *     cond = a condition variable
505         *     mutex = a mutex, currently held
506         *
507         * Returns: %TRUE if the operation succeeded, and
508         *     this thread is now the owner of @context.
509         */
510        public bool wait(Cond cond, Mutex mutex)
511        {
512                return g_main_context_wait(gMainContext, (cond is null) ? null : cond.getCondStruct(), (mutex is null) ? null : mutex.getMutexStruct()) != 0;
513        }
514
515        /**
516         * If @context is currently blocking in g_main_context_iteration()
517         * waiting for a source to become ready, cause it to stop blocking
518         * and return.  Otherwise, cause the next invocation of
519         * g_main_context_iteration() to return without blocking.
520         *
521         * This API is useful for low-level control over #GMainContext; for
522         * example, integrating it with main loop implementations such as
523         * #GMainLoop.
524         *
525         * Another related use for this function is when implementing a main
526         * loop with a termination condition, computed from multiple threads:
527         *
528         * |[<!-- language="C" -->
529         * #define NUM_TASKS 10
530         * static volatile gint tasks_remaining = NUM_TASKS;
531         * ...
532         *
533         * while (g_atomic_int_get (&tasks_remaining) != 0)
534         * g_main_context_iteration (NULL, TRUE);
535         * ]|
536         *
537         * Then in a thread:
538         * |[<!-- language="C" -->
539         * perform_work();
540         *
541         * if (g_atomic_int_dec_and_test (&tasks_remaining))
542         * g_main_context_wakeup (NULL);
543         * ]|
544         */
545        public void wakeup()
546        {
547                g_main_context_wakeup(gMainContext);
548        }
549
550        /**
551         * Returns the global default main context. This is the main context
552         * used for main loop functions when a main loop is not explicitly
553         * specified, and corresponds to the "main" main loop. See also
554         * g_main_context_get_thread_default().
555         *
556         * Returns: the global default main context.
557         */
558        public static MainContext defaulx()
559        {
560                auto p = g_main_context_default();
561               
562                if(p is null)
563                {
564                        return null;
565                }
566               
567                return new MainContext(cast(GMainContext*) p);
568        }
569
570        /**
571         * Gets the thread-default #GMainContext for this thread. Asynchronous
572         * operations that want to be able to be run in contexts other than
573         * the default one should call this method or
574         * g_main_context_ref_thread_default() to get a #GMainContext to add
575         * their #GSources to. (Note that even in single-threaded
576         * programs applications may sometimes want to temporarily push a
577         * non-default context, so it is not safe to assume that this will
578         * always return %NULL if you are running in the default thread.)
579         *
580         * If you need to hold a reference on the context, use
581         * g_main_context_ref_thread_default() instead.
582         *
583         * Returns: the thread-default #GMainContext, or
584         *     %NULL if the thread-default context is the global default context.
585         *
586         * Since: 2.22
587         */
588        public static MainContext getThreadDefault()
589        {
590                auto p = g_main_context_get_thread_default();
591               
592                if(p is null)
593                {
594                        return null;
595                }
596               
597                return new MainContext(cast(GMainContext*) p);
598        }
599
600        /**
601         * Gets the thread-default #GMainContext for this thread, as with
602         * g_main_context_get_thread_default(), but also adds a reference to
603         * it with g_main_context_ref(). In addition, unlike
604         * g_main_context_get_thread_default(), if the thread-default context
605         * is the global default context, this will return that #GMainContext
606         * (with a ref added to it) rather than returning %NULL.
607         *
608         * Returns: the thread-default #GMainContext. Unref
609         *     with g_main_context_unref() when you are done with it.
610         *
611         * Since: 2.32
612         */
613        public static MainContext refThreadDefault()
614        {
615                auto p = g_main_context_ref_thread_default();
616               
617                if(p is null)
618                {
619                        return null;
620                }
621               
622                return new MainContext(cast(GMainContext*) p, true);
623        }
624}
Note: See TracBrowser for help on using the repository browser.