Amebis/wxWidgets
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

COW cleanup patch (1583966):

Browse Source 
1. perform deep comparison for the classes for which it makes sense in the
   ports where this wasn't done yet
2. remove (shallow) comparison operators for the classes for which it does
   not make sense (such as wxBitmap)
3. makes wxBitmap use COW on all ports
4. adds wxObject::IsRefTo()
5. centralizes and improves COW docs


git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@42752 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
Vadim Zeitlin
2006-10-30 19:26:48 +00:00
parent 8d1517cef2
commit 55ccdb93e4
102 changed files with 310 additions and 639 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
docs/latex/wx/accel.tex
View File

@@ -85,6 +85,12 @@ initial accelerator table for a window.
<wx/accel.h>
\wxheading{Predefined objects}
Objects:
{\bf wxNullAcceleratorTable}
\wxheading{Example}
{\small%
@@ -150,6 +156,7 @@ and cmd values like you would construct wxAcceleratorEntry objects with.}
\func{}{\destruct{wxAcceleratorTable}}{\void}
Destroys the wxAcceleratorTable object.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\membersection{wxAcceleratorTable::IsOk}\label{wxacceleratortableisok}
@@ -170,35 +177,3 @@ Assignment operator, using \helpref{reference counting}{trefcount}.
\wxheading{Return value}
Returns reference to this object.
\membersection{wxAcceleratorTable::operator $==$}\label{wxacceleratortableequal}
\func{bool}{operator $==$}{\param{const wxAcceleratorTable\& }{accel}}
Equality operator. This operator tests whether the internal data pointers are
equal (a fast test).
\wxheading{Parameters}
\docparam{accel}{Accelerator table to compare with}
\wxheading{Return value}
Returns true if the accelerator tables were effectively equal, false otherwise.
\membersection{wxAcceleratorTable::operator $!=$}\label{wxacceleratortablenotequal}
\func{bool}{operator $!=$}{\param{const wxAcceleratorTable\& }{accel}}
Inequality operator. This operator tests whether the internal data pointers are
unequal (a fast test).
\wxheading{Parameters}
\docparam{accel}{Accelerator table to compare with}
\wxheading{Return value}
Returns true if the accelerator tables were unequal, false otherwise.

16
docs/latex/wx/animation.tex
View File

@@ -44,8 +44,7 @@ Default constructor.
\func{}{wxAnimation}{\param{const wxAnimation\& }{anim}}
Copy constructor.
wxAnimation objects are reference counted so that this operation is very fast.
Copy constructor, uses \helpref{reference counting}{trefcount}.
\func{}{wxAnimation}{\param{const wxString\& }{name}, \param{wxAnimationType}{ type = wxANIMATION\_TYPE\_ANY}}
@@ -60,10 +59,8 @@ Loads an animation from a file.
\func{}{\destruct{wxAnimation}}{\void}
Destroys the wxAnimation object and possibly the underlying animation data.
Because reference counting is used, the animation may not actually be
destroyed at this point - only when the reference count is zero will the
data be deleted.
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\membersection{wxAnimation::GetDelay}\label{wxanimationgetdelay}
@@ -151,3 +148,10 @@ Loads an animation from a file.
\true if the operation succeeded, \false otherwise.
\membersection{wxAnimation::operator $=$}\label{wxanimationassignment}
\func{wxAnimation\&}{operator $=$}{\param{const wxAnimation\& }{brush}}
Assignment operator, using \helpref{reference counting}{trefcount}.

35
docs/latex/wx/bitmap.tex
View File

