Logo Search packages:      
Sourcecode: virtualbox-ose version File versions

util::Shareable< D, Extra > Class Template Reference

#include <Shareable.h>

Inheritance diagram for util::Shareable< D, Extra >:

util::Backupable< D, Extra >

List of all members.


Detailed Description

template<class D, class Extra = internal::Dummy>
class util::Shareable< D, Extra >

Template class to manage allocation/deallocation of data structures on the heap with the ability to share allocated data among several instances.

Data sharing is implemented using the concept of reference counting. When an instance allocates the managed data structure from scratch, it sets the reference counter to one. When it starts sharing the existing data structure, it simply increments the reference counter by one. When it stops sharing data, the reference counter is decremented. Once this counter drops to zero, the managed data structure is automatically deallocated (deleted).

Data managed by instances of this class can be either |NULL| (not allocated and not shared) or non-|NULL| (either allocated using create() or shared with another instance using one of assignment operators or methods), as indicated by the isNull() method and by the data pointer returned by the data() method. Note that the operator->() method will fail (hit an assertion) if the managed data pointer is |NULL|.

The managed data structure (passed as the first argument to the template) must meet the following requirements:

This template class is NOT thread-safe. If you need thread safefy, you can specify util::Lockable as the second argument to the template. In this case, you can explicitly lock instances of the template (using the AutoWriteLock and AutoReadLock classes) before accessing any of its members, as follows: struct Data { ... }; Shareable <Data, util::Lockable> mData; ... { // acquire the lock until the end of the block AutoWriteLock alock (mData); // share with another instance (thatData defined somewhere else) { AutoReadLock thatLock (thatData); mData = thatData; } // access managed data (through operator->()) mData->mSomeVield = someValue; }

Making this class thread-safe usually assumes that the managed data structure must be also thread-safe and must share its own lock object with all other Shareable instances referring it (so locking it through one Shareable instance will prevent another one sharing the same data from accessing it). This can be done in a similar way by deriving the data structure to manage from util::Lockable and using the data() method to lock it before accessing: struct Data : public util::Lockable { ... }; Shareable <Data, util::Lockable> mData; ... { // read-only data access AutoReadLock lock (mData); // protect Shareable members (read-only) AutoReadLock dataLock (mData.data()); // protect Data members (read-only) if (mData->mSomeVield) ... } ... { // data modification AutoReadLock lock (mData); // protect Shareable members (still read-only) AutoWriteLock dataLock (mData.data()); // protect Data members (exclusive) mData->mSomeVield = someValue; }

Please note that if you want to access managed data through data() or operator->(), you have to enter both locks! If you only need to access Shareable members themselves (i.e. to assign one Shareable to another or to call setNull()) it's enough to enter the Shareable lock only (as it's shown at the beginning of the first example).

Parameters:
D data structure to manage
Extra extra class the template instantiation will be publicly derived from (by default, a dummy empty class)

Definition at line 156 of file Shareable.h.


Public Member Functions

void create ()
void createCopy (const Shareable &that)
const D * data () const
D * data ()
bool isNull () const
 operator bool () const
const D * operator-> () const
D * operator-> ()
Shareableoperator= (const Shareable &that)
virtual void setNull ()
 Shareable ()
virtual ~Shareable ()

Package Functions

void setData (Data *aData)

Package Attributes

 __pad0__:Shareable_base::Data BD

Private Attributes

Data * mData

Classes

class  Data

The documentation for this class was generated from the following files:

Generated by  Doxygen 1.6.0   Back to index