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.Mutex;
26 
27 private import glib.c.functions;
28 public  import glib.c.types;
29 public  import gtkc.glibtypes;
30 
31 
32 /**
33  * The #GMutex struct is an opaque data structure to represent a mutex
34  * (mutual exclusion). It can be used to protect data against shared
35  * access.
36  * 
37  * Take for example the following function:
38  * |[<!-- language="C" -->
39  * int
40  * give_me_next_number (void)
41  * {
42  * static int current_number = 0;
43  * 
44  * // now do a very complicated calculation to calculate the new
45  * // number, this might for example be a random number generator
46  * current_number = calc_next_number (current_number);
47  * 
48  * return current_number;
49  * }
50  * ]|
51  * It is easy to see that this won't work in a multi-threaded
52  * application. There current_number must be protected against shared
53  * access. A #GMutex can be used as a solution to this problem:
54  * |[<!-- language="C" -->
55  * int
56  * give_me_next_number (void)
57  * {
58  * static GMutex mutex;
59  * static int current_number = 0;
60  * int ret_val;
61  * 
62  * g_mutex_lock (&mutex);
63  * ret_val = current_number = calc_next_number (current_number);
64  * g_mutex_unlock (&mutex);
65  * 
66  * return ret_val;
67  * }
68  * ]|
69  * Notice that the #GMutex is not initialised to any particular value.
70  * Its placement in static storage ensures that it will be initialised
71  * to all-zeros, which is appropriate.
72  * 
73  * If a #GMutex is placed in other contexts (eg: embedded in a struct)
74  * then it must be explicitly initialised using g_mutex_init().
75  * 
76  * A #GMutex should only be accessed via g_mutex_ functions.
77  */
78 public class Mutex
79 {
80 	/** the main Gtk struct */
81 	protected GMutex* gMutex;
82 	protected bool ownedRef;
83 
84 	/** Get the main Gtk struct */
85 	public GMutex* getMutexStruct(bool transferOwnership = false)
86 	{
87 		if (transferOwnership)
88 			ownedRef = false;
89 		return gMutex;
90 	}
91 
92 	/** the main Gtk struct as a void* */
93 	protected void* getStruct()
94 	{
95 		return cast(void*)gMutex;
96 	}
97 
98 	/**
99 	 * Sets our main struct and passes it to the parent class.
100 	 */
101 	public this (GMutex* gMutex, bool ownedRef = false)
102 	{
103 		this.gMutex = gMutex;
104 		this.ownedRef = ownedRef;
105 	}
106 
107 
108 	/**
109 	 * Frees the resources allocated to a mutex with g_mutex_init().
110 	 *
111 	 * This function should not be used with a #GMutex that has been
112 	 * statically allocated.
113 	 *
114 	 * Calling g_mutex_clear() on a locked mutex leads to undefined
115 	 * behaviour.
116 	 *
117 	 * Sine: 2.32
118 	 */
119 	public void clear()
120 	{
121 		g_mutex_clear(gMutex);
122 	}
123 
124 	/**
125 	 * Initializes a #GMutex so that it can be used.
126 	 *
127 	 * This function is useful to initialize a mutex that has been
128 	 * allocated on the stack, or as part of a larger structure.
129 	 * It is not necessary to initialize a mutex that has been
130 	 * statically allocated.
131 	 *
132 	 * |[<!-- language="C" -->
133 	 * typedef struct {
134 	 * GMutex m;
135 	 * ...
136 	 * } Blob;
137 	 *
138 	 * Blob *b;
139 	 *
140 	 * b = g_new (Blob, 1);
141 	 * g_mutex_init (&b->m);
142 	 * ]|
143 	 *
144 	 * To undo the effect of g_mutex_init() when a mutex is no longer
145 	 * needed, use g_mutex_clear().
146 	 *
147 	 * Calling g_mutex_init() on an already initialized #GMutex leads
148 	 * to undefined behaviour.
149 	 *
150 	 * Since: 2.32
151 	 */
152 	public void init()
153 	{
154 		g_mutex_init(gMutex);
155 	}
156 
157 	/**
158 	 * Locks @mutex. If @mutex is already locked by another thread, the
159 	 * current thread will block until @mutex is unlocked by the other
160 	 * thread.
161 	 *
162 	 * #GMutex is neither guaranteed to be recursive nor to be
163 	 * non-recursive.  As such, calling g_mutex_lock() on a #GMutex that has
164 	 * already been locked by the same thread results in undefined behaviour
165 	 * (including but not limited to deadlocks).
166 	 */
167 	public void lock()
168 	{
169 		g_mutex_lock(gMutex);
170 	}
171 
172 	/**
173 	 * Tries to lock @mutex. If @mutex is already locked by another thread,
174 	 * it immediately returns %FALSE. Otherwise it locks @mutex and returns
175 	 * %TRUE.
176 	 *
177 	 * #GMutex is neither guaranteed to be recursive nor to be
178 	 * non-recursive.  As such, calling g_mutex_lock() on a #GMutex that has
179 	 * already been locked by the same thread results in undefined behaviour
180 	 * (including but not limited to deadlocks or arbitrary return values).
181 	 *
182 	 * Returns: %TRUE if @mutex could be locked
183 	 */
184 	public bool trylock()
185 	{
186 		return g_mutex_trylock(gMutex) != 0;
187 	}
188 
189 	/**
190 	 * Unlocks @mutex. If another thread is blocked in a g_mutex_lock()
191 	 * call for @mutex, it will become unblocked and can lock @mutex itself.
192 	 *
193 	 * Calling g_mutex_unlock() on a mutex that is not locked by the
194 	 * current thread leads to undefined behaviour.
195 	 */
196 	public void unlock()
197 	{
198 		g_mutex_unlock(gMutex);
199 	}
200 }