Xfce Foundation Classes

Xfc::Trackable Class Reference

The primary base class for the XFC object hierarchy. More...

#include <xfc/trackable.hh>

Inheritance diagram for Xfc::Trackable:

List of all members.

Public Member Functions

Accessors

bool is_dynamic () const
Determines whether the object was allocated from the heap.
bool owns_reference () const
The owns_reference flag setting.

Methods

virtual void ref ()
Increases the object's reference count by one.
virtual void unref ()
Decreases the object's reference count by one.

Static Public Member Functions

Methods

std::new_handler set_new_handler (std::new_handler handler)
Specify a class-specific out-of-memory handler.
void * operator new (size_t size)
Class-specific operator new; inherited by derived classes.
void * operator new (size_t size, void *ptr)
Class-specific placement operator new.
void operator delete (void *ptr)
Class-specific operator delete; inherited by derived classes.

Protected Member Functions

Constructors

Trackable ()
Constructor.
virtual ~Trackable ()=0
Pure virtual Destructor.

Methods

void set_owns_reference (bool setting)
Set the internal owns_reference flag.

Detailed Description

The primary base class for the XFC object hierarchy.

Trackable is a reference counting base class. It implements the reference counting features required by the XFC smart pointer, Xfc::Pointer<>. Trackable is also a memory manager. It allows XFC objects to be created either on the heap or on the stack, and it prevents memory leaks by catching any stray objects. Trackable is based on "Item 27" from Scott Meyers book: More Effective C++. It is a memory tracking class that keeps track of objects allocated on the heap. Trackable provides it's own version of operator new and delete. All new allocations are added to an internal allocation list. When an object's reference count reaches zero the object is removed from this list and delete is called.

When a program ends, Trackable walks through the object allocation list and calls operator delete to free any pointers it finds. This frees the raw memory a pointer points to but note - it doesn't call the object destructor. Ideally, if a program manages heap memory correctly the list should be empty, but it wont be. The list will contain a C++ pointers to any wrapped global GTK+ objects used in your program, such as Gdk::Display, Gdk::Keymap, Gdk::Screen, Gtk::Clipboard, the default Gdk::Colormap and the default Gtk::Style.

Why? If you remember, XFC adds a hook to GTK+ that calls a global "destroy_notify" function when each GTK+ object is destroyed. This function checks to see if the C++ wrapper for the GTK+ object being destroyed was dynamically allocated, and if it was calls delete (otherwise the object was allocated on the stack and nothing happens). This is how XFC manages memory. It lets the GTK+ object decide when it's time to destroy the C++ wrapper, which only happens when an object's reference count drops to zero. This causes a problem for those few default and global objects owned by GTK+. They don't get destroyed until GTK+ is removed from memory, which is never if you use the GNOME desktop. When a program ends the C++ wrappers for these objects will not be deleted and over time could cause a significant memory leak. Since these objects are few, the easiest solution was to have Trackable clean up after itself and free their allocated raw memory.

Note: Do not use Trackable as a garbage collector. It only cleans up after a program ends and not while it's running. The programmer is still responsible for allocating and freeing heap objects correctly. Trackable is just a safe guard to prevent inadvertent memory leaks.

Member Function Documentation

bool Xfc::Trackable::is_dynamic ( ) const

Determines whether the object was allocated from the heap.

Returns:
true if the object was created by new and can safely be deleted.

void Xfc::Trackable::operator delete ( void * ptr ) [static]

Class-specific operator delete; inherited by derived classes.
Only deletes ptr if it's in the Trackable allocation list. You should not call delete yourself! Object deletion is handled internally by XFC.

void* Xfc::Trackable::operator new ( size_t size,

void * ptr

) [static]

Class-specific placement operator new.
This operator new is defined for GCC versions prior to 3.4.0. The standard C++ library included with these versions has a bug in <stl_construct.h> at line 78. Operator new in this line is missing the scope resolution operator, so instead of calling global placement new it calls the class placement new operator. This version of placement new simply calls the global placement new operator .

void* Xfc::Trackable::operator new ( size_t size ) [static]

Class-specific operator new; inherited by derived classes.
Stores a pointer to each new allocation in the allocation_list. If the allocation fails the out-of-memory handler is called.

bool Xfc::Trackable::owns_reference ( ) const [inline]

The owns_reference flag setting.

Returns:
true if unref() must be explicitly called on this object.
This is mainly used by the XFC smart pointer to deteremine if the initial reference count is owned by the object and must be explicitly cleared.

std::new_handler Xfc::Trackable::set_new_handler ( std::new_handler handler ) [static]

Specify a class-specific out-of-memory handler.

Parameters:

handler A user defined out-of-memory handler to install.

void Xfc::Trackable::set_owns_reference ( bool setting ) [inline, protected]

Set the internal owns_reference flag.

Parameters:

setting Set true if the initial reference count must be removed by owner.

Called by derived classes to set the owns_reference_ flag. A G::Object sets this flag to true , indicating that it owns the initial reference count and unref() must be called. As a general rule a Gtk::Object sets this flag to false, indicating that the initial reference count is floating and unref() only needs to be called if you take ownership. If you pass a Gtk::Object to an owner or add a Gtk::Widget to a container you only need to call unref() if you called ref().

virtual void Xfc::Trackable::unref ( ) [virtual]

Decreases the object's reference count by one.
After this call, if the object reference is zero and the object was allocated on the heap, delete is automatically called. You don't need to call delete on objects derived from Trackable. Trackable has no refernece counter itself. It just sets up the reference counting API for the derived classes classes Xfc::Object and Xfc::G::TypeInstance, which do have reference counters. Therefore Trackable::unref() must only be called by a dervied class when its reference count reaches zero.
Reimplemented in Xfc::G::AsyncQueue, Xfc::G::IOChannel, Xfc::G::MainContext, Xfc::G::MainLoop, Xfc::G::Source, Xfc::G::Object, and Xfc::Object.

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

trackable.hh

Xfce Foundation Classes

XFC 4.3