Xfce Foundation Classes
Main Page  | IndexNamespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::Trackable Class Reference

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

#include <xfc/trackable.hh>

Inheritance diagram for Xfc::Trackable:

Xfc::G::IOChannel Xfc::G::MainContext Xfc::G::MainLoop Xfc::G::Source Xfc::G::TypeInstance Xfc::Object Xfc::G::ChildWatchSource Xfc::G::IdleSource Xfc::G::IOSource Xfc::G::TimeoutSource Xfc::G::Object Xfc::G::ObjectSignals Xfc::G::TypeInterface Xfc::G::AsyncQueue Xfc::G::Boxed Xfc::G::Completion Xfc::G::Condition Xfc::G::Date Xfc::G::KeyFile Xfc::G::MarkupParseContext Xfc::G::Module Xfc::G::Mutex Xfc::G::OptionContext Xfc::G::OptionGroup Xfc::G::PatternSpec Xfc::G::Rand Xfc::G::Scanner Xfc::G::ThreadPool Xfc::G::Timer Xfc::Gdk::PixbufFormat Xfc::Gdk::Region Xfc::Gtk::TargetList Xfc::Pango::Attribute Xfc::Pango::AttrIterator Xfc::Pango::Coverage Xfc::Pango::Item Xfc::Pango::LayoutLine List of all members.

Public Member Functions

Accessors
Methods

Static Public Member Functions

Methods

Protected Member Functions

Methods

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

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().

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.

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.

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.

static 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.

static 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.

static 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 .

static 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.


The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3