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