[wxWidgets.git] / docs / latex / wx / trefcount.tex

\section{Reference counting}\label{trefcount}

\subsection{Reference counting and 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).
This means that when an object is assigned to another, no copying really takes place:
only the reference count on the shared object data is incremented and both objects
share the same data (a very fast operation).

But as soon as one of the two (or more) objects is modified, the data has to be
copied because the changes to one of the objects shouldn't be seen in the
others. As data copying only happens when the object 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 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{List of reference-counted wxWidgets classes}\label{refcountlist}

The following classes in wxWidgets have efficient (i.e. fast) assignment operators
and copy constructors since they are reference-counted:

\helpref{wxAcceleratorTable}{wxacceleratortable}\\
\helpref{wxBrush}{wxbrush}\\
\helpref{wxCursor}{wxcursor}\\
\helpref{wxFont}{wxfont}\\
\helpref{wxImage}{wximage}\\
\helpref{wxMetafile}{wxmetafile}\\
\helpref{wxPalette}{wxpalette}\\
\helpref{wxPen}{wxpen}\\
\helpref{wxRegion}{wxregion}\\
\helpref{wxRegionIterator}{wxregioniterator}\\
\helpref{wxString}{wxstring}


\subsection{Make your own reference-counted class}\label{wxobjectoverview}

Reference counting can be implemented easily using \helpref{wxObject}{wxobject}
and \helpref{wxObjectRefData}{wxobjectrefdata} classes.

First, derive a new class from \helpref{wxObjectRefData}{wxobjectrefdata} and
put there the memory-consuming data.

Then derive a new class from \helpref{wxObject}{wxobject} and implement there
the public interface which will be seen by the user of your class.
You'll probably want to add a function to your class which does the cast from
\helpref{wxObjectRefData}{wxobjectrefdata} to your class-specific shared data; e.g.:

\begin{verbatim}
    MyClassRefData *GetData() const   { return wx_static_cast(MyClassRefData*, m_refData); }
\end{verbatim}

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}
function to be sure that the modifications won't affect other instances which are
eventually sharing your object's data.
Commit	Line	Data
40131743 RR	1	\section{Reference counting}\label{trefcount}
	2
	3	\subsection{Reference counting and why you shouldn't care about it}\label{refcount}
	4
	5	Many wxWidgets objects use a technique known as \it{reference counting}, also known
	6	as {\it copy on write} (COW).
	7	This means that when an object is assigned to another, no copying really takes place:
	8	only the reference count on the shared object data is incremented and both objects
	9	share the same data (a very fast operation).
	10
	11	But as soon as one of the two (or more) objects is modified, the data has to be
	12	copied because the changes to one of the objects shouldn't be seen in the
	13	others. As data copying only happens when the object is written to, this is
	14	known as COW.
	15
	16	What is important to understand is that all this happens absolutely
	17	transparently to the class users and that whether an object is shared or not
	18	is not seen from the outside of the class - in any case, the result of any
	19	operation on it is the same.
	20
	21
	22
	23	\subsection{List of reference-counted wxWidgets classes}\label{refcountlist}
	24
	25	The following classes in wxWidgets have efficient (i.e. fast) assignment operators
	26	and copy constructors since they are reference-counted:
	27
	28	\helpref{wxAcceleratorTable}{wxacceleratortable}\\
	29	\helpref{wxBrush}{wxbrush}\\
	30	\helpref{wxCursor}{wxcursor}\\
	31	\helpref{wxFont}{wxfont}\\
	32	\helpref{wxImage}{wximage}\\
	33	\helpref{wxMetafile}{wxmetafile}\\
	34	\helpref{wxPalette}{wxpalette}\\
	35	\helpref{wxPen}{wxpen}\\
	36	\helpref{wxRegion}{wxregion}\\
	37	\helpref{wxRegionIterator}{wxregioniterator}\\
	38	\helpref{wxString}{wxstring}
	39
	40
	41
	42	\subsection{Make your own reference-counted class}\label{wxobjectoverview}
	43
	44	Reference counting can be implemented easily using \helpref{wxObject}{wxobject}
	45	and \helpref{wxObjectRefData}{wxobjectrefdata} classes.
	46
	47	First, derive a new class from \helpref{wxObjectRefData}{wxobjectrefdata} and
	48	put there the memory-consuming data.
	49
	50	Then derive a new class from \helpref{wxObject}{wxobject} and implement there
	51	the public interface which will be seen by the user of your class.
	52	You'll probably want to add a function to your class which does the cast from
	53	\helpref{wxObjectRefData}{wxobjectrefdata} to your class-specific shared data; e.g.:
	54
	55	\begin{verbatim}
	56	MyClassRefData GetData() const { return wx_static_cast(MyClassRefData, m_refData); }
	57	\end{verbatim}
	58
	59	in fact, all times you'll need to read the data from your wxObject-derived class,
	60	you'll need to call such function.
	61
	62	Very important, all times you need to actually modify the data placed inside your
	63	wxObject-derived class, you must first call the \helpref{wxObject::UnShare}{wxobjectunshare}
	64	function to be sure that the modifications won't affect other instances which are
65	eventually sharing your object's data.
66