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