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 gobject.WeakRef;
26 
27 private import gobject.ObjectG;
28 private import gtkc.gobject;
29 public  import gtkc.gobjecttypes;
30 
31 
32 /**
33  * A structure containing a weak reference to a #GObject.  It can either
34  * be empty (i.e. point to %NULL), or point to an object for as long as
35  * at least one "strong" reference to that object exists. Before the
36  * object's #GObjectClass.dispose method is called, every #GWeakRef
37  * associated with becomes empty (i.e. points to %NULL).
38  * 
39  * Like #GValue, #GWeakRef can be statically allocated, stack- or
40  * heap-allocated, or embedded in larger structures.
41  * 
42  * Unlike g_object_weak_ref() and g_object_add_weak_pointer(), this weak
43  * reference is thread-safe: converting a weak pointer to a reference is
44  * atomic with respect to invalidation of weak pointers to destroyed
45  * objects.
46  * 
47  * If the object's #GObjectClass.dispose method results in additional
48  * references to the object being held, any #GWeakRefs taken
49  * before it was disposed will continue to point to %NULL.  If
50  * #GWeakRefs are taken after the object is disposed and
51  * re-referenced, they will continue to point to it until its refcount
52  * goes back to zero, at which point they too will be invalidated.
53  */
54 public class WeakRef
55 {
56 	/** the main Gtk struct */
57 	protected GWeakRef* gWeakRef;
58 	protected bool ownedRef;
59 
60 	/** Get the main Gtk struct */
61 	public GWeakRef* getWeakRefStruct(bool transferOwnership = false)
62 	{
63 		if (transferOwnership)
64 			ownedRef = false;
65 		return gWeakRef;
66 	}
67 
68 	/** the main Gtk struct as a void* */
69 	protected void* getStruct()
70 	{
71 		return cast(void*)gWeakRef;
72 	}
73 
74 	/**
75 	 * Sets our main struct and passes it to the parent class.
76 	 */
77 	public this (GWeakRef* gWeakRef, bool ownedRef = false)
78 	{
79 		this.gWeakRef = gWeakRef;
80 		this.ownedRef = ownedRef;
81 	}
82 
83 	/** */
84 	this(void* object)
85 	{
86 		g_weak_ref_init(gWeakRef, object);
87 	}
88 
89 	/**
90 	 */
91 
92 	/**
93 	 * Frees resources associated with a non-statically-allocated #GWeakRef.
94 	 * After this call, the #GWeakRef is left in an undefined state.
95 	 *
96 	 * You should only call this on a #GWeakRef that previously had
97 	 * g_weak_ref_init() called on it.
98 	 *
99 	 * Since: 2.32
100 	 */
101 	public void clear()
102 	{
103 		g_weak_ref_clear(gWeakRef);
104 	}
105 
106 	/**
107 	 * If @weak_ref is not empty, atomically acquire a strong
108 	 * reference to the object it points to, and return that reference.
109 	 *
110 	 * This function is needed because of the potential race between taking
111 	 * the pointer value and g_object_ref() on it, if the object was losing
112 	 * its last reference at the same time in a different thread.
113 	 *
114 	 * The caller should release the resulting reference in the usual way,
115 	 * by using g_object_unref().
116 	 *
117 	 * Returns: the object pointed to
118 	 *     by @weak_ref, or %NULL if it was empty
119 	 *
120 	 * Since: 2.32
121 	 */
122 	public ObjectG get()
123 	{
124 		auto p = g_weak_ref_get(gWeakRef);
125 		
126 		if(p is null)
127 		{
128 			return null;
129 		}
130 		
131 		return ObjectG.getDObject!(ObjectG)(cast(GObject*) p, true);
132 	}
133 
134 	/**
135 	 * Initialise a non-statically-allocated #GWeakRef.
136 	 *
137 	 * This function also calls g_weak_ref_set() with @object on the
138 	 * freshly-initialised weak reference.
139 	 *
140 	 * This function should always be matched with a call to
141 	 * g_weak_ref_clear().  It is not necessary to use this function for a
142 	 * #GWeakRef in static storage because it will already be
143 	 * properly initialised.  Just use g_weak_ref_set() directly.
144 	 *
145 	 * Params:
146 	 *     object = a #GObject or %NULL
147 	 *
148 	 * Since: 2.32
149 	 */
150 	public void init(ObjectG object)
151 	{
152 		g_weak_ref_init(gWeakRef, (object is null) ? null : object.getObjectGStruct());
153 	}
154 
155 	/**
156 	 * Change the object to which @weak_ref points, or set it to
157 	 * %NULL.
158 	 *
159 	 * You must own a strong reference on @object while calling this
160 	 * function.
161 	 *
162 	 * Params:
163 	 *     object = a #GObject or %NULL
164 	 *
165 	 * Since: 2.32
166 	 */
167 	public void set(ObjectG object)
168 	{
169 		g_weak_ref_set(gWeakRef, (object is null) ? null : object.getObjectGStruct());
170 	}
171 }