1 #ifndef _GLIBMM_REFPTR_H
2 #define _GLIBMM_REFPTR_H
3
4 /* Copyright 2002 The gtkmm Development Team
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Lesser General Public
8 * License as published by the Free Software Foundation; either
9 * version 2.1 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Lesser General Public License for more details.
15 *
16 * You should have received a copy of the GNU Lesser General Public
17 * License along with this library. If not, see <http://www.gnu.org/licenses/>.
18 */
19
20 #include <glibmmconfig.h>
21 #include <glib.h>
22 #include <utility>
23
24 namespace Glib
25 {
26
27 /** RefPtr<> is a reference-counting shared smartpointer.
28 *
29 * Some objects in gtkmm are obtained from a shared
30 * store. Consequently you cannot instantiate them yourself. Instead they
31 * return a RefPtr which behaves much like an ordinary pointer in that members
32 * can be reached with the usual <code>object_ptr->member</code> notation.
33 * Unlike most other smart pointers, RefPtr doesn't support dereferencing
34 * through <code>*object_ptr</code>.
35 *
36 * Reference counting means that a shared reference count is incremented each
37 * time a RefPtr is copied, and decremented each time a RefPtr is destroyed,
38 * for instance when it leaves its scope. When the reference count reaches
39 * zero, the contained object is deleted, meaning you don't need to remember
40 * to delete the object.
41 *
42 * RefPtr<> can store any class that has reference() and unreference() methods,
43 * and whose destructor is noexcept (the default for destructors).
44 * In gtkmm, that is anything derived from Glib::ObjectBase, such as
45 * Gdk::Pixbuf.
46 *
47 * See the "Memory Management" section in the "Programming with gtkmm"
48 * book for further information.
49 */
50 template <class T_CppObject>
51 class RefPtr
52 {
53 private:
54 #ifndef DOXYGEN_SHOULD_SKIP_THIS
55 /** Helper class for disallowing use of Glib::RefPtr with certain classes.
56 *
57 * Disallow for instance in Gtk::Widget and its subclasses.
58 * Glib::RefPtr<T>::is_allowed_type::value is false if
59 * T:dont_allow_use_in_glib_refptr_ is a public type, else it's true.
60 * Example:
61 * @code
62 * using dont_allow_use_in_glib_refptr_ = int;
63 * @endcode
64 */
65 class is_allowed_type
66 {
67 private:
68 struct big
69 {
70 int memory[64];
71 };
72
73 static big check(...);
74
75 // If X::dont_allow_use_in_glib_refptr_ is not a type, this check() overload
76 // is ignored because of the SFINAE rule (Substitution Failure Is Not An Error).
77 template <typename X>
78 static typename X::dont_allow_use_in_glib_refptr_ check(X* obj);
79
80 public:
81 static const bool value = sizeof(check(static_cast<T_CppObject*>(nullptr))) == sizeof(big);
82 };
83
84 static_assert(is_allowed_type::value, "Glib::RefPtr must not be used with this class.");
85 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
86
87 public:
88 /** Default constructor
89 *
90 * Afterwards it will be null and use of -> will invoke undefined behaviour.
91 */
92 inline RefPtr() noexcept;
93
94 /// Destructor - decrements reference count.
95 inline ~RefPtr() noexcept;
96
97 /// For use only by the \::create() methods.
98 explicit inline RefPtr(T_CppObject* pCppObject) noexcept;
99
100 /** Copy constructor
101 *
102 * This increments the shared reference count.
103 */
104 inline RefPtr(const RefPtr& src) noexcept;
105
106 /** Move constructor
107 */
108 inline RefPtr(RefPtr&& src) noexcept;
109
110 /** Move constructor (from different, but castable type).
111 */
112 template <class T_CastFrom>
113 inline RefPtr(RefPtr<T_CastFrom>&& src) noexcept;
114
115 /** Copy constructor (from different, but castable type).
116 *
117 * Increments the reference count.
118 */
119 template <class T_CastFrom>
120 inline RefPtr(const RefPtr<T_CastFrom>& src) noexcept;
121
122 /** Swap the contents of two RefPtr<>.
123 * This method swaps the internal pointers to T_CppObject. This can be
124 * done safely without involving a reference/unreference cycle and is
125 * therefore highly efficient.
126 */
127 inline void swap(RefPtr& other) noexcept;
128
129 /// Copy from another RefPtr:
130 inline RefPtr& operator=(const RefPtr& src) noexcept;
131
132 /// Move assignment operator:
133 inline RefPtr& operator=(RefPtr&& src) noexcept;
134
135 /// Move assignment operator (from different, but castable type):
136 template <class T_CastFrom>
137 inline RefPtr& operator=(RefPtr<T_CastFrom>&& src) noexcept;
138
139 /** Copy from different, but castable type.
140 *
141 * Increments the reference count.
142 */
143 template <class T_CastFrom>
144 inline RefPtr& operator=(const RefPtr<T_CastFrom>& src) noexcept;
145
146 /// Tests whether the RefPtr<> point to the same underlying instance.
147 inline bool operator==(const RefPtr& src) const noexcept;
148
149 /// See operator==().
150 inline bool operator!=(const RefPtr& src) const noexcept;
151
152 /** Dereferencing.
153 *
154 * Use the methods of the underlying instance like so:
155 * <code>refptr->memberfun()</code>.
156 */
157 inline T_CppObject* operator->() const noexcept;
158
159 /** Returns the stored pointer.
160 *
161 * @newin{2,56}
162 */
163 inline T_CppObject* get() const noexcept;
164
165 /** Test whether the RefPtr<> points to any underlying instance.
166 *
167 * Mimics usage of ordinary pointers:
168 * @code
169 * if (ptr)
170 * do_something();
171 * @endcode
172 */
173 inline explicit operator bool() const noexcept;
174
175 #ifndef GLIBMM_DISABLE_DEPRECATED
176 /// @deprecated Use reset() instead because this leads to confusion with clear() methods on the
177 /// underlying class. For instance, people use .clear() when they mean ->clear().
178 inline void clear() noexcept;
179 #endif // GLIBMM_DISABLE_DEPRECATED
180
181 /** Set underlying instance to nullptr, decrementing reference count of existing instance
182 * appropriately.
183 * @newin{2,16}
184 */
185 inline void reset() noexcept;
186
187 /** Release the ownership of underlying instance.
188 *
189 * RefPtr's underlying instance is set to nullptr, therefore underlying object can't be accessed
190 * through this RefPtr anymore.
191 * @return an underlying instance.
192 *
193 * Most users should not use release(). It can spoil the automatic destruction
194 * of the managed object. A legitimate use is if you immediately give RefPtr's
195 * reference to another object.
196 */
197 inline T_CppObject* release() noexcept G_GNUC_WARN_UNUSED_RESULT;
198
199 /** Dynamic cast to derived class.
200 *
201 * The RefPtr can't be cast with the usual notation so instead you can use
202 * @code
203 * ptr_derived = RefPtr<Derived>::cast_dynamic(ptr_base);
204 * @endcode
205 */
206 template <class T_CastFrom>
207 static inline RefPtr cast_dynamic(const RefPtr<T_CastFrom>& src) noexcept;
208
209 /** Static cast to derived class.
210 *
211 * Like the dynamic cast; the notation is
212 * @code
213 * ptr_derived = RefPtr<Derived>::cast_static(ptr_base);
214 * @endcode
215 */
216 template <class T_CastFrom>
217 static inline RefPtr cast_static(const RefPtr<T_CastFrom>& src) noexcept;
218
219 /** Cast to non-const.
220 *
221 * The RefPtr can't be cast with the usual notation so instead you can use
222 * @code
223 * ptr_unconst = RefPtr<UnConstType>::cast_const(ptr_const);
224 * @endcode
225 */
226 template <class T_CastFrom>
227 static inline RefPtr cast_const(const RefPtr<T_CastFrom>& src) noexcept;
228
229 /** Compare based on the underlying instance address.
230 *
231 * This is needed in code that requires an ordering on
232 * RefPtr<T_CppObject> instances, e.g. std::set<RefPtr<T_CppObject> >.
233 *
234 * Without these, comparing two RefPtr<T_CppObject> instances
235 * is still syntactically possible, but the result is semantically
236 * wrong, as p1 REL_OP p2 is interpreted as (bool)p1 REL_OP (bool)p2.
237 */
238 inline bool operator<(const RefPtr& src) const noexcept;
239
240 /// See operator<().
241 inline bool operator<=(const RefPtr& src) const noexcept;
242
243 /// See operator<().
244 inline bool operator>(const RefPtr& src) const noexcept;
245
246 /// See operator<().
247 inline bool operator>=(const RefPtr& src) const noexcept;
248
249 private:
250 T_CppObject* pCppObject_;
251 };
252
253 #ifndef DOXYGEN_SHOULD_SKIP_THIS
254
255 // RefPtr<>::operator->() comes first here since it's used by other methods.
256 // If it would come after them it wouldn't be inlined.
257
258 template <class T_CppObject>
259 inline T_CppObject* RefPtr<T_CppObject>::operator->() const noexcept
260 {
261 return pCppObject_;
262 }
263
264 template <class T_CppObject>
RefPtr()265 inline RefPtr<T_CppObject>::RefPtr() noexcept : pCppObject_(nullptr)
266 {
267 }
268
269 template <class T_CppObject>
~RefPtr()270 inline RefPtr<T_CppObject>::~RefPtr() noexcept
271 {
272 if (pCppObject_)
273 pCppObject_->unreference(); // This could cause pCppObject to be deleted.
274 }
275
276 template <class T_CppObject>
RefPtr(T_CppObject * pCppObject)277 inline RefPtr<T_CppObject>::RefPtr(T_CppObject* pCppObject) noexcept : pCppObject_(pCppObject)
278 {
279 }
280
281 template <class T_CppObject>
RefPtr(const RefPtr & src)282 inline RefPtr<T_CppObject>::RefPtr(const RefPtr& src) noexcept : pCppObject_(src.pCppObject_)
283 {
284 if (pCppObject_)
285 pCppObject_->reference();
286 }
287
288 template <class T_CppObject>
RefPtr(RefPtr && src)289 inline RefPtr<T_CppObject>::RefPtr(RefPtr&& src) noexcept : pCppObject_(src.pCppObject_)
290 {
291 src.pCppObject_ = nullptr;
292 }
293
294 template <class T_CppObject>
295 template <class T_CastFrom>
RefPtr(RefPtr<T_CastFrom> && src)296 inline RefPtr<T_CppObject>::RefPtr(RefPtr<T_CastFrom>&& src) noexcept : pCppObject_(src.release())
297 {
298 }
299
300 // The templated ctor allows copy construction from any object that's
301 // castable. Thus, it does downcasts:
302 // base_ref = derived_ref
303 template <class T_CppObject>
304 template <class T_CastFrom>
RefPtr(const RefPtr<T_CastFrom> & src)305 inline RefPtr<T_CppObject>::RefPtr(const RefPtr<T_CastFrom>& src) noexcept :
306 // A different RefPtr<> will not allow us access to pCppObject_. We need
307 // to add a get_underlying() for this, but that would encourage incorrect
308 // use, so we use the less well-known operator->() accessor:
309 pCppObject_(src.operator->())
310 {
311 if (pCppObject_)
312 pCppObject_->reference();
313 }
314
315 template <class T_CppObject>
316 inline void
swap(RefPtr & other)317 RefPtr<T_CppObject>::swap(RefPtr& other) noexcept
318 {
319 T_CppObject* const temp = pCppObject_;
320 pCppObject_ = other.pCppObject_;
321 other.pCppObject_ = temp;
322 }
323
324 template <class T_CppObject>
325 inline RefPtr<T_CppObject>&
326 RefPtr<T_CppObject>::operator=(const RefPtr& src) noexcept
327 {
328 // In case you haven't seen the swap() technique to implement copy
329 // assignment before, here's what it does:
330 //
331 // 1) Create a temporary RefPtr<> instance via the copy ctor, thereby
332 // increasing the reference count of the source object.
333 //
334 // 2) Swap the internal object pointers of *this and the temporary
335 // RefPtr<>. After this step, *this already contains the new pointer,
336 // and the old pointer is now managed by temp.
337 //
338 // 3) The destructor of temp is executed, thereby unreferencing the
339 // old object pointer.
340 //
341 // This technique is described in Herb Sutter's "Exceptional C++", and
342 // has a number of advantages over conventional approaches:
343 //
344 // - Code reuse by calling the copy ctor.
345 // - Strong exception safety for free.
346 // - Self assignment is handled implicitely.
347 // - Simplicity.
348 // - It just works and is hard to get wrong; i.e. you can use it without
349 // even thinking about it to implement copy assignment whereever the
350 // object data is managed indirectly via a pointer, which is very common.
351
352 RefPtr<T_CppObject> temp(src);
353 this->swap(temp);
354 return *this;
355 }
356
357 template <class T_CppObject>
358 inline RefPtr<T_CppObject>&
359 RefPtr<T_CppObject>::operator=(RefPtr&& src) noexcept
360 {
361 RefPtr<T_CppObject> temp(std::move(src));
362 this->swap(temp);
363 src.pCppObject_ = nullptr;
364
365 return *this;
366 }
367
368 template <class T_CppObject>
369 template <class T_CastFrom>
370 inline RefPtr<T_CppObject>&
371 RefPtr<T_CppObject>::operator=(RefPtr<T_CastFrom>&& src) noexcept
372 {
373 if (pCppObject_)
374 pCppObject_->unreference();
375 pCppObject_ = src.release();
376
377 return *this;
378 }
379
380 template <class T_CppObject>
381 template <class T_CastFrom>
382 inline RefPtr<T_CppObject>&
383 RefPtr<T_CppObject>::operator=(const RefPtr<T_CastFrom>& src) noexcept
384 {
385 RefPtr<T_CppObject> temp(src);
386 this->swap(temp);
387 return *this;
388 }
389
390 template <class T_CppObject>
391 inline bool
392 RefPtr<T_CppObject>::operator==(const RefPtr& src) const noexcept
393 {
394 return (pCppObject_ == src.pCppObject_);
395 }
396
397 template <class T_CppObject>
398 inline bool
399 RefPtr<T_CppObject>::operator!=(const RefPtr& src) const noexcept
400 {
401 return (pCppObject_ != src.pCppObject_);
402 }
403
404 template <class T_CppObject>
get()405 inline T_CppObject* RefPtr<T_CppObject>::get() const noexcept
406 {
407 return pCppObject_;
408 }
409
410 template <class T_CppObject>
411 inline RefPtr<T_CppObject>::operator bool() const noexcept
412 {
413 return (pCppObject_ != nullptr);
414 }
415
416 #ifndef GLIBMM_DISABLE_DEPRECATED
417 template <class T_CppObject>
418 inline void
clear()419 RefPtr<T_CppObject>::clear() noexcept
420 {
421 reset();
422 }
423 #endif // GLIBMM_DISABLE_DEPRECATED
424
425 template <class T_CppObject>
426 inline void
reset()427 RefPtr<T_CppObject>::reset() noexcept
428 {
429 RefPtr<T_CppObject> temp; // swap with an empty RefPtr<> to clear *this
430 this->swap(temp);
431 }
432
433 template <class T_CppObject>
434 inline T_CppObject*
release()435 RefPtr<T_CppObject>::release() noexcept
436 {
437 T_CppObject* tmp = pCppObject_;
438 pCppObject_ = nullptr;
439 return tmp;
440 }
441
442 template <class T_CppObject>
443 template <class T_CastFrom>
444 inline RefPtr<T_CppObject>
cast_dynamic(const RefPtr<T_CastFrom> & src)445 RefPtr<T_CppObject>::cast_dynamic(const RefPtr<T_CastFrom>& src) noexcept
446 {
447 T_CppObject* const pCppObject = dynamic_cast<T_CppObject*>(src.operator->());
448
449 if (pCppObject)
450 pCppObject->reference();
451
452 return RefPtr<T_CppObject>(pCppObject);
453 }
454
455 template <class T_CppObject>
456 template <class T_CastFrom>
457 inline RefPtr<T_CppObject>
cast_static(const RefPtr<T_CastFrom> & src)458 RefPtr<T_CppObject>::cast_static(const RefPtr<T_CastFrom>& src) noexcept
459 {
460 T_CppObject* const pCppObject = static_cast<T_CppObject*>(src.operator->());
461
462 if (pCppObject)
463 pCppObject->reference();
464
465 return RefPtr<T_CppObject>(pCppObject);
466 }
467
468 template <class T_CppObject>
469 template <class T_CastFrom>
470 inline RefPtr<T_CppObject>
cast_const(const RefPtr<T_CastFrom> & src)471 RefPtr<T_CppObject>::cast_const(const RefPtr<T_CastFrom>& src) noexcept
472 {
473 T_CppObject* const pCppObject = const_cast<T_CppObject*>(src.operator->());
474
475 if (pCppObject)
476 pCppObject->reference();
477
478 return RefPtr<T_CppObject>(pCppObject);
479 }
480
481 template <class T_CppObject>
482 inline bool
483 RefPtr<T_CppObject>::operator<(const RefPtr& src) const noexcept
484 {
485 return (pCppObject_ < src.pCppObject_);
486 }
487
488 template <class T_CppObject>
489 inline bool
490 RefPtr<T_CppObject>::operator<=(const RefPtr& src) const noexcept
491 {
492 return (pCppObject_ <= src.pCppObject_);
493 }
494
495 template <class T_CppObject>
496 inline bool
497 RefPtr<T_CppObject>::operator>(const RefPtr& src) const noexcept
498 {
499 return (pCppObject_ > src.pCppObject_);
500 }
501
502 template <class T_CppObject>
503 inline bool
504 RefPtr<T_CppObject>::operator>=(const RefPtr& src) const noexcept
505 {
506 return (pCppObject_ >= src.pCppObject_);
507 }
508
509 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
510
511 /** @relates Glib::RefPtr */
512 template <class T_CppObject>
513 inline void
swap(RefPtr<T_CppObject> & lhs,RefPtr<T_CppObject> & rhs)514 swap(RefPtr<T_CppObject>& lhs, RefPtr<T_CppObject>& rhs) noexcept
515 {
516 lhs.swap(rhs);
517 }
518
519 } // namespace Glib
520
521 #endif /* _GLIBMM_REFPTR_H */
522