]>
Commit | Line | Data |
---|---|---|
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 |
14 | Many wxWidgets objects use a technique known as <em>reference counting</em>, |
15 | also known as <em>copy on write</em> (COW). This means that when an object is | |
16 | assigned to another, no copying really takes place. Only the reference count on | |
17 | the shared object data is incremented and both objects share the same data (a | |
18 | very fast operation). | |
36c9828f | 19 | |
72844950 BP |
20 | But as soon as one of the two (or more) objects is modified, the data has to be |
21 | copied because the changes to one of the objects shouldn't be seen in the | |
22 | others. As data copying only happens when the object is written to, this is | |
23 | known as COW. | |
36c9828f | 24 | |
72844950 BP |
25 | What is important to understand is that all this happens absolutely |
26 | transparently to the class users and that whether an object is shared or not is | |
27 | not seen from the outside of the class - in any case, the result of any | |
28 | operation on it is the same. | |
36c9828f | 29 | |
36c9828f | 30 | |
72844950 | 31 | @section overview_refcount_equality Object Comparison |
36c9828f | 32 | |
3ed3a1c8 BP |
33 | The == and != operators of @ref overview_refcount_list "the reference counted classes" |
34 | always do a <em>deep comparison</em>. This means that the equality operator | |
35 | will return @true if two objects are identical and not only if they share the | |
36 | same data. | |
36c9828f | 37 | |
72844950 | 38 | Note that wxWidgets follows the <em>STL philosophy</em>: when a comparison |
4c51a665 | 39 | operator cannot be implemented efficiently (like for e.g. wxImage's == |
72844950 BP |
40 | operator which would need to compare the entire image's data, pixel-by-pixel), |
41 | it's not implemented at all. That's why not all reference counted classes | |
42 | provide comparison operators. | |
36c9828f | 43 | |
72844950 | 44 | Also note that if you only need to do a @c shallow comparison between two |
7442b5ee | 45 | wxObject derived classes, you should not use the == and != operators but |
f0a9a84c | 46 | rather the wxObject::IsSameAs() function. |
36c9828f | 47 | |
36c9828f | 48 | |
72844950 | 49 | @section overview_refcount_destruct Object Destruction |
36c9828f | 50 | |
72844950 BP |
51 | When a COW object destructor is called, it may not delete the data: if it's |
52 | shared, the destructor will just decrement the shared data's reference count | |
53 | without destroying it. Only when the destructor of the last object owning the | |
54 | data is called, the data is really destroyed. Just like all other COW-things, | |
55 | this happens transparently to the class users so that you shouldn't care about | |
56 | it. | |
36c9828f | 57 | |
36c9828f | 58 | |
72844950 | 59 | @section overview_refcount_list List of Reference Counted Classes |
36c9828f | 60 | |
72844950 BP |
61 | The following classes in wxWidgets have efficient (i.e. fast) assignment |
62 | operators 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 |
86 | Note that the list above reports the objects which are reference counted in all |
87 | ports of wxWidgets; some ports may use this technique also for other classes. | |
36c9828f | 88 | |
831e1028 BP |
89 | All the objects implement a function @b IsOk() to test if they are referencing |
90 | valid 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 | |
92 | the ::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 |
97 | Reference counting can be implemented easily using wxObject or using the |
98 | intermediate wxRefCounter class directly. Alternatively, you can also use the | |
99 | wxObjectDataPtr<T> template. | |
36c9828f | 100 | |
831e1028 BP |
101 | First, derive a new class from wxRefCounter (or wxObjectRefData when using a |
102 | wxObject derived class) and put the memory-consuming data in it. | |
36c9828f | 103 | |
7442b5ee | 104 | Then derive a new class from wxObject and implement there the public interface |
72844950 | 105 | which will be seen by the user of your class. You'll probably want to add a |
7442b5ee | 106 | function to your class which does the cast from wxObjectRefData to your |
72844950 | 107 | class-specific shared data. For example: |
36c9828f | 108 | |
72844950 BP |
109 | @code |
110 | MyClassRefData* GetData() const | |
111 | { | |
112 | return wx_static_cast(MyClassRefData*, m_refData); | |
113 | } | |
114 | @endcode | |
36c9828f | 115 | |
72844950 BP |
116 | In fact, any time you need to read the data from your wxObject-derived class, |
117 | you 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 | 120 | derived class, you must first call the wxObject::UnShare() function to ensure |
72844950 BP |
121 | that the modifications won't affect other instances which are eventually |
122 | sharing your object's data. | |
36c9828f | 123 | |
72844950 | 124 | */ |