/////////////////////////////////////////////////////////////////////////////
-// Name: trefcount
+// Name: refcount.h
// Purpose: topic overview
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
-/*!
+/**
- @page trefcount_overview Reference counting
+@page overview_refcount Reference Counting
- @ref refcount_overview
- @ref refcountequality_overview
- @ref refcountdestruct_overview
- @ref refcountlist_overview
- @ref object_overview
+@li @ref overview_refcount_ignore
+@li @ref overview_refcount_equality
+@li @ref overview_refcount_destruct
+@li @ref overview_refcount_list
+@li @ref overview_refcount_object
- @section refcount Why you shouldn't care about it
+<hr>
- Many wxWidgets objects use a technique known as @e reference counting, also known
- as @e copy on write (COW).
- This means that when an object is assigned to another, no copying really takes place:
- only the reference count on the shared object data is incremented and both objects
- share the same data (a very fast operation).
- But as soon as one of the two (or more) objects is modified, the data has to be
- copied because the changes to one of the objects shouldn't be seen in the
- others. As data copying only happens when the object is written to, this is
- known as COW.
- What is important to understand is that all this happens absolutely
- transparently to the class users and that whether an object is shared or not
- is not seen from the outside of the class - in any case, the result of any
- operation on it is the same.
- @section refcountequality Object comparison
+@section overview_refcount_ignore Why You Shouldn't Care About It
- The == and != operators of @ref refcountlist_overview
- always do a @c deep comparison.
- This means that the equality operator will return @true if two objects are
- identic and not only if they share the same data.
- Note that wxWidgets follows the @e STL philosophy: when a comparison operator cannot
- be implemented efficiently (like for e.g. wxImage's == operator which would need to
- compare pixel-by-pixel the entire image's data), it's not implemented at all.
- That's why not all reference-counted wxWidgets classes provide comparison operators.
- Also note that if you only need to do a @c shallow comparison between two
- #wxObject-derived classes, you should not use the == and != operators
- but rather the wxObject::IsSameAs function.
+Many wxWidgets objects use a technique known as <em>reference counting</em>,
+also known as <em>copy on write</em> (COW). This means that when an object is
+assigned to another, no copying really takes place. Only the reference count on
+the shared object data is incremented and both objects share the same data (a
+very fast operation).
+But as soon as one of the two (or more) objects is modified, the data has to be
+copied because the changes to one of the objects shouldn't be seen in the
+others. As data copying only happens when the object is written to, this is
+known as COW.
- @section refcountdestruct Object destruction
+What is important to understand is that all this happens absolutely
+transparently to the class users and that whether an object is shared or not is
+not seen from the outside of the class - in any case, the result of any
+operation on it is the same.
- When a COW object destructor is called, it may not delete the data: if it's shared,
- the destructor will just decrement the shared data's reference count without destroying it.
- Only when the destructor of the last object owning the data is called, the data is really
- destroyed. As for all other COW-things, this happens transparently to the class users so
- that you shouldn't care about it.
+@section overview_refcount_equality Object Comparison
- @section refcountlist List of reference-counted wxWidgets classes
+The == and != operators of @ref overview_refcount_list "the reference counted classes"
+always do a <em>deep comparison</em>. This means that the equality operator
+will return @true if two objects are identical and not only if they share the
+same data.
- The following classes in wxWidgets have efficient (i.e. fast) assignment operators
- and copy constructors since they are reference-counted:
- #wxAcceleratorTable
+Note that wxWidgets follows the <em>STL philosophy</em>: when a comparison
+operator cannot be implemented efficiently (like for e.g. wxImage's ==
+operator which would need to compare the entire image's data, pixel-by-pixel),
+it's not implemented at all. That's why not all reference counted classes
+provide comparison operators.
- #wxAnimation
+Also note that if you only need to do a @c shallow comparison between two
+wxObject derived classes, you should not use the == and != operators but
+rather the wxObject::IsSameAs() function.
- #wxBitmap
- #wxBrush
+@section overview_refcount_destruct Object Destruction
- #wxCursor
+When a COW object destructor is called, it may not delete the data: if it's
+shared, the destructor will just decrement the shared data's reference count
+without destroying it. Only when the destructor of the last object owning the
+data is called, the data is really destroyed. Just like all other COW-things,
+this happens transparently to the class users so that you shouldn't care about
+it.
- #wxFont
- #wxIcon
+@section overview_refcount_list List of Reference Counted Classes
- #wxImage
+The following classes in wxWidgets have efficient (i.e. fast) assignment
+operators and copy constructors since they are reference-counted:
- #wxMetafile
+@li wxAcceleratorTable
+@li wxAnimation
+@li wxBitmap
+@li wxBrush
+@li wxCursor
+@li wxFont
+@li wxGraphicsBrush
+@li wxGraphicsContext
+@li wxGraphicsFont
+@li wxGraphicsMatrix
+@li wxGraphicsPath
+@li wxGraphicsPen
+@li wxIcon
+@li wxImage
+@li wxMetafile
+@li wxPalette
+@li wxPen
+@li wxRegion
+@li wxString
+@li wxVariant
+@li wxVariantData
- #wxPalette
+Note that the list above reports the objects which are reference counted in all
+ports of wxWidgets; some ports may use this technique also for other classes.
- #wxPen
+All the objects implement a function @b IsOk() to test if they are referencing valid
+data; when the objects are in uninitialized state, you can only use the @b IsOk() getter;
+trying to call any other getter, e.g. wxBrush::GetStyle() on the ::wxNullBrush object,
+will result in an assert failure in debug builds.
- #wxRegion
- #wxString
+@section overview_refcount_object Making Your Own Reference Counted Class
- #wxVariant
+Reference counting can be implemented easily using wxObject or using
+the intermediate wxRefCounter class directly.
+Alternatively, you can also use the wxObjectDataPtr<T> template.
- #wxVariantData
- Note that the list above reports the objects which are reference-counted in all ports of
- wxWidgets; some ports may use this tecnique also for other classes.
+First, derive a new class from wxRefCounter (or wxObjectRefData when
+using a wxObject derived class) and put the memory-consuming data in it.
- @section wxobjectoverview Make your own reference-counted class
-
- Reference counting can be implemented easily using #wxObject
- and #wxObjectRefData classes. Alternatively, you
- can also use the #wxObjectDataPtrT template.
- First, derive a new class from #wxObjectRefData and
- put there the memory-consuming data.
- Then derive a new class from #wxObject and implement there
- the public interface which will be seen by the user of your class.
- You'll probably want to add a function to your class which does the cast from
- #wxObjectRefData to your class-specific shared data; e.g.:
-
- @code
- MyClassRefData *GetData() const { return wx_static_cast(MyClassRefData*, m_refData); }
- @endcode
-
- in fact, all times you'll need to read the data from your wxObject-derived class,
- you'll need to call such function.
- Very important, all times you need to actually modify the data placed inside your
- wxObject-derived class, you must first call the wxObject::UnShare
- function to be sure that the modifications won't affect other instances which are
- eventually sharing your object's data.
-
- */
+Then derive a new class from wxObject and implement there the public interface
+which will be seen by the user of your class. You'll probably want to add a
+function to your class which does the cast from wxObjectRefData to your
+class-specific shared data. For example:
+@code
+MyClassRefData* GetData() const
+{
+ return wx_static_cast(MyClassRefData*, m_refData);
+}
+@endcode
+
+In fact, any time you need to read the data from your wxObject-derived class,
+you will need to call this function.
+
+@note Any time you need to actually modify the data placed inside your wxObject
+derived class, you must first call the wxObject::UnShare() function to ensure
+that the modifications won't affect other instances which are eventually
+sharing your object's data.
+
+*/
projects / wxWidgets.git / blobdiff