]> git.saurik.com Git - wxWidgets.git/blame - docs/doxygen/overviews/refcount.h
Fix column sorting UI in wxDataViewCtrl under wxOSX.
[wxWidgets.git] / docs / doxygen / overviews / refcount.h
CommitLineData
15b6757b 1/////////////////////////////////////////////////////////////////////////////
72844950 2// Name: refcount.h
15b6757b
FM
3// Purpose: topic overview
4// Author: wxWidgets team
526954c5 5// Licence: wxWindows licence
15b6757b
FM
6/////////////////////////////////////////////////////////////////////////////
7
880efa2a 8/**
36c9828f 9
72844950 10@page overview_refcount Reference Counting
36c9828f 11
831e1028 12@tableofcontents
36c9828f 13
72844950
BP
14Many wxWidgets objects use a technique known as <em>reference counting</em>,
15also known as <em>copy on write</em> (COW). This means that when an object is
16assigned to another, no copying really takes place. Only the reference count on
17the shared object data is incremented and both objects share the same data (a
18very fast operation).
36c9828f 19
72844950
BP
20But as soon as one of the two (or more) objects is modified, the data has to be
21copied because the changes to one of the objects shouldn't be seen in the
22others. As data copying only happens when the object is written to, this is
23known as COW.
36c9828f 24
72844950
BP
25What is important to understand is that all this happens absolutely
26transparently to the class users and that whether an object is shared or not is
27not seen from the outside of the class - in any case, the result of any
28operation on it is the same.
36c9828f 29
36c9828f 30
72844950 31@section overview_refcount_equality Object Comparison
36c9828f 32
3ed3a1c8
BP
33The == and != operators of @ref overview_refcount_list "the reference counted classes"
34always do a <em>deep comparison</em>. This means that the equality operator
35will return @true if two objects are identical and not only if they share the
36same data.
36c9828f 37
72844950 38Note that wxWidgets follows the <em>STL philosophy</em>: when a comparison
4c51a665 39operator cannot be implemented efficiently (like for e.g. wxImage's ==
72844950
BP
40operator which would need to compare the entire image's data, pixel-by-pixel),
41it's not implemented at all. That's why not all reference counted classes
42provide comparison operators.
36c9828f 43
72844950 44Also note that if you only need to do a @c shallow comparison between two
7442b5ee 45wxObject derived classes, you should not use the == and != operators but
f0a9a84c 46rather the wxObject::IsSameAs() function.
36c9828f 47
36c9828f 48
72844950 49@section overview_refcount_destruct Object Destruction
36c9828f 50
72844950
BP
51When a COW object destructor is called, it may not delete the data: if it's
52shared, the destructor will just decrement the shared data's reference count
53without destroying it. Only when the destructor of the last object owning the
54data is called, the data is really destroyed. Just like all other COW-things,
55this happens transparently to the class users so that you shouldn't care about
56it.
36c9828f 57
36c9828f 58
72844950 59@section overview_refcount_list List of Reference Counted Classes
36c9828f 60
72844950
BP
61The following classes in wxWidgets have efficient (i.e. fast) assignment
62operators and copy constructors since they are reference-counted:
36c9828f 63
7442b5ee
BP
64@li wxAcceleratorTable
65@li wxAnimation
66@li wxBitmap
67@li wxBrush
68@li wxCursor
69@li wxFont
660b61d7
FM
70@li wxGraphicsBrush
71@li wxGraphicsContext
72@li wxGraphicsFont
73@li wxGraphicsMatrix
74@li wxGraphicsPath
75@li wxGraphicsPen
7442b5ee
BP
76@li wxIcon
77@li wxImage
78@li wxMetafile
79@li wxPalette
80@li wxPen
81@li wxRegion
82@li wxString
83@li wxVariant
84@li wxVariantData
36c9828f 85
72844950
BP
86Note that the list above reports the objects which are reference counted in all
87ports of wxWidgets; some ports may use this technique also for other classes.
36c9828f 88
831e1028
BP
89All the objects implement a function @b IsOk() to test if they are referencing
90valid data; when the objects are in uninitialized state, you can only use the
91@b IsOk() getter; trying to call any other getter, e.g. wxBrush::GetStyle() on
92the ::wxNullBrush object, will result in an assert failure in debug builds.
f0a9a84c 93
36c9828f 94
72844950 95@section overview_refcount_object Making Your Own Reference Counted Class
36c9828f 96
831e1028
BP
97Reference counting can be implemented easily using wxObject or using the
98intermediate wxRefCounter class directly. Alternatively, you can also use the
99wxObjectDataPtr<T> template.
36c9828f 100
831e1028
BP
101First, derive a new class from wxRefCounter (or wxObjectRefData when using a
102wxObject derived class) and put the memory-consuming data in it.
36c9828f 103
7442b5ee 104Then derive a new class from wxObject and implement there the public interface
72844950 105which will be seen by the user of your class. You'll probably want to add a
7442b5ee 106function to your class which does the cast from wxObjectRefData to your
72844950 107class-specific shared data. For example:
36c9828f 108
72844950
BP
109@code
110MyClassRefData* GetData() const
111{
112 return wx_static_cast(MyClassRefData*, m_refData);
113}
114@endcode
36c9828f 115
72844950
BP
116In fact, any time you need to read the data from your wxObject-derived class,
117you will need to call this function.
36c9828f 118
72844950 119@note Any time you need to actually modify the data placed inside your wxObject
3ed3a1c8 120derived class, you must first call the wxObject::UnShare() function to ensure
72844950
BP
121that the modifications won't affect other instances which are eventually
122sharing your object's data.
36c9828f 123
72844950 124*/