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