glibmm: Glib::RefPtr< T_CppObject > Class Template Reference

RefPtr<> is a reference-counting shared smartpointer. More...

#include <glibmm/refptr.h>

Public Member Functions

 RefPtr () noexcept
 Default constructor. More...

 
 ~RefPtr () noexcept
 Destructor - decrements reference count. More...

 
 RefPtr (T_CppObject* pCppObject) noexcept
 For use only by the ::create() methods. More...

 
 RefPtr (const RefPtr& src) noexcept
 Copy constructor. More...

 
 RefPtr (RefPtr&& src) noexcept
 Move constructor. More...

 
template<class T_CastFrom >
 RefPtr (RefPtr< T_CastFrom >&& src) noexcept
 Move constructor (from different, but castable type). More...

 
template<class T_CastFrom >
 RefPtr (const RefPtr< T_CastFrom >& src) noexcept
 Copy constructor (from different, but castable type). More...

 
void swap (RefPtr& other) noexcept
 Swap the contents of two RefPtr<>. More...

 
RefPtroperator= (const RefPtr& src) noexcept
 Copy from another RefPtr: More...

 
RefPtroperator= (RefPtr&& src) noexcept
 Move assignment operator: More...

 
template<class T_CastFrom >
RefPtroperator= (RefPtr< T_CastFrom >&& src) noexcept
 Move assignment operator (from different, but castable type): More...

 
template<class T_CastFrom >
RefPtroperator= (const RefPtr< T_CastFrom >& src) noexcept
 Copy from different, but castable type). More...

 
bool operator== (const RefPtr& src) const noexcept
 Tests whether the RefPtr<> point to the same underlying instance. More...

 
bool operator!= (const RefPtr& src) const noexcept
 See operator==(). More...

 
T_CppObject* operator-> () const noexcept
 Dereferencing. More...

 
 operator bool () const noexcept
 Test whether the RefPtr<> points to any underlying instance. More...

 
void clear () noexcept
 
void reset () noexcept
 Set underlying instance to nullptr, decrementing reference count of existing instance appropriately. More...

 
T_CppObject* release () noexcept G_GNUC_WARN_UNUSED_RESULT
 Release the ownership of underlying instance. More...

 
bool operator< (const RefPtr& src) const noexcept
 Compare based on the underlying instance address. More...

 
bool operator<= (const RefPtr& src) const noexcept
 See operator<(). More...

 
bool operator> (const RefPtr& src) const noexcept
 See operator<(). More...

 
bool operator>= (const RefPtr& src) const noexcept
 See operator<(). More...

 

Static Public Member Functions

template<class T_CastFrom >
static RefPtr cast_dynamic (const RefPtr< T_CastFrom >& src) noexcept
 Dynamic cast to derived class. More...

 
template<class T_CastFrom >
static RefPtr cast_static (const RefPtr< T_CastFrom >& src) noexcept
 Static cast to derived class. More...

 
template<class T_CastFrom >
static RefPtr cast_const (const RefPtr< T_CastFrom >& src) noexcept
 Cast to non-const. More...

 

Related Functions

(Note that these are not member functions.)

template<class T_CppObject >
void swap (RefPtr< T_CppObject >& lhs, RefPtr< T_CppObject >& rhs) noexcept
 

Detailed Description

template<class T_CppObject>

class Glib::RefPtr< T_CppObject >

RefPtr<> is a reference-counting shared smartpointer.

Some objects in gtkmm are obtained from a shared store. Consequently you cannot instantiate them yourself. Instead they return a RefPtr which behaves much like an ordinary pointer in that members can be reached with the usual object_ptr->member notation. Unlike most other smart pointers, RefPtr doesn't support dereferencing through * object_ptr.

Reference counting means that a shared reference count is incremented each time a RefPtr is copied, and decremented each time a RefPtr is destroyed, for instance when it leaves its scope. When the reference count reaches zero, the contained object is deleted, meaning you don't need to remember to delete the object.

RefPtr<> can store any class that has reference() and unreference() methods, and whose destructor is noexcept (the default for destructors). In gtkmm, that is anything derived from Glib::ObjectBase, such as Gdk::Pixmap.

See the "Memory Management" section in the "Programming with gtkmm" book for further information.

Examples:
thread/dispatcher.cc.

Constructor & Destructor Documentation

template <class T_CppObject>
Glib::RefPtr< T_CppObject >::RefPtr ( )
inlinenoexcept

Default constructor.

Afterwards it will be null and use of -> will cause a segmentation fault.

template <class T_CppObject>
Glib::RefPtr< T_CppObject >::~RefPtr ( )
inlinenoexcept

Destructor - decrements reference count.

template <class T_CppObject>
Glib::RefPtr< T_CppObject >::RefPtr ( T_CppObject *  pCppObject)
inlineexplicitnoexcept

For use only by the ::create() methods.

template <class T_CppObject>
Glib::RefPtr< T_CppObject >::RefPtr ( const RefPtr< T_CppObject >&  src)
inlinenoexcept

Copy constructor.

This increments the shared reference count.

template <class T_CppObject>
Glib::RefPtr< T_CppObject >::RefPtr ( RefPtr< T_CppObject >&&  src)
inlinenoexcept

Move constructor.

template <class T_CppObject>
template <class T_CastFrom >
Glib::RefPtr< T_CppObject >::RefPtr ( RefPtr< T_CastFrom >&&  src)
inlinenoexcept

Move constructor (from different, but castable type).

template <class T_CppObject>
template <class T_CastFrom >
Glib::RefPtr< T_CppObject >::RefPtr ( const RefPtr< T_CastFrom >&  src)
inlinenoexcept

Copy constructor (from different, but castable type).

Increments the reference count.

Member Function Documentation

template <class T_CppObject>
template <class T_CastFrom >
static RefPtr Glib::RefPtr< T_CppObject >::cast_const ( const RefPtr< T_CastFrom >&  src)
inlinestaticnoexcept

Cast to non-const.

The RefPtr can't be cast with the usual notation so instead you can use

ptr_unconst = RefPtr<UnConstType>::cast_const(ptr_const);
template <class T_CppObject>
template <class T_CastFrom >
static RefPtr Glib::RefPtr< T_CppObject >::cast_dynamic ( const RefPtr< T_CastFrom >&  src)
inlinestaticnoexcept

Dynamic cast to derived class.

The RefPtr can't be cast with the usual notation so instead you can use

ptr_derived = RefPtr<Derived>::cast_dynamic(ptr_base);
template <class T_CppObject>
template <class T_CastFrom >
static RefPtr Glib::RefPtr< T_CppObject >::cast_static ( const RefPtr< T_CastFrom >&  src)
inlinestaticnoexcept

Static cast to derived class.

Like the dynamic cast; the notation is

ptr_derived = RefPtr<Derived>::cast_static(ptr_base);
template <class T_CppObject>
void Glib::RefPtr< T_CppObject >::clear ( )
inlinenoexcept
Deprecated:
Use reset() instead because this leads to confusion with clear() methods on the underlying class. For instance, people use .clear() when they mean ->clear().
template <class T_CppObject>
Glib::RefPtr< T_CppObject >::operator bool ( ) const
inlineexplicitnoexcept

Test whether the RefPtr<> points to any underlying instance.

Mimics usage of ordinary pointers:

if (ptr)
do_something();
template <class T_CppObject>
bool Glib::RefPtr< T_CppObject >::operator!= ( const RefPtr< T_CppObject >&  src) const
inlinenoexcept
template <class T_CppObject>
T_CppObject* Glib::RefPtr< T_CppObject >::operator-> ( ) const
inlinenoexcept

Dereferencing.

Use the methods of the underlying instance like so: refptr->memberfun().

template <class T_CppObject>
bool Glib::RefPtr< T_CppObject >::operator< ( const RefPtr< T_CppObject >&  src) const
inlinenoexcept

Compare based on the underlying instance address.

This is needed in code that requires an ordering on RefPtr<T_CppObject> instances, e.g. std::set<RefPtr<T_CppObject> >.

Without these, comparing two RefPtr<T_CppObject> instances is still syntactically possible, but the result is semantically wrong, as p1 REL_OP p2 is interpreted as (bool)p1 REL_OP (bool)p2.

template <class T_CppObject>
bool Glib::RefPtr< T_CppObject >::operator<= ( const RefPtr< T_CppObject >&  src) const
inlinenoexcept
template <class T_CppObject>
RefPtr& Glib::RefPtr< T_CppObject >::operator= ( const RefPtr< T_CppObject >&  src)
inlinenoexcept

Copy from another RefPtr:

template <class T_CppObject>
RefPtr& Glib::RefPtr< T_CppObject >::operator= ( RefPtr< T_CppObject >&&  src)
inlinenoexcept

Move assignment operator:

template <class T_CppObject>
template <class T_CastFrom >
RefPtr& Glib::RefPtr< T_CppObject >::operator= ( RefPtr< T_CastFrom >&&  src)
inlinenoexcept

Move assignment operator (from different, but castable type):

template <class T_CppObject>
template <class T_CastFrom >
RefPtr& Glib::RefPtr< T_CppObject >::operator= ( const RefPtr< T_CastFrom >&  src)
inlinenoexcept

Copy from different, but castable type).

Increments the reference count.

template <class T_CppObject>
bool Glib::RefPtr< T_CppObject >::operator== ( const RefPtr< T_CppObject >&  src) const
inlinenoexcept

Tests whether the RefPtr<> point to the same underlying instance.

template <class T_CppObject>
bool Glib::RefPtr< T_CppObject >::operator> ( const RefPtr< T_CppObject >&  src) const
inlinenoexcept
template <class T_CppObject>
bool Glib::RefPtr< T_CppObject >::operator>= ( const RefPtr< T_CppObject >&  src) const
inlinenoexcept
template <class T_CppObject>
T_CppObject* Glib::RefPtr< T_CppObject >::release ( )
inlinenoexcept

Release the ownership of underlying instance.

RefPtr's underlying instance is set to nullptr, therefore underlying object can't be accessed through this RefPtr anymore.

Returns
an underlying instance.

Most users should not use release(). It can spoil the automatic destruction of the managed object. A legitimate use is if you immediately give RefPtr's reference to another object.

template <class T_CppObject>
void Glib::RefPtr< T_CppObject >::reset ( )
inlinenoexcept

Set underlying instance to nullptr, decrementing reference count of existing instance appropriately.

Since glibmm 2.16:
template <class T_CppObject>
void Glib::RefPtr< T_CppObject >::swap ( RefPtr< T_CppObject >&  other)
inlinenoexcept

Swap the contents of two RefPtr<>.

This method swaps the internal pointers to T_CppObject. This can be done safely without involving a reference/unreference cycle and is therefore highly efficient.

Friends And Related Function Documentation

template <class T_CppObject >
void swap ( RefPtr< T_CppObject >&  lhs,
RefPtr< T_CppObject >&  rhs 
)
related