From a91225b27b4416488d299ef10053bb822e6a9bf4 Mon Sep 17 00:00:00 2001 From: Robert Roebling Date: Wed, 18 Oct 2006 17:23:42 +0000 Subject: [PATCH] [ 1578529 ] better docs for reference-counted objects This already includes the change for wxBitmap, which is not COW yet. git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@42094 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775 --- docs/latex/wx/accel.tex | 6 ++---- docs/latex/wx/bitmap.tex | 10 +++------- docs/latex/wx/brush.tex | 5 ++--- docs/latex/wx/cursor.tex | 5 ++--- docs/latex/wx/font.tex | 7 +++++-- docs/latex/wx/image.tex | 6 ++---- docs/latex/wx/object.tex | 17 +++++++++-------- docs/latex/wx/palette.tex | 5 ++--- docs/latex/wx/pen.tex | 5 ++--- docs/latex/wx/region.tex | 6 ++++-- docs/latex/wx/topics.tex | 4 ++-- docs/latex/wx/tstring.tex | 16 ++-------------- 12 files changed, 37 insertions(+), 55 deletions(-) diff --git a/docs/latex/wx/accel.tex b/docs/latex/wx/accel.tex index 266fa9a83e..304dbb3439 100644 --- a/docs/latex/wx/accel.tex +++ b/docs/latex/wx/accel.tex @@ -119,7 +119,7 @@ Default constructor. \func{}{wxAcceleratorTable}{\param{const wxAcceleratorTable\& }{bitmap}} -Copy constructor. +Copy constructor, uses \helpref{reference counting}{trefcount}. \func{}{wxAcceleratorTable}{\param{int}{ n}, \param{wxAcceleratorEntry}{ entries[]}} @@ -161,9 +161,7 @@ Returns true if the accelerator table is valid. \func{wxAcceleratorTable\& }{operator $=$}{\param{const wxAcceleratorTable\& }{accel}} -Assignment operator. This operator does not copy any data, but instead -passes a pointer to the data in {\it accel} and increments a reference -counter. It is a fast operation. +Assignment operator, using \helpref{reference counting}{trefcount}. \wxheading{Parameters} diff --git a/docs/latex/wx/bitmap.tex b/docs/latex/wx/bitmap.tex index b2c94b7599..57eb5c05d8 100644 --- a/docs/latex/wx/bitmap.tex +++ b/docs/latex/wx/bitmap.tex @@ -38,10 +38,8 @@ Default constructor. \func{}{wxBitmap}{\param{const wxBitmap\& }{bitmap}} -Copy constructor. Note that this does not take a fresh copy of the data, -but instead makes the internal data point to {\it bitmap}'s data. So -changing one bitmap will change the other. To make a real copy, you can -use: +Copy constructor, uses \helpref{reference counting}{trefcount}. +To make a real copy, you can use: \begin{verbatim} wxBitmap newBitmap = oldBitmap.GetSubBitmap( @@ -587,9 +585,7 @@ Sets the width member (does not affect the bitmap data). \func{wxBitmap\& }{operator $=$}{\param{const wxBitmap\& }{bitmap}} -Assignment operator. This operator does not copy any data, but instead -passes a pointer to the data in {\it bitmap} and increments a reference -counter. It is a fast operation. +Assignment operator, using \helpref{reference counting}{trefcount}. \wxheading{Parameters} diff --git a/docs/latex/wx/brush.tex b/docs/latex/wx/brush.tex index 0b3a4502d6..63faaac73e 100644 --- a/docs/latex/wx/brush.tex +++ b/docs/latex/wx/brush.tex @@ -95,7 +95,7 @@ Constructs a stippled brush using a bitmap. \func{}{wxBrush}{\param{const wxBrush\&}{ brush}} -Copy constructor. This uses reference counting so is a cheap operation. +Copy constructor, uses \helpref{reference counting}{trefcount}. \wxheading{Parameters} @@ -293,8 +293,7 @@ Sets the brush style. \func{wxBrush\&}{operator $=$}{\param{const wxBrush\& }{brush}} -Assignment operator, using reference counting. Returns a reference -to `this'. +Assignment operator, using \helpref{reference counting}{trefcount}. \membersection{wxBrush::operator $==$}\label{wxbrushequals} diff --git a/docs/latex/wx/cursor.tex b/docs/latex/wx/cursor.tex index 8821d5775f..a27b660288 100644 --- a/docs/latex/wx/cursor.tex +++ b/docs/latex/wx/cursor.tex @@ -84,7 +84,7 @@ On MacOS if the cursor is larger than 16x16 it is resized and currently only sho \func{}{wxCursor}{\param{const wxCursor\&}{ cursor}} -Copy constructor. This uses reference counting so is a cheap operation. +Copy constructor, uses \helpref{reference counting}{trefcount}. \wxheading{Parameters} @@ -244,8 +244,7 @@ Returns true if cursor data is present. \func{wxCursor\&}{operator $=$}{\param{const wxCursor\& }{cursor}} -Assignment operator, using reference counting. Returns a reference -to `this'. +Assignment operator, using \helpref{reference counting}{trefcount}. \membersection{wxCursor::operator $==$}\label{wxcursorequals} diff --git a/docs/latex/wx/font.tex b/docs/latex/wx/font.tex index f520000102..001deb8209 100644 --- a/docs/latex/wx/font.tex +++ b/docs/latex/wx/font.tex @@ -165,6 +165,10 @@ wxSWISS\_FONT} Default constructor. +\func{}{wxFont}{\param{const wxFont\&}{ font}} + +Copy constructor, uses \helpref{reference counting}{trefcount}. + \func{}{wxFont}{\param{int}{ pointSize}, \param{wxFontFamily}{ family}, \param{int}{ style}, \param{wxFontWeight}{ weight}, \param{const bool}{ underline = false}, \param{const wxString\& }{faceName = ""}, \param{wxFontEncoding }{encoding = wxFONTENCODING\_DEFAULT}} @@ -578,8 +582,7 @@ Sets the font weight. \func{wxFont\&}{operator $=$}{\param{const wxFont\& }{font}} -Assignment operator, using reference counting. Returns a reference -to `this'. +Assignment operator, using \helpref{reference counting}{trefcount}. \membersection{wxFont::operator $==$}\label{wxfontequals} diff --git a/docs/latex/wx/image.tex b/docs/latex/wx/image.tex index b78c101efa..ad817d13c7 100644 --- a/docs/latex/wx/image.tex +++ b/docs/latex/wx/image.tex @@ -95,7 +95,7 @@ Default constructor. \func{}{wxImage}{\param{const wxImage\& }{image}} -Copy constructor. +Copy constructor, uses \helpref{reference counting}{trefcount}. \func{}{wxImage}{\param{const wxBitmap\&}{ bitmap}} @@ -1290,9 +1290,7 @@ data. \func{wxImage\& }{operator $=$}{\param{const wxImage\& }{image}} -Assignment operator. This operator does not copy any data, but instead -passes a pointer to the data in {\it image} and increments a reference -counter. It is a fast operation. +Assignment operator, using \helpref{reference counting}{trefcount}. \wxheading{Parameters} diff --git a/docs/latex/wx/object.tex b/docs/latex/wx/object.tex index c18b6d6646..d7c65cee43 100644 --- a/docs/latex/wx/object.tex +++ b/docs/latex/wx/object.tex @@ -12,8 +12,8 @@ The class contains optional debugging versions of {\bf new} and {\bf delete}, which can help trace memory allocation and deallocation problems. -wxObject can be used to implement reference counted objects, such as -wxPen, wxBitmap and others. +wxObject can be used to implement \helpref{reference counted}{trefcount} objects, +such as wxPen, wxBitmap and others (see \helpref{this list}{refcountlist}). \wxheading{See also} @@ -197,12 +197,6 @@ you will need to cast to your own derived class. \latexignore{\rtfignore{\wxheading{Members}}} -\membersection{wxObjectRefData::m\_count}\label{wxobjectrefdatamcount} - -\member{int}{m\_count} - -Reference count. When this goes to zero during a \helpref{wxObject::UnRef}{wxobjectunref}, an object -can delete the {\bf wxObjectRefData} object. \membersection{wxObjectRefData::wxObjectRefData}\label{wxobjectrefdatactor} @@ -216,4 +210,11 @@ Default constructor. Initialises the {\bf m\_count} member to 1. Destructor. +\membersection{wxObjectRefData::GetRefCount}\label{wxobjectrefdatagetrefcount} + +\constfunc{int}{GetRefCount}{\void} + +Returns the reference count associated with this shared data. +When this goes to zero during a \helpref{wxObject::UnRef}{wxobjectunref}, an object +can delete this {\bf wxObjectRefData} object. diff --git a/docs/latex/wx/palette.tex b/docs/latex/wx/palette.tex index 6e400c8f38..3524bf599f 100644 --- a/docs/latex/wx/palette.tex +++ b/docs/latex/wx/palette.tex @@ -54,7 +54,7 @@ Default constructor. \func{}{wxPalette}{\param{const wxPalette\&}{ palette}} -Copy constructor. This uses reference counting so is a cheap operation. +Copy constructor, uses \helpref{reference counting}{trefcount}. \func{}{wxPalette}{\param{int}{ n}, \param{const unsigned char* }{red},\\ \param{const unsigned char* }{green}, \param{const unsigned char* }{blue}} @@ -180,8 +180,7 @@ Returns true if palette data is present. \func{wxPalette\&}{operator $=$}{\param{const wxPalette\& }{palette}} -Assignment operator, using reference counting. Returns a reference -to `this'. +Assignment operator, using \helpref{reference counting}{trefcount}. \membersection{wxPalette::operator $==$}\label{wxpaletteequals} diff --git a/docs/latex/wx/pen.tex b/docs/latex/wx/pen.tex index 98841425e7..8f39b78099 100644 --- a/docs/latex/wx/pen.tex +++ b/docs/latex/wx/pen.tex @@ -93,7 +93,7 @@ Constructs a stippled pen from a stipple bitmap and a width. \func{}{wxPen}{\param{const wxPen\&}{ pen}} -Copy constructor. This uses reference counting so is a cheap operation. +Copy constructor, uses \helpref{reference counting}{trefcount}. \wxheading{Parameters} @@ -329,8 +329,7 @@ Sets the pen width. \func{wxPen\&}{operator $=$}{\param{const wxPen\& }{pen}} -Assignment operator, using reference counting. Returns a reference -to `this'. +Assignment operator, using \helpref{reference counting}{trefcount}. \membersection{wxPen::operator $==$}\label{wxpenequals} diff --git a/docs/latex/wx/region.tex b/docs/latex/wx/region.tex index 4cc3310907..f12a867b8f 100644 --- a/docs/latex/wx/region.tex +++ b/docs/latex/wx/region.tex @@ -39,7 +39,7 @@ Constructs a rectangular region a wxRect object. \func{}{wxRegion}{\param{const wxRegion\&}{ region}} -Constructs a region by copying another region. +Copy constructor, uses \helpref{reference counting}{trefcount}. \func{}{wxRegion}{\param{size\_t}{ n}, \param{const wxPoint }{*points}, \param{int }{fillStyle = wxWINDING\_RULE}} @@ -260,7 +260,9 @@ for any overlapping areas. The result is stored in this region. \func{void}{operator $=$}{\param{const wxRegion\&}{ region}} -Copies {\it region} by reference counting. +Assignment operator, using \helpref{reference counting}{trefcount}. + + \section{\class{wxRegionIterator}}\label{wxregioniterator} diff --git a/docs/latex/wx/topics.tex b/docs/latex/wx/topics.tex index 0454e8c496..24d95db000 100644 --- a/docs/latex/wx/topics.tex +++ b/docs/latex/wx/topics.tex @@ -4,13 +4,14 @@ This chapter contains a selection of topic overviews. -\input tchanges.tex +%\input tchanges.tex -- deprecated: look at docs/changes.txt instead \input tusage.tex \input tguide.tex \input hworld.tex \input tsamples.tex \input tapp.tex \input truntime.tex +\input trefcount.tex \input tstring.tex \input tbuffer.tex \input tdate.tex @@ -66,4 +67,3 @@ This chapter contains a selection of topic overviews. \input re_syntax.tex \input arc.tex \input backwardcompat.tex - diff --git a/docs/latex/wx/tstring.tex b/docs/latex/wx/tstring.tex index 17acb3070c..fa25faee5e 100644 --- a/docs/latex/wx/tstring.tex +++ b/docs/latex/wx/tstring.tex @@ -167,20 +167,8 @@ vastly better from a performance point of view than a wxObjectArray of wxStrings \subsection{Reference counting and why you shouldn't care about it}\label{wxstringrefcount} -wxString objects use a technique known as {\it copy on write} (COW). This means -that when a string is assigned to another, no copying really takes place: only -the reference count on the shared string data is incremented and both strings -share the same data. - -But as soon as one of the two (or more) strings is modified, the data has to be -copied because the changes to one of the strings shouldn't be seen in the -others. As data copying only happens when the string 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 a string 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. +All considerations for wxObject-derived \helpref{reference counted}{trefcount} objects +are valid also for wxString, even if it does not derive from wxObject. Probably the unique case when you might want to think about reference counting is when a string character is taken from a string which is not a -- 2.45.2