@@ -206,10 +206,8 @@ wxImage to a wxBitmap.}
\func{}{\destruct{wxBitmap}}{\void}
Destroys the wxBitmap object and possibly the underlying bitmap data.
Because reference counting is used, the bitmap may not actually be
destroyed at this point - only when the reference count is zero will the
data be deleted.
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
If the application omits to delete the bitmap explicitly, the bitmap will be
destroyed automatically by wxWidgets when the application exits.
@@ -595,33 +593,4 @@ Assignment operator, using \helpref{reference counting}{trefcount}.
Returns 'this' object.
\membersection{wxBitmap::operator $==$}\label{wxbitmapequal}
\func{bool}{operator $==$}{\param{const wxBitmap\& }{bitmap}}
Equality operator. This operator tests whether the internal data pointers are
equal (a fast test).
\wxheading{Parameters}
\docparam{bitmap}{Bitmap to compare with 'this'}
\wxheading{Return value}
Returns true if the bitmaps were effectively equal, false otherwise.
\membersection{wxBitmap::operator $!=$}\label{wxbitmapnotequal}
\func{bool}{operator $!=$}{\param{const wxBitmap\& }{bitmap}}
Inequality operator. This operator tests whether the internal data pointers are
unequal (a fast test).
\wxheading{Parameters}
\docparam{bitmap}{Bitmap to compare with 'this'}
\wxheading{Return value}
Returns true if the bitmaps were unequal, false otherwise.

15
docs/latex/wx/brush.tex
View File

@@ -135,12 +135,10 @@ If a stipple brush is created, the brush style will be set to wxSTIPPLE.
\func{}{\destruct{wxBrush}}{\void}
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\wxheading{Remarks}
The destructor may not delete the underlying brush object of the native windowing
system, since wxBrush uses a reference counting system for efficiency.
Although all remaining brushes are deleted when the application exits,
the application should try to clean up all brushes itself. This is because
wxWidgets cannot know if a pointer to the brush object is stored in an
@@ -300,18 +298,17 @@ Assignment operator, using \helpref{reference counting}{trefcount}.
\func{bool}{operator $==$}{\param{const wxBrush\& }{brush}}
Equality operator. Two brushes are equal if they contain pointers
to the same underlying brush data. It does not compare each attribute,
so two independently-created brushes using the same parameters will
fail the test.
Equality operator.
See \helpref{reference-counted object comparison}{refcountequality} for more info.
\membersection{wxBrush::operator $!=$}\label{wxbrushnotequals}
\func{bool}{operator $!=$}{\param{const wxBrush\& }{brush}}
Inequality operator. Two brushes are not equal if they contain pointers
to different underlying brush data. It does not compare each attribute.
Inequality operator.
See \helpref{reference-counted object comparison}{refcountequality} for more info.
\section{\class{wxBrushList}}\label{wxbrushlist}

22
docs/latex/wx/cursor.tex
View File

