/////////////////////////////////////////////////////////////////////////////
// Name: object.h
-// Purpose: interface of wxObjectRefData
+// Purpose: interface of wxRefCounter
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-/**
- @class wxObjectRefData
+/** @class wxObjectRefData
+
+ This class is just a typedef to wxRefCounter and is used by wxObject.
- This class is used to store reference-counted data.
+ Derive classes from this to store your own data in wxObject-derived
+ classes. When retrieving information from a wxObject's reference data,
+ you will need to cast to your own derived class.
- Derive classes from this to store your own data. When retrieving information
- from a wxObject's reference data, you will need to cast to your own derived class.
+ Below is an example illustrating how to store reference counted
+ data in a class derived from wxObject including copy-on-write
+ semantics.
- @b Example:
+ @section objectrefdata_example Example
@code
// include file
+ // ------------
- class MyCar: public wxObject
+ class MyCar : public wxObject
{
public:
MyCar() { }
virtual wxObjectRefData *CreateRefData() const;
virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;
- DECLARE_DYNAMIC_CLASS(MyCar)
+ wxDECLARE_DYNAMIC_CLASS(MyCar)
};
// implementation
+ // --------------
- class MyCarRefData: public wxObjectRefData
+ // the reference data class is typically a private class only visible in the
+ // implementation source file of the refcounted class.
+ class MyCarRefData : public wxObjectRefData
{
public:
MyCarRefData()
MyCarRefData( const MyCarRefData& data )
: wxObjectRefData()
{
+ // copy refcounted data; this is usually a time- and memory-consuming operation
+ // and is only done when two (or more) MyCar instances need to unshare a
+ // common instance of MyCarRefData
m_price = data.m_price;
}
return m_price == data.m_price;
}
+ private:
+ // in real world, reference counting is usually used only when
+ // the wxObjectRefData-derived class holds data very memory-consuming;
+ // in this example the various MyCar instances may share a MyCarRefData
+ // instance which however only takes 4 bytes for this integer!
int m_price;
};
#define M_CARDATA ((MyCarRefData *)m_refData)
-
- IMPLEMENT_DYNAMIC_CLASS(MyCar,wxObject)
+ wxIMPLEMENT_DYNAMIC_CLASS(MyCar, wxObject);
MyCar::MyCar( int price )
{
+ // here we init the MyCar internal data:
m_refData = new MyCarRefData();
M_CARDATA->m_price = price;
}
bool MyCar::operator == ( const MyCar& car ) const
{
- if (m_refData == car.m_refData) return true;
-
- if (!m_refData || !car.m_refData) return false;
-
+ if (m_refData == car.m_refData)
+ return true;
+ if (!m_refData || !car.m_refData)
+ return false;
+
+ // here we use the MyCarRefData::operator==() function.
+ // Note however that this comparison may be very slow if the
+ // reference data contains a lot of data to be compared.
return ( *(MyCarRefData*)m_refData == *(MyCarRefData*)car.m_refData );
}
void MyCar::SetPrice( int price )
{
+ // since this function modifies one of the MyCar internal property,
+ // we need to be sure that the other MyCar instances which share the
+ // same MyCarRefData instance are not affected by this call.
+ // I.e. it's very important to call UnShare() in all setters of
+ // refcounted classes!
UnShare();
M_CARDATA->m_price = price;
{
wxCHECK_MSG( IsOk(), -1, "invalid car" );
- return (M_CARDATA->m_price);
+ return M_CARDATA->m_price;
}
@endcode
@see wxObject, wxObjectDataPtr<T>, @ref overview_refcount
*/
-class wxObjectRefData
+typedef wxRefCounter wxObjectRefData;
+
+
+/**
+ @class wxRefCounter
+
+ This class is used to manage reference-counting providing a simple
+ interface and a counter. wxRefCounter can be easily used together
+ with wxObjectDataPtr<T> to ensure that no calls to wxRefCounter::DecRef()
+ are missed - thus avoiding memory leaks.
+
+ wxObjectRefData is a typedef to wxRefCounter and is used as the
+ built-in reference counted storage for wxObject-derived classes.
+
+ @library{wxbase}
+ @category{rtti}
+
+ @see wxObject, wxObjectRefData, wxObjectDataPtr<T>, @ref overview_refcount
+*/
+class wxRefCounter
{
protected:
/**
Destructor.
- It's declared @c protected so that wxObjectRefData instances
+ It's declared @c protected so that wxRefCounter instances
will never be destroyed directly but only as result of a DecRef() call.
*/
- virtual ~wxObjectRefData();
+ virtual ~wxRefCounter();
public:
/**
Default constructor. Initialises the internal reference count to 1.
*/
- wxObjectRefData();
+ wxRefCounter();
/**
Decrements the reference count associated with this shared data and, if
- it reaches zero, destroys this instance of wxObjectRefData releasing its
+ it reaches zero, destroys this instance of wxRefCounter releasing its
memory.
Please note that after calling this function, the caller should
wxObject can be used to implement @ref overview_refcount "reference counted"
objects, such as wxPen, wxBitmap and others
(see @ref overview_refcount_list "this list").
+ See wxRefCounter and @ref overview_refcount for more info about
+ reference counting.
@library{wxbase}
@category{rtti}
- @see wxClassInfo, @ref overview_debugging, wxObjectRefData
+ @see wxClassInfo, @ref overview_debugging, @ref overview_refcount,
+ wxObjectDataRef, wxObjectDataPtr<T>
*/
class wxObject
{
public:
+ /**
+ Default ctor; initializes to @NULL the internal reference data.
+ */
wxObject();
/**
Copy ctor.
+
+ Sets the internal wxObject::m_refData pointer to point to the same
+ instance of the wxObjectRefData-derived class pointed by @c other and
+ increments the refcount of wxObject::m_refData.
*/
wxObject(const wxObject& other);
-
/**
Destructor.
/**
This virtual function is redefined for every class that requires run-time
- type information, when using the ::DECLARE_CLASS macro (or similar).
+ type information, when using the ::wxDECLARE_CLASS macro (or similar).
*/
virtual wxClassInfo* GetClassInfo() const;
/**
- Returns the wxObject::m_refData pointer, i.e. the data referenced by this object.
+ Returns the wxObject::m_refData pointer, i.e.\ the data referenced by this object.
@see Ref(), UnRef(), wxObject::m_refData, SetRefData(), wxObjectRefData
*/
Example:
@code
- bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
+ bool tmp = obj->IsKindOf(wxCLASSINFO(wxFrame));
@endcode
@param info
A pointer to a class information object, which may be obtained
- by using the ::CLASSINFO macro.
+ by using the ::wxCLASSINFO macro.
@return @true if the class represented by info is the same class as this
one or is derived from it.
void UnRef();
/**
- Ensure that this object's data is not shared with any other object.
-
- If we have no data, it is created using CreateRefData() below,
- if we have shared data, it is copied using CloneRefData(),
- otherwise nothing is done.
+ This is the same of AllocExclusive() but this method is public.
*/
void UnShare();
void* operator new(size_t size, const wxString& filename = NULL, int lineNum = 0);
protected:
+ /**
+ Ensure that this object's data is not shared with any other object.
+
+ If we have no data, it is created using CreateRefData();
+ if we have shared data (i.e. data with a reference count greater than 1),
+ it is copied using CloneRefData(); otherwise nothing is done (the data
+ is already present and is not shared by other object instances).
+
+ If you use this function you should make sure that you override the
+ CreateRefData() and CloneRefData() functions in your class otherwise
+ an assertion will fail at runtime.
+ */
+ void AllocExclusive();
+
+ /**
+ Creates a new instance of the wxObjectRefData-derived class specific to
+ this object and returns it.
+
+ This is usually implemented as a one-line call:
+ @code
+ wxObjectRefData *MyObject::CreateRefData() const
+ {
+ return new MyObjectRefData;
+ }
+ @endcode
+ */
+ virtual wxObjectRefData *CreateRefData() const;
+
+ /**
+ Creates a new instance of the wxObjectRefData-derived class specific to
+ this object and initializes it copying @a data.
+
+ This is usually implemented as a one-line call:
+ @code
+ wxObjectRefData *MyObject::CloneRefData(const wxObjectRefData *data) const
+ {
+ // rely on the MyObjectRefData copy ctor:
+ return new MyObjectRefData(*(MyObjectRefData *)data);
+ }
+ @endcode
+ */
+ virtual wxObjectRefData *CloneRefData(const wxObjectRefData *data) const;
/**
Pointer to an object which is the object's reference-counted data.
@see Ref(), UnRef(), SetRefData(), GetRefData(), wxObjectRefData
*/
- wxObjectRefData* m_refData;
+ wxObjectRefData* m_refData;
};
This class stores meta-information about classes.
Instances of this class are not generally defined directly by an application,
- but indirectly through use of macros such as ::DECLARE_DYNAMIC_CLASS and
- ::IMPLEMENT_DYNAMIC_CLASS.
+ but indirectly through use of macros such as ::wxDECLARE_DYNAMIC_CLASS and
+ ::wxIMPLEMENT_DYNAMIC_CLASS.
@library{wxbase}
@category{rtti}
/**
- This is helper template class primarily written to avoid memory leaks because of
- missing calls to wxObjectRefData::DecRef().
+ This is an helper template class primarily written to avoid memory leaks because
+ of missing calls to wxRefCounter::DecRef() and wxObjectRefData::DecRef().
Despite the name this template can actually be used as a smart pointer for any
class implementing the reference counting interface which only consists of the two
methods @b T::IncRef() and @b T::DecRef().
The difference to wxSharedPtr<T> is that wxObjectDataPtr<T> relies on the reference
- counting to be in the class pointed to where instead wxSharedPtr<T> implements the
+ counting to be in the class pointed to, where instead wxSharedPtr<T> implements the
reference counting itself.
+ Below is an example illustrating how to implement reference counted
+ data using wxRefCounter and wxObjectDataPtr<T> with copy-on-write
+ semantics.
- @b Example:
+ @section objectdataptr_example Example
@code
- class MyCarRefData: public wxObjectRefData
+ class MyCarRefData: public wxRefCounter
{
public:
- MyCarRefData() { m_price = 0; }
-
- MyCarRefData( const MyCarRefData& data )
- : wxObjectRefData()
- {
- m_price = data.m_price;
- }
+ MyCarRefData( int price = 0 ) : m_price(price) { }
+ MyCarRefData( const MyCarRefData& data ) : m_price(data.m_price) { }
void SetPrice( int price ) { m_price = price; }
- int GetPrice() { return m_price; }
+ int GetPrice() const { return m_price; }
protected:
int m_price;
class MyCar
{
public:
- MyCar( int price ) : m_data( new MyCarRefData )
+ // initializes this MyCar assigning to the
+ // internal data pointer a new instance of MyCarRefData
+ MyCar( int price = 0 ) : m_data( new MyCarRefData(price) )
{
- m_data->SetPrice( price );
}
MyCar& operator =( const MyCar& tocopy )
{
+ // shallow copy: this is just a fast copy of pointers; the real
+ // memory-consuming data which typically is stored inside
+ // MyCarRefData is not copied here!
m_data = tocopy.m_data;
return *this;
}
bool operator == ( const MyCar& other ) const
{
- if (m_data.get() == other.m_data.get()) return true;
- return (m_data->GetPrice() == other.m_data->GetPrice());
+ if (m_data.get() == other.m_data.get())
+ return true; // this instance and the 'other' one share the
+ // same MyCarRefData data...
+
+ return (m_data.GetPrice() == other.m_data.GetPrice());
}
void SetPrice( int price )
{
- UnShare();
- m_data->SetPrice( price );
+ // make sure changes to this class do not affect other instances
+ // currently sharing our same refcounted data:
+ UnShare();
+
+ m_data->SetPrice( price );
}
int GetPrice() const
@see wxObject, wxObjectRefData, @ref overview_refcount, wxSharedPtr<T>,
wxScopedPtr<T>, wxWeakRef<T>
*/
+template <class T>
class wxObjectDataPtr<T>
{
public:
@header{wx/object.h}
*/
-#define CLASSINFO( className )
-
-/**
- Used inside a class declaration to declare that the class should be made
- known to the class hierarchy, but objects of this class cannot be created
- dynamically. The same as DECLARE_ABSTRACT_CLASS().
-
- @header{wx/object.h}
-*/
-#define DECLARE_CLASS( className )
+#define wxCLASSINFO( className )
/**
Used inside a class declaration to declare that the class should be
made known to the class hierarchy, but objects of this class cannot be created
- dynamically. The same as DECLARE_CLASS().
+ dynamically.
@header{wx/object.h}
@code
class wxCommand: public wxObject
{
- DECLARE_ABSTRACT_CLASS(wxCommand)
+ wxDECLARE_ABSTRACT_CLASS(wxCommand);
private:
...
};
@endcode
*/
-#define DECLARE_ABSTRACT_CLASS( className )
+#define wxDECLARE_ABSTRACT_CLASS( className )
/**
Used inside a class declaration to make the class known to wxWidgets RTTI
system and also declare that the objects of this class should be
dynamically creatable from run-time type information. Notice that this
implies that the class should have a default constructor, if this is not
- the case consider using DECLARE_CLASS().
+ the case consider using wxDECLARE_ABSTRACT_CLASS().
@header{wx/object.h}
@code
class wxFrame: public wxWindow
{
- DECLARE_DYNAMIC_CLASS(wxFrame)
+ wxDECLARE_DYNAMIC_CLASS(wxFrame);
private:
const wxString& frameTitle;
};
@endcode
*/
-#define DECLARE_DYNAMIC_CLASS( className )
+#define wxDECLARE_DYNAMIC_CLASS( className )
/**
- Used in a C++ implementation file to complete the declaration of a class
- that has run-time type information. The same as IMPLEMENT_ABSTRACT_CLASS().
-
- @header{wx/object.h}
-*/
-#define IMPLEMENT_CLASS( className, baseClassName )
+ Used inside a class declaration to declare that the class should be made
+ known to the class hierarchy, but objects of this class cannot be created
+ dynamically.
-/**
- Used in a C++ implementation file to complete the declaration of a class
- that has run-time type information and two base classes. The same as
- IMPLEMENT_ABSTRACT_CLASS2().
+ The same as wxDECLARE_ABSTRACT_CLASS().
@header{wx/object.h}
*/
-#define IMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 )
+#define wxDECLARE_CLASS( className )
/**
Used in a C++ implementation file to complete the declaration of a class
- that has run-time type information. The same as IMPLEMENT_CLASS().
-
+ that has run-time type information.
+
@header{wx/object.h}
Example:
@code
- IMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject)
+ wxIMPLEMENT_ABSTRACT_CLASS(wxCommand, wxObject);
wxCommand::wxCommand(void)
{
}
@endcode
*/
-#define IMPLEMENT_ABSTRACT_CLASS( className, baseClassName )
+#define wxIMPLEMENT_ABSTRACT_CLASS( className, baseClassName )
/**
Used in a C++ implementation file to complete the declaration of a class
- that has run-time type information and two base classes. The same as
- IMPLEMENT_CLASS2().
+ that has run-time type information and two base classes.
@header{wx/object.h}
*/
-#define IMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 )
+#define wxIMPLEMENT_ABSTRACT_CLASS2( className, baseClassName1, baseClassName2 )
/**
Used in a C++ implementation file to complete the declaration of a class
Example:
@code
- IMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow)
+ wxIMPLEMENT_DYNAMIC_CLASS(wxFrame, wxWindow);
wxFrame::wxFrame(void)
{
}
@endcode
*/
-#define IMPLEMENT_DYNAMIC_CLASS( className, baseClassName )
+#define wxIMPLEMENT_DYNAMIC_CLASS( className, baseClassName )
/**
Used in a C++ implementation file to complete the declaration of a class
@header{wx/object.h}
*/
-#define IMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 )
+#define wxIMPLEMENT_DYNAMIC_CLASS2( className, baseClassName1, baseClassName2 )
+
+/**
+ Used in a C++ implementation file to complete the declaration of a class
+ that has run-time type information, and whose instances can be created
+ dynamically. The same as wxIMPLEMENT_DYNAMIC_CLASS().
+
+ @header{wx/object.h}
+*/
+#define wxIMPLEMENT_CLASS( className, baseClassName )
+
+/**
+ Used in a C++ implementation file to complete the declaration of a class
+ that has run-time type information and two base classes, and whose instances
+ can be created dynamically. The same as wxIMPLEMENT_DYNAMIC_CLASS2().
+
+ @header{wx/object.h}
+*/
+#define wxIMPLEMENT_CLASS2( className, baseClassName1, baseClassName2 )
/**
Same as @c const_cast<T>(x) if the compiler supports const cast or @c (T)x for
projects / wxWidgets.git / blobdiff