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

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

Initial release

File size: 10.1 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.Thread;
22
23private import gi.glib;
24public  import gi.glibtypes;
25private import glib.ConstructionException;
26private import glib.ErrorG;
27private import glib.GException;
28private import glib.Str;
29
30
31/**
32 * The #GThread struct represents a running thread. This struct
33 * is returned by g_thread_new() or g_thread_try_new(). You can
34 * obtain the #GThread struct representing the current thread by
35 * calling g_thread_self().
36 *
37 * GThread is refcounted, see g_thread_ref() and g_thread_unref().
38 * The thread represented by it holds a reference while it is running,
39 * and g_thread_join() consumes the reference that it is given, so
40 * it is normally not necessary to manage GThread references
41 * explicitly.
42 *
43 * The structure is opaque -- none of its fields may be directly
44 * accessed.
45 */
46public class Thread
47{
48        /** the main Gtk struct */
49        protected GThread* gThread;
50        protected bool ownedRef;
51
52        /** Get the main Gtk struct */
53        public GThread* getThreadStruct()
54        {
55                return gThread;
56        }
57
58        /** the main Gtk struct as a void* */
59        protected void* getStruct()
60        {
61                return cast(void*)gThread;
62        }
63
64        /**
65         * Sets our main struct and passes it to the parent class.
66         */
67        public this (GThread* gThread, bool ownedRef = false)
68        {
69                this.gThread = gThread;
70                this.ownedRef = ownedRef;
71        }
72
73
74        /**
75         * This function is the same as g_thread_new() except that
76         * it allows for the possibility of failure.
77         *
78         * If a thread can not be created (due to resource limits),
79         * @error is set and %NULL is returned.
80         *
81         * Params:
82         *     name = an (optional) name for the new thread
83         *     func = a function to execute in the new thread
84         *     data = an argument to supply to the new thread
85         *
86         * Returns: the new #GThread, or %NULL if an error occurred
87         *
88         * Since: 2.32
89         *
90         * Throws: GException on failure.
91         * Throws: ConstructionException GTK+ fails to create the object.
92         */
93        public this(string name, GThreadFunc func, void* data)
94        {
95                GError* err = null;
96               
97                auto p = g_thread_try_new(Str.toStringz(name), func, data, &err);
98               
99                if (err !is null)
100                {
101                        throw new GException( new ErrorG(err) );
102                }
103               
104                if(p is null)
105                {
106                        throw new ConstructionException("null returned by try_new");
107                }
108               
109                this(cast(GThread*) p);
110        }
111
112        /**
113         * Waits until @thread finishes, i.e. the function @func, as
114         * given to g_thread_new(), returns or g_thread_exit() is called.
115         * If @thread has already terminated, then g_thread_join()
116         * returns immediately.
117         *
118         * Any thread can wait for any other thread by calling g_thread_join(),
119         * not just its 'creator'. Calling g_thread_join() from multiple threads
120         * for the same @thread leads to undefined behaviour.
121         *
122         * The value returned by @func or given to g_thread_exit() is
123         * returned by this function.
124         *
125         * g_thread_join() consumes the reference to the passed-in @thread.
126         * This will usually cause the #GThread struct and associated resources
127         * to be freed. Use g_thread_ref() to obtain an extra reference if you
128         * want to keep the GThread alive beyond the g_thread_join() call.
129         *
130         * Returns: the return value of the thread
131         */
132        public void* join()
133        {
134                return g_thread_join(gThread);
135        }
136
137        /**
138         * Increase the reference count on @thread.
139         *
140         * Returns: a new reference to @thread
141         *
142         * Since: 2.32
143         */
144        public Thread doref()
145        {
146                auto p = g_thread_ref(gThread);
147               
148                if(p is null)
149                {
150                        return null;
151                }
152               
153                return new Thread(cast(GThread*) p, true);
154        }
155
156        /**
157         * Decrease the reference count on @thread, possibly freeing all
158         * resources associated with it.
159         *
160         * Note that each thread holds a reference to its #GThread while
161         * it is running, so it is safe to drop your own reference to it
162         * if you don't need it anymore.
163         *
164         * Since: 2.32
165         */
166        public void unref()
167        {
168                g_thread_unref(gThread);
169        }
170
171        /** */
172        public static GQuark errorQuark()
173        {
174                return g_thread_error_quark();
175        }
176
177        /**
178         * Terminates the current thread.
179         *
180         * If another thread is waiting for us using g_thread_join() then the
181         * waiting thread will be woken up and get @retval as the return value
182         * of g_thread_join().
183         *
184         * Calling g_thread_exit() with a parameter @retval is equivalent to
185         * returning @retval from the function @func, as given to g_thread_new().
186         *
187         * You must only call g_thread_exit() from a thread that you created
188         * yourself with g_thread_new() or related APIs. You must not call
189         * this function from a thread created with another threading library
190         * or or from within a #GThreadPool.
191         *
192         * Params:
193         *     retval = the return value of this thread
194         */
195        public static void exit(void* retval)
196        {
197                g_thread_exit(retval);
198        }
199
200        /**
201         * This function returns the #GThread corresponding to the
202         * current thread. Note that this function does not increase
203         * the reference count of the returned struct.
204         *
205         * This function will return a #GThread even for threads that
206         * were not created by GLib (i.e. those created by other threading
207         * APIs). This may be useful for thread identification purposes
208         * (i.e. comparisons) but you must not use GLib functions (such
209         * as g_thread_join()) on these threads.
210         *
211         * Returns: the #GThread representing the current thread
212         */
213        public static Thread self()
214        {
215                auto p = g_thread_self();
216               
217                if(p is null)
218                {
219                        return null;
220                }
221               
222                return new Thread(cast(GThread*) p, true);
223        }
224
225        /**
226         * Causes the calling thread to voluntarily relinquish the CPU, so
227         * that other threads can run.
228         *
229         * This function is often used as a method to make busy wait less evil.
230         */
231        public static void yield()
232        {
233                g_thread_yield();
234        }
235
236        /**
237         * Sets the indicated @lock_bit in @address.  If the bit is already
238         * set, this call will block until g_bit_unlock() unsets the
239         * corresponding bit.
240         *
241         * Attempting to lock on two different bits within the same integer is
242         * not supported and will very probably cause deadlocks.
243         *
244         * The value of the bit that is set is (1u << @bit).  If @bit is not
245         * between 0 and 31 then the result is undefined.
246         *
247         * This function accesses @address atomically.  All other accesses to
248         * @address must be atomic in order for this function to work
249         * reliably.
250         *
251         * Params:
252         *     address = a pointer to an integer
253         *     lockBit = a bit value between 0 and 31
254         *
255         * Since: 2.24
256         */
257        public static void bitLock(int* address, int lockBit)
258        {
259                g_bit_lock(address, lockBit);
260        }
261
262        /**
263         * Sets the indicated @lock_bit in @address, returning %TRUE if
264         * successful.  If the bit is already set, returns %FALSE immediately.
265         *
266         * Attempting to lock on two different bits within the same integer is
267         * not supported.
268         *
269         * The value of the bit that is set is (1u << @bit).  If @bit is not
270         * between 0 and 31 then the result is undefined.
271         *
272         * This function accesses @address atomically.  All other accesses to
273         * @address must be atomic in order for this function to work
274         * reliably.
275         *
276         * Params:
277         *     address = a pointer to an integer
278         *     lockBit = a bit value between 0 and 31
279         *
280         * Returns: %TRUE if the lock was acquired
281         *
282         * Since: 2.24
283         */
284        public static bool bitTrylock(int* address, int lockBit)
285        {
286                return g_bit_trylock(address, lockBit) != 0;
287        }
288
289        /**
290         * Clears the indicated @lock_bit in @address.  If another thread is
291         * currently blocked in g_bit_lock() on this same bit then it will be
292         * woken up.
293         *
294         * This function accesses @address atomically.  All other accesses to
295         * @address must be atomic in order for this function to work
296         * reliably.
297         *
298         * Params:
299         *     address = a pointer to an integer
300         *     lockBit = a bit value between 0 and 31
301         *
302         * Since: 2.24
303         */
304        public static void bitUnlock(int* address, int lockBit)
305        {
306                g_bit_unlock(address, lockBit);
307        }
308
309        /**
310         * Determine the approximate number of threads that the system will
311         * schedule simultaneously for this process.  This is intended to be
312         * used as a parameter to g_thread_pool_new() for CPU bound tasks and
313         * similar cases.
314         *
315         * Returns: Number of schedulable threads, always greater than 0
316         *
317         * Since: 2.36
318         */
319        public static uint getNumProcessors()
320        {
321                return g_get_num_processors();
322        }
323
324        /**
325         * This is equivalent to g_bit_lock, but working on pointers (or other
326         * pointer-sized values).
327         *
328         * For portability reasons, you may only lock on the bottom 32 bits of
329         * the pointer.
330         *
331         * Params:
332         *     address = a pointer to a #gpointer-sized value
333         *     lockBit = a bit value between 0 and 31
334         *
335         * Since: 2.30
336         */
337        public static void pointerBitLock(void* address, int lockBit)
338        {
339                g_pointer_bit_lock(address, lockBit);
340        }
341
342        /**
343         * This is equivalent to g_bit_trylock, but working on pointers (or
344         * other pointer-sized values).
345         *
346         * For portability reasons, you may only lock on the bottom 32 bits of
347         * the pointer.
348         *
349         * Params:
350         *     address = a pointer to a #gpointer-sized value
351         *     lockBit = a bit value between 0 and 31
352         *
353         * Returns: %TRUE if the lock was acquired
354         *
355         * Since: 2.30
356         */
357        public static bool pointerBitTrylock(void* address, int lockBit)
358        {
359                return g_pointer_bit_trylock(address, lockBit) != 0;
360        }
361
362        /**
363         * This is equivalent to g_bit_unlock, but working on pointers (or other
364         * pointer-sized values).
365         *
366         * For portability reasons, you may only lock on the bottom 32 bits of
367         * the pointer.
368         *
369         * Params:
370         *     address = a pointer to a #gpointer-sized value
371         *     lockBit = a bit value between 0 and 31
372         *
373         * Since: 2.30
374         */
375        public static void pointerBitUnlock(void* address, int lockBit)
376        {
377                g_pointer_bit_unlock(address, lockBit);
378        }
379}
Note: See TracBrowser for help on using the repository browser.