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