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()
62 	{
63 		return gWeakRef;
64 	}
65 
66 	/** the main Gtk struct as a void* */
67 	protected void* getStruct()
68 	{
69 		return cast(void*)gWeakRef;
70 	}
71 
72 	/**
73 	 * Sets our main struct and passes it to the parent class.
74 	 */
75 	public this (GWeakRef* gWeakRef, bool ownedRef = false)
76 	{
77 		this.gWeakRef = gWeakRef;
78 		this.ownedRef = ownedRef;
79 	}
80 
81 	/** */
82 	this(void* object)
83 	{
84 		g_weak_ref_init(gWeakRef, object);
85 	}
86 
87 	/**
88 	 */
89 
90 	/**
91 	 * Frees resources associated with a non-statically-allocated #GWeakRef.
92 	 * After this call, the #GWeakRef is left in an undefined state.
93 	 *
94 	 * You should only call this on a #GWeakRef that previously had
95 	 * g_weak_ref_init() called on it.
96 	 *
97 	 * Since: 2.32
98 	 */
99 	public void clear()
100 	{
101 		g_weak_ref_clear(gWeakRef);
102 	}
103 
104 	/**
105 	 * If @weak_ref is not empty, atomically acquire a strong
106 	 * reference to the object it points to, and return that reference.
107 	 *
108 	 * This function is needed because of the potential race between taking
109 	 * the pointer value and g_object_ref() on it, if the object was losing
110 	 * its last reference at the same time in a different thread.
111 	 *
112 	 * The caller should release the resulting reference in the usual way,
113 	 * by using g_object_unref().
114 	 *
115 	 * Return: the object pointed to
116 	 *     by @weak_ref, or %NULL if it was empty
117 	 *
118 	 * Since: 2.32
119 	 */
120 	public ObjectG get()
121 	{
122 		auto p = g_weak_ref_get(gWeakRef);
123 		
124 		if(p is null)
125 		{
126 			return null;
127 		}
128 		
129 		return ObjectG.getDObject!(ObjectG)(cast(GObject*) p, true);
130 	}
131 
132 	/**
133 	 * Initialise a non-statically-allocated #GWeakRef.
134 	 *
135 	 * This function also calls g_weak_ref_set() with @object on the
136 	 * freshly-initialised weak reference.
137 	 *
138 	 * This function should always be matched with a call to
139 	 * g_weak_ref_clear().  It is not necessary to use this function for a
140 	 * #GWeakRef in static storage because it will already be
141 	 * properly initialised.  Just use g_weak_ref_set() directly.
142 	 *
143 	 * Params:
144 	 *     object = a #GObject or %NULL
145 	 *
146 	 * Since: 2.32
147 	 */
148 	public void init(ObjectG object)
149 	{
150 		g_weak_ref_init(gWeakRef, (object is null) ? null : object.getObjectGStruct());
151 	}
152 
153 	/**
154 	 * Change the object to which @weak_ref points, or set it to
155 	 * %NULL.
156 	 *
157 	 * You must own a strong reference on @object while calling this
158 	 * function.
159 	 *
160 	 * Params:
161 	 *     object = a #GObject or %NULL
162 	 *
163 	 * Since: 2.32
164 	 */
165 	public void set(ObjectG object)
166 	{
167 		g_weak_ref_set(gWeakRef, (object is null) ? null : object.getObjectGStruct());
168 	}
169 }