X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/40131743c6b71881ec36f206f88fa2932c36925b..81c882b613b5d99ddb1e5ab69fcd7ebccc287025:/docs/latex/wx/trefcount.tex diff --git a/docs/latex/wx/trefcount.tex b/docs/latex/wx/trefcount.tex index a5f9592c0f..d240a690e3 100644 --- a/docs/latex/wx/trefcount.tex +++ b/docs/latex/wx/trefcount.tex @@ -1,6 +1,6 @@ \section{Reference counting}\label{trefcount} -\subsection{Reference counting and why you shouldn't care about it}\label{refcount} +\subsection{Why you shouldn't care about it}\label{refcount} Many wxWidgets objects use a technique known as \it{reference counting}, also known as {\it copy on write} (COW). @@ -18,6 +18,33 @@ 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. +\subsection{Object comparison}\label{refcountequality} + +The $==$ and $!=$ operators of \helpref{wxWidgets COW objects}{refcountlist} +always do a {\tt 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 {\it 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 {\tt shallow} comparison between two +\helpref{wxObject}{wxobject}-derived classes, you should not use the $==$ and $!=$ operators +but rather the \helpref{wxObject::IsSameAs}{wxobjectissameas} function. + + +\subsection{Object destruction}\label{refcountdestruct} + +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. \subsection{List of reference-counted wxWidgets classes}\label{refcountlist} @@ -26,19 +53,23 @@ The following classes in wxWidgets have efficient (i.e. fast) assignment operato and copy constructors since they are reference-counted: \helpref{wxAcceleratorTable}{wxacceleratortable}\\ +\helpref{wxAnimation}{wxanimation}\\ +\helpref{wxBitmap}{wxbitmap}\\ \helpref{wxBrush}{wxbrush}\\ \helpref{wxCursor}{wxcursor}\\ \helpref{wxFont}{wxfont}\\ +\helpref{wxIcon}{wxicon}\\ \helpref{wxImage}{wximage}\\ \helpref{wxMetafile}{wxmetafile}\\ \helpref{wxPalette}{wxpalette}\\ \helpref{wxPen}{wxpen}\\ \helpref{wxRegion}{wxregion}\\ -\helpref{wxRegionIterator}{wxregioniterator}\\ -\helpref{wxString}{wxstring} - - +\helpref{wxString}{wxstring}\\ +\helpref{wxVariant}{wxvariant}\\ +\helpref{wxVariantData}{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. \subsection{Make your own reference-counted class}\label{wxobjectoverview} Reference counting can be implemented easily using \helpref{wxObject}{wxobject} @@ -60,7 +91,7 @@ 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 \helpref{wxObject::UnShare}{wxobjectunshare} +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.