Type: info
Title: Helper template for copy-on-write (COW) pattern
Posted by: [EMAIL PROTECTED]
Affected: o3tl
Effective from: SRC680_m177
*Summary*
--------
+#include <o3tl/cow_wrapper.hxx>
+template<T,P> class o3tl::cow_wrapper
*Description*
-------------
Effective SRC680_m177, a helper template is available to ease usage of
the copy-on-write (COW) pattern in C++. It's contained in the new
module o3tl (shorthand for OOo template lib), which is slated to
contain some more pure template code over time (which should ideally
be independent from any other OOo module, except, maybe, sal).
To quote from the docs:
"This template provides copy-on-write semantics for the wrapped type:
when copying, the operation is performed shallow, i.e. different
cow_wrapper objects share the same underlying instance. Only when
accessing the underlying object via non-const methods, a unique copy
is provided.
The type parameter <code>T</code> must satisfy the following
requirements: it must be default-constructible, copyable (it need not
be assignable), and be of non-reference type. Note that, despite the
fact that this template provides access to the wrapped type via
pointer-like methods (<code>operator->()</code> and
<code>operator*()</code>), it does <em>not</em> work like e.g. the
boost pointer wrappers (shared_ptr, scoped_ptr, etc.). Internally, the
cow_wrapper holds a by-value instance of the wrapped object. This is
to avoid one additional heap allocation, and providing access via
<code>operator->()</code>/<code>operator*()</code> is because
<code>operator.()</code> cannot be overridden.
Regarding thread safety: this wrapper is <em>not</em> thread-safe per
se, because cow_wrapper has no way of syncronizing the potentially
many different cow_wrapper instances, that reference a single shared
value_type instance. That said, when passing
<code>ThreadSafeRefCountingPolicy</code> as the <code>MTPolicy</code>
parameter, accessing a thread-safe pointee through multiple
cow_wrapper instances might be thread-safe, if the individual pointee
methods are thread-safe, <em>including</em> pointee's copy
constructor. Any wrapped object that needs external synchronisation
(e.g. via an external mutex, which arbitrates access to object
methods, and can be held across multiple object method calls) cannot
easily be dealt with in a thread-safe way, because, as noted, objects
are shared behind the client's back.
If one wants to use the pimpl idiom together with cow_wrapper
(i.e. put an opaque type into the cow_wrapper), then <em>all<em>
methods in the surrounding class needs to be non-inline
(<em>including</em> destructor, copy constructor and assignment
operator). Not conforming to this requirement will result in a compile
error."
Example:
<pre>
class cow_wrapper_client_impl;
class cow_wrapper_client
{
public:
cow_wrapper_client();
cow_wrapper_client( const cow_wrapper_client& );
~cow_wrapper_client();
cow_wrapper_client& operator=( const cow_wrapper_client& );
void modify( int nVal );
int queryUnmodified() const;
private:
otl::cow_wrapper< cow_wrapper_client_impl > maImpl;
};
</pre>
and the implementation file would look like this:
<pre>
class cow_wrapper_client_impl
{
public:
void setValue( int nVal ) { mnValue = nVal; }
int getValue() const { return mnValue; }
private:
int mnValue;
}
cow_wrapper_client::cow_wrapper_client() :
maImpl()
{
}
cow_wrapper_client::cow_wrapper_client( const cow_wrapper_client& rSrc ) :
maImpl( rSrc.maImpl )
{
}
cow_wrapper_client::~cow_wrapper_client()
{
}
cow_wrapper_client& cow_wrapper_client::operator=( const
cow_wrapper_client& rSrc )
{
maImpl = rSrc.maImpl;
return *this;
}
void cow_wrapper_client::modify( int nVal )
{
maImpl->setValue( nVal );
}
void cow_wrapper_client::queryUnmodified() const
{
return maImpl->getValue();
}
</pre>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
