Cgu::GobjWeakHandle< T > Class Template Reference
handles and smart pointers

This is a handle for managing weak references to GObjects. More...

`#include <c++-gtk-utils/gobj_handle.h>`

## Public Member Functions

| GobjWeakHandle (T *ptr=0)
void | reset (T *ptr=0)
| GobjWeakHandle (const GobjWeakHandle &gobj)
| GobjWeakHandle (const GobjHandle< T > &gobj)
GobjWeakHandle & | operator= (const GobjWeakHandle &gobj)
GobjWeakHandle & | operator= (const GobjHandle< T > &gobj)
| operator bool () const
bool | valid () const
T * | get () const
T & | operator* () const
T * | operator-> () const
| operator T * () const
| ~GobjWeakHandle ()

## Detailed Description

### template<class T>
class Cgu::GobjWeakHandle< T >

This is a handle for managing weak references to GObjects.

See Also
  GobjHandle

This class tracks a GObject, so that if that GObject no longer exists then operator bool() or the valid() method will return false, but does not take a strong reference by incrementing the reference count to the GObject and so take ownership of it. It has two main use areas: first, in order to break reference cycles that may otherwise arise if two classes would otherwise hold strong references to each other. Secondly, to manage a pointer to a GObject returned by a GTK+ getter function where ownership is not passed (that is, where the user is not expected to call g_object_unref() when finished with the return value). A typical example of this is the GtkTreeSelection object returned by gtk_tree_view_get_selection(). The GtkTreeSelection object is part of the GtkTreeView's implemention and will become invalid as soon as the GtkTreeView object is finalized.

As in the case of the GobjHandle class, although this class has operator*() and operator->() dereferencing operators, and so has normal smart pointer functionality, as it is intended for use with the normal C GObject/pango/GTK+ interfaces, ordinary use would involve passing the handle to a function taking a pointer by means of the operatorT*() type conversion operator (which returns the underlying pointer), or by explicitly calling the get() method to obtain the underlying pointer.

Typical usage is as follows:

using namespace Cgu;
GobjWeakHandle<GtkTreeSelection> s(gtk_tree_view_get_selection(tree_view));
gtk_tree_selection_set_mode(s, GTK_SELECTION_SINGLE);
...
[some code blocks later]
if (s) { // check that the GtkTreeSelection object still exists.
GtkTreeIter iter;
GtkTreeModel* model = 0;
gtk_tree_selection_get_selected(s, &model, &iter);
...
}
else [report error];

Or instead of an 'if' block, GobjWeakHandleError could be caught:

using namespace Cgu;
GobjWeakHandle<GtkTreeSelection> s(gtk_tree_view_get_selection(tree_view));
gtk_tree_selection_set_mode(s, GTK_SELECTION_SINGLE);
...
[some code blocks later]
GtkTreeIter iter;
GtkTreeModel* model = 0;
try {
gtk_tree_selection_get_selected(s, &model, &iter);
...
}
catch (GobjWeakHandleError&) {[report error]}

Thread-safe use

This class wraps g_object_add_weak_pointer()/g_object_remove_weak_pointer(), and as those GObject functions have practical limitations concerning thread-safe use, this class has the same practical limitations. As shown above, typical usage for a weak pointer 's' would be 'if (s) do_it(s)', but if the thread calling that sequence (thread A) were not the thread controlling the lifetime of the referenced GObject (thread B), then thread B may have destroyed the GObject between thread A testing 's' and then calling the referenced object. The same applies to the test leading to GobjWeakHandleError being thrown.

In other words, in the GtkTreeSelection code example above, if the thread calling gtk_tree_selection_get_selected() were not the main GUI thread (which would anyway require the use of gdk_threads_enter()/gdk_threads_leave()), then the calling thread must ensure that the main GUI thread does not destroy the relevant tree view, and so the GtkTreeSelection object, from the beginning of the 'if' test to the end of the 'if' block, or for the duration of the try block. (This cannot be done just by incrementing the reference count of the tree view or the tree selection in the calling thread before the 'if' test or the try block is entered, because by the time the reference is incremented and the weak pointer tested, the tree view and tree selection may already be in their dispose functions but the tree selection's dispose function may not yet have reached the point of dispatching the callback NULLing the weak pointer. As a general design issue, it is usually best only to call GTK+ functions in one thread, and in order to make that straightforward, this library contains a number of classes and functions for inter-thread communication.)

## Constructor & Destructor Documentation

template<class T>

Cgu::GobjWeakHandle< T >::GobjWeakHandle | ( | T * | ptr = `0`) |  |

inline explicit

This constructor does not throw.

Parameters

  ptr | The object which the GobjWeakHandle is to track (if any).

template<class T>

Cgu::GobjWeakHandle< T >::GobjWeakHandle | ( | const GobjWeakHandle< T > & | gobj) |  |

inline

The copy constructor does not throw. It constructs a new weak pointer tracking the same GObject as that tracked by the existing weak pointer.

Parameters

  gobj | The handle to be copied.

template<class T>

Cgu::GobjWeakHandle< T >::GobjWeakHandle | ( | const GobjHandle< T > & | gobj) |  |

inline

This constructor constructs a weak pointer for a GObject managed by a GobjHandle handle. It does not throw.

Parameters

  gobj | The GobjHandle managing the GObject which the GobjWeakHandle is to track.

template<class T>

Cgu::GobjWeakHandle< T >::~GobjWeakHandle | ( | ) |  |

inline

The destructor does not throw.

## Member Function Documentation

template<class T>

T* Cgu::GobjWeakHandle< T >::get | ( | ) |  | const

inline

This method does not throw.

Returns
  A pointer to the tracked GObject.

Exceptions

  GobjWeakHandleError | This method will throw GobjWeakHandleError if the tracked object no longer exists or none is being tracked. There is no need to check for this exception if the status of the tracked object has been established with operator bool() or valid().

template<class T>

Cgu::GobjWeakHandle< T >::operator bool | ( | ) |  | const

inline

This method does not throw.

Returns
  True if the tracked GObject still exists, or false if it does not or no GObject is being tracked.

Note
  The valid() method is a synonym for this method.

template<class T>

Cgu::GobjWeakHandle< T >::operator T * | ( | ) |  | const

inline

This method does not throw.

Returns
  A pointer to the tracked GObject.

Exceptions

  GobjWeakHandleError | This method will throw GobjWeakHandleError if the tracked object no longer exists or none is being tracked. There is no need to check for this exception if the status of the tracked object has been established with operator bool() or valid().

template<class T>

T& Cgu::GobjWeakHandle< T >::operator* | ( | ) |  | const

inline

This method does not throw.

Returns
  A reference to the tracked GObject.

Exceptions

  GobjWeakHandleError | This method will throw GobjWeakHandleError if the tracked object no longer exists or none is being tracked. There is no need to check for this exception if the status of the tracked object has been established with operator bool() or valid().

template<class T>

T* Cgu::GobjWeakHandle< T >::operator-> | ( | ) |  | const

inline

This method does not throw.

Returns
  A pointer to the tracked GObject.

Exceptions

  GobjWeakHandleError | This method will throw GobjWeakHandleError if the tracked object no longer exists or none is being tracked. There is no need to check for this exception if the status of the tracked object has been established with operator bool() or valid().

template<class T>

GobjWeakHandle& Cgu::GobjWeakHandle< T >::operator= | ( | const GobjWeakHandle< T > & | gobj) |  |

inline

This method does not throw. It causes the handle to cease to track its tracked object (if any), and begin tracking the same GObject as that tracked by the assignor. This method does not throw.

Parameters

  gobj | The assignor.

Returns
  The GobjWeakHandle object after assignment.

template<class T>

GobjWeakHandle& Cgu::GobjWeakHandle< T >::operator= | ( | const GobjHandle< T > & | gobj) |  |

inline

This method does not throw. It causes the handle to cease to track its tracked object (if any), and begin tracking the GObject managed by the GobjHandle argument. This method does not throw.

Parameters

  gobj | The assignor GobjHandle.

Returns
  The GobjWeakHandle object after assignment.

template<class T>

void Cgu::GobjWeakHandle< T >::reset | ( | T * | ptr = `0`) |  |

inline

Causes the handle to cease to track its tracked object (if any). If the argument passed is not NULL, the handle will track the new object passed. This method does not throw.

Parameters

  ptr | NULL (the default), or a new object to track.

template<class T>

bool Cgu::GobjWeakHandle< T >::valid | ( | ) |  | const

inline

This method does not throw.

Returns
  True if the tracked GObject still exists, or false if it does not or no GObject is being tracked.

Note
  operator bool() is a synonym for this method.

Since 2.0.5

The documentation for this class was generated from the following file:

- gobj_handle.h