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