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  * Conversion parameters:
26  * inFile  = 
27  * outPack = gthread
28  * outFile = Mutex
29  * strct   = GMutex
30  * realStrct=
31  * ctorStrct=
32  * clss    = Mutex
33  * interf  = 
34  * class Code: No
35  * interface Code: No
36  * template for:
37  * extend  = 
38  * implements:
39  * prefixes:
40  * 	- g_mutex_
41  * omit structs:
42  * omit prefixes:
43  * omit code:
44  * omit signals:
45  * imports:
46  * structWrap:
47  * module aliases:
48  * local aliases:
49  * overrides:
50  */
51 
52 module gthread.Mutex;
53 
54 public  import gtkc.gthreadtypes;
55 
56 private import gtkc.gthread;
57 private import glib.ConstructionException;
58 
59 
60 
61 
62 
63 
64 /**
65  * Threads act almost like processes, but unlike processes all threads
66  * of one process share the same memory. This is good, as it provides
67  * easy communication between the involved threads via this shared
68  * memory, and it is bad, because strange things (so called
69  * "Heisenbugs") might happen if the program is not carefully designed.
70  * In particular, due to the concurrent nature of threads, no
71  * assumptions on the order of execution of code running in different
72  * threads can be made, unless order is explicitly forced by the
73  * programmer through synchronization primitives.
74  *
75  * The aim of the thread-related functions in GLib is to provide a
76  * portable means for writing multi-threaded software. There are
77  * primitives for mutexes to protect the access to portions of memory
78  * (GMutex, GRecMutex and GRWLock). There is a facility to use
79  * individual bits for locks (g_bit_lock()). There are primitives
80  * for condition variables to allow synchronization of threads (GCond).
81  * There are primitives for thread-private data - data that every
82  * thread has a private instance of (GPrivate). There are facilities
83  * for one-time initialization (GOnce, g_once_init_enter()). Finally,
84  * there are primitives to create and manage threads (GThread).
85  *
86  * The GLib threading system used to be initialized with g_thread_init().
87  * This is no longer necessary. Since version 2.32, the GLib threading
88  * system is automatically initialized at the start of your program,
89  * and all thread-creation functions and synchronization primitives
90  * are available right away.
91  *
92  * Note that it is not safe to assume that your program has no threads
93  * even if you don't call g_thread_new() yourself. GLib and GIO can
94  * and will create threads for their own purposes in some cases, such
95  * as when using g_unix_signal_source_new() or when using GDBus.
96  *
97  * Originally, UNIX did not have threads, and therefore some traditional
98  * UNIX APIs are problematic in threaded programs. Some notable examples
99  * are
100  *
101  *  C library functions that return data in statically allocated
102  *  buffers, such as strtok() or strerror(). For many of these,
103  *  there are thread-safe variants with a _r suffix, or you can
104  *  look at corresponding GLib APIs (like g_strsplit() or g_strerror()).
105  *
106  * setenv() and unsetenv() manipulate the process environment in
107  *  a not thread-safe way, and may interfere with getenv() calls
108  *  in other threads. Note that getenv() calls may be
109  *  “hidden” behind other APIs. For example, GNU gettext()
110  *  calls getenv() under the covers. In general, it is best to treat
111  *  the environment as readonly. If you absolutely have to modify the
112  *  environment, do it early in main(), when no other threads are around yet.
113  *
114  * setlocale() changes the locale for the entire process, affecting
115  *  all threads. Temporary changes to the locale are often made to
116  *  change the behavior of string scanning or formatting functions
117  *  like scanf() or printf(). GLib offers a number of string APIs
118  *  (like g_ascii_formatd() or g_ascii_strtod()) that can often be
119  *  used as an alternative. Or you can use the uselocale() function
120  *  to change the locale only for the current thread.
121  *
122  * fork() only takes the calling thread into the child's copy of the
123  *  process image. If other threads were executing in critical
124  *  sections they could have left mutexes locked which could easily
125  *  cause deadlocks in the new child. For this reason, you should
126  *  call exit() or exec() as soon as possible in the child and only
127  *  make signal-safe library calls before that.
128  *
129  * daemon() uses fork() in a way contrary to what is described
130  *  above. It should not be used with GLib programs.
131  *
132  * GLib itself is internally completely thread-safe (all global data is
133  * automatically locked), but individual data structure instances are
134  * not automatically locked for performance reasons. For example,
135  * you must coordinate accesses to the same GHashTable from multiple
136  * threads. The two notable exceptions from this rule are GMainLoop
137  * and GAsyncQueue, which are thread-safe and
138  * need no further application-level locking to be accessed from
139  * multiple threads. Most refcounting functions such as g_object_ref()
140  * are also thread-safe.
141  */
142 public class Mutex
143 {
144 	
145 	/** the main Gtk struct */
146 	protected GMutex* gMutex;
147 	
148 	
149 	public GMutex* getMutexStruct()
150 	{
151 		return gMutex;
152 	}
153 	
154 	
155 	/** the main Gtk struct as a void* */
156 	protected void* getStruct()
157 	{
158 		return cast(void*)gMutex;
159 	}
160 	
161 	/**
162 	 * Sets our main struct and passes it to the parent class
163 	 */
164 	public this (GMutex* gMutex)
165 	{
166 		this.gMutex = gMutex;
167 	}
168 	
169 	/**
170 	 */
171 	
172 	/**
173 	 * Initializes a GMutex so that it can be used.
174 	 * This function is useful to initialize a mutex that has been
175 	 * allocated on the stack, or as part of a larger structure.
176 	 * It is not necessary to initialize a mutex that has been
177 	 * statically allocated.
178 	 * $(DDOC_COMMENT example)
179 	 * To undo the effect of g_mutex_init() when a mutex is no longer
180 	 * needed, use g_mutex_clear().
181 	 * Calling g_mutex_init() on an already initialized GMutex leads
182 	 * to undefined behaviour.
183 	 * Since 2.32
184 	 */
185 	public void init()
186 	{
187 		// void g_mutex_init (GMutex *mutex);
188 		g_mutex_init(gMutex);
189 	}
190 	
191 	/**
192 	 * Frees the resources allocated to a mutex with g_mutex_init().
193 	 * This function should not be used with a GMutex that has been
194 	 * statically allocated.
195 	 * Calling g_mutex_clear() on a locked mutex leads to undefined
196 	 * behaviour.
197 	 * Sine: 2.32
198 	 */
199 	public void clear()
200 	{
201 		// void g_mutex_clear (GMutex *mutex);
202 		g_mutex_clear(gMutex);
203 	}
204 	
205 	/**
206 	 * Locks mutex. If mutex is already locked by another thread, the
207 	 * current thread will block until mutex is unlocked by the other
208 	 * thread.
209 	 * Note
210 	 * GMutex is neither guaranteed to be recursive nor to be
211 	 * non-recursive. As such, calling g_mutex_lock() on a GMutex that has
212 	 * already been locked by the same thread results in undefined behaviour
213 	 * (including but not limited to deadlocks).
214 	 */
215 	public void lock()
216 	{
217 		// void g_mutex_lock (GMutex *mutex);
218 		g_mutex_lock(gMutex);
219 	}
220 	
221 	/**
222 	 * Tries to lock mutex. If mutex is already locked by another thread,
223 	 * it immediately returns FALSE. Otherwise it locks mutex and returns
224 	 * TRUE.
225 	 * Note
226 	 * GMutex is neither guaranteed to be recursive nor to be
227 	 * non-recursive. As such, calling g_mutex_lock() on a GMutex that has
228 	 * already been locked by the same thread results in undefined behaviour
229 	 * (including but not limited to deadlocks or arbitrary return values).
230 	 * Returns: TRUE if mutex could be locked
231 	 */
232 	public int trylock()
233 	{
234 		// gboolean g_mutex_trylock (GMutex *mutex);
235 		return g_mutex_trylock(gMutex);
236 	}
237 	
238 	/**
239 	 * Unlocks mutex. If another thread is blocked in a g_mutex_lock()
240 	 * call for mutex, it will become unblocked and can lock mutex itself.
241 	 * Calling g_mutex_unlock() on a mutex that is not locked by the
242 	 * current thread leads to undefined behaviour.
243 	 */
244 	public void unlock()
245 	{
246 		// void g_mutex_unlock (GMutex *mutex);
247 		g_mutex_unlock(gMutex);
248 	}
249 }