@@ -229,7 +229,10 @@ wxCursor down_cursor = wxCursor(down_bits, 32, 32,
\func{}{\destruct{wxCursor}}{\void}
Destroys the cursor. A cursor can be reused for more
Destroys the cursor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
A cursor can be reused for more
than one window, and does not get destroyed when the window is
destroyed. wxWidgets destroys all cursors on application exit, although
it is best to clean them up explicitly.
@@ -246,20 +249,3 @@ Returns true if cursor data is present.
Assignment operator, using \helpref{reference counting}{trefcount}.
\membersection{wxCursor::operator $==$}\label{wxcursorequals}
\func{bool}{operator $==$}{\param{const wxCursor\& }{cursor}}
Equality operator. Two cursors are equal if they contain pointers
to the same underlying cursor data. It does not compare each attribute,
so two independently-created cursors using the same parameters will
fail the test.
\membersection{wxCursor::operator $!=$}\label{wxcursornotequals}
\func{bool}{operator $!=$}{\param{const wxCursor\& }{cursor}}
Inequality operator. Two cursors are not equal if they contain pointers
to different underlying cursor data. It does not compare each attribute.

14
docs/latex/wx/font.tex
View File

@@ -248,12 +248,10 @@ and \helpref{wxDC::GetTextExtent}{wxdcgettextextent}.
\func{}{\destruct{wxFont}}{\void}
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\wxheading{Remarks}
The destructor may not delete the underlying font object of the native windowing
system, since wxFont uses a reference counting system for efficiency.
Although all remaining fonts are deleted when the application exits,
the application should try to clean up all fonts itself. This is because
wxWidgets cannot know if a pointer to the font object is stored in an
@@ -589,16 +587,14 @@ Assignment operator, using \helpref{reference counting}{trefcount}.
\func{bool}{operator $==$}{\param{const wxFont\& }{font}}
Equality operator. Two fonts are equal if they contain pointers
to the same underlying font data. It does not compare each attribute,
so two independently-created fonts using the same parameters will
fail the test.
Equality operator.
See \helpref{reference-counted object comparison}{refcountequality} for more info.
\membersection{wxFont::operator $!=$}\label{wxfontnotequals}
\func{bool}{operator $!=$}{\param{const wxFont\& }{font}}
Inequality operator. Two fonts are not equal if they contain pointers
to different underlying font data. It does not compare each attribute.
Inequality operator.
See \helpref{reference-counted object comparison}{refcountequality} for more info.

40
docs/latex/wx/icon.tex
View File

@@ -212,10 +212,8 @@ must have mask colour set.
\func{}{\destruct{wxIcon}}{\void}
Destroys the wxIcon object and possibly the underlying icon data.
Because reference counting is used, the icon may not actually be
destroyed at this point - only when the reference count is zero will the
data be deleted.
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
If the application omits to delete the icon explicitly, the icon will be
destroyed automatically by wxWidgets when the application exits.
@@ -355,9 +353,7 @@ Sets the width member (does not affect the icon data).
\func{wxIcon\& }{operator $=$}{\param{const wxIcon\& }{icon}}
Assignment operator. This operator does not copy any data, but instead
passes a pointer to the data in {\it icon} and increments a reference
counter. It is a fast operation.
Assignment operator, using \helpref{reference counting}{trefcount}.
\wxheading{Parameters}
@@ -367,34 +363,4 @@ counter. It is a fast operation.
Returns 'this' object.
\membersection{wxIcon::operator $==$}\label{wxiconequal}
\func{bool}{operator $==$}{\param{const wxIcon\& }{icon}}
Equality operator. This operator tests whether the internal data pointers are
equal (a fast test).
\wxheading{Parameters}
\docparam{icon}{Icon to compare with 'this'}
\wxheading{Return value}
Returns true if the icons were effectively equal, false otherwise.
\membersection{wxIcon::operator $!=$}\label{wxiconnotequal}
\func{bool}{operator $!=$}{\param{const wxIcon\& }{icon}}
Inequality operator. This operator tests whether the internal data pointers are
unequal (a fast test).
\wxheading{Parameters}
\docparam{icon}{Icon to compare with 'this'}
\wxheading{Return value}
Returns true if the icons were unequal, false otherwise.

31
docs/latex/wx/image.tex
View File

@@ -224,6 +224,7 @@ platform-dependent bitmap}
\func{}{\destruct{wxImage}}{\void}
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\membersection{wxImage::AddHandler}\label{wximageaddhandler}
@@ -1300,36 +1301,6 @@ Assignment operator, using \helpref{reference counting}{trefcount}.
Returns 'this' object.
\membersection{wxImage::operator $==$}\label{wximageequal}
\constfunc{bool}{operator $==$}{\param{const wxImage\& }{image}}
Equality operator. This operator tests whether the internal data pointers are
equal (a fast test).
\wxheading{Parameters}
\docparam{image}{Image to compare with 'this'}
\wxheading{Return value}
Returns true if the images were effectively equal, false otherwise.
\membersection{wxImage::operator $!=$}\label{wximagenotequal}
\constfunc{bool}{operator $!=$}{\param{const wxImage\& }{image}}
Inequality operator. This operator tests whether the internal data pointers are
unequal (a fast test).
\wxheading{Parameters}
\docparam{image}{Image to compare with 'this'}
\wxheading{Return value}
Returns true if the images were unequal, false otherwise.
\section{\class{wxImageHandler}}\label{wximagehandler}

1
docs/latex/wx/metafile.tex
View File

@@ -33,6 +33,7 @@ using the \helpref{wxMetafile:IsOk}{wxmetafileisok} member.
\func{}{\destruct{wxMetafile}}{\void}
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\membersection{wxMetafile::IsOk}\label{wxmetafileisok}

18
docs/latex/wx/object.tex
View File

@@ -116,6 +116,13 @@ this one or is derived from it.
bool tmp = obj->IsKindOf(CLASSINFO(wxFrame));
\end{verbatim}
\membersection{wxObject::IsRefTo}\label{wxobjectisrefto}
\func{bool}{IsRefTo}{\param{const wxObject *}{ obj}}
Returns \true if this object is referencing the \arg{obj}'s data.
Note that this function only does a {\tt shallow} comparison.
\membersection{wxObject::Ref}\label{wxobjectref}
\func{void}{Ref}{\param{const wxObject\& }{clone}}
@@ -165,6 +172,17 @@ The {\bf m\_refData} member is set to NULL.
\helpref{wxObject::SetRefData}{wxobjectsetrefdata}, \helpref{wxObject::GetRefData}{wxobjectgetrefdata},\rtfsp
\helpref{wxObjectRefData}{wxobjectrefdata}
\membersection{wxObject::UnShare}\label{wxobjectunshare}
\func{void}{UnShare}{\void}
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.
\membersection{wxObject::operator new}\label{wxobjectnew}
\func{void *}{new}{\param{size\_t }{size}, \param{const wxString\& }{filename = NULL}, \param{int}{ lineNum = 0}}

17
docs/latex/wx/palette.tex
View File

@@ -86,6 +86,7 @@ red, blue or green component.
\func{}{\destruct{wxPalette}}{\void}
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\membersection{wxPalette::Create}\label{wxpalettecreate}
@@ -182,19 +183,3 @@ Returns true if palette data is present.
Assignment operator, using \helpref{reference counting}{trefcount}.
\membersection{wxPalette::operator $==$}\label{wxpaletteequals}
\func{bool}{operator $==$}{\param{const wxPalette\& }{palette}}
Equality operator. Two palettes are equal if they contain pointers
to the same underlying palette data. It does not compare each attribute,
so two independently-created palettes using the same parameters will
fail the test.
\membersection{wxPalette::operator $!=$}\label{wxpalettenotequals}
\func{bool}{operator $!=$}{\param{const wxPalette\& }{palette}}
Inequality operator. Two palettes are not equal if they contain pointers
to different underlying palette data. It does not compare each attribute.

14
docs/latex/wx/pen.tex
View File

@@ -154,12 +154,10 @@ is found in the colour database.
\func{}{\destruct{wxPen}}{\void}
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\wxheading{Remarks}
The destructor may not delete the underlying pen object of the native windowing
system, since wxBrush uses a reference counting system for efficiency.
Although all remaining pens are deleted when the application exits,
the application should try to clean up all pens itself. This is because
wxWidgets cannot know if a pointer to the pen object is stored in an
@@ -335,17 +333,15 @@ Assignment operator, using \helpref{reference counting}{trefcount}.
\func{bool}{operator $==$}{\param{const wxPen\& }{pen}}
Equality operator. Two pens are equal if they contain pointers
to the same underlying pen data. It does not compare each attribute,
so two independently-created pens using the same parameters will
fail the test.
Equality operator.
See \helpref{reference-counted object comparison}{refcountequality} for more info.
\membersection{wxPen::operator $!=$}\label{wxpennotequals}
\func{bool}{operator $!=$}{\param{const wxPen\& }{pen}}
Inequality operator. Two pens are not equal if they contain pointers
to different underlying pen data. It does not compare each attribute.
Inequality operator.
See \helpref{reference-counted object comparison}{refcountequality} for more info.
\section{\class{wxPenList}}\label{wxpenlist}

1
docs/latex/wx/region.tex
View File

@@ -65,6 +65,7 @@ Constructs a region using the non-transparent pixels of a bitmap. See
\func{}{\destruct{wxRegion}}{\void}
Destructor.
See \helpref{reference-counted object destruction}{refcountdestruct} for more info.
\membersection{wxRegion::Clear}\label{wxregionclear}

36
docs/latex/wx/trefcount.tex
View File

@@ -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).
@@ -19,22 +19,54 @@ is not seen from the outside of the class - in any case, the result of any
operation on it is the same.
\subsection{List of reference-counted wxWidgets classes}\label{refcountlist}
\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::IsRefTo}{wxobjectisrefto} 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.
The following classes in wxWidgets have efficient (i.e. fast) assignment operators
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}
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}