ArrayHandle< T > Class Template Reference

#include <Image/ArrayData.H>

List of all members.

---

Detailed Description

template<class T>
class ArrayHandle< T >

This class provides ref-counting and copy-on-write for ArrayData's.

NOTE: Most clients will not need to use ArrayHandle<T> directly, but can rather use Image<T>, which wraps and expands the ArrayHandle interface. Nevertheless, these notes may be of interest because the ref-counting and copy-on-write semantics that ArrayHandle<T> offers are transferred through to Image<T>.

As long as clients access ArrayData<T> through an ArrayHandle<T>, the proper copy-on-write semantics are guaranteed. This is by virtue of the fact that the only way to extract a non-const ArrayData<T>& from an ArrayHandle<T> is to call uniq(), which in turn checks to see if the ArrayData is shared (i.e. ref count > 1). If it is shared, then that ArrayData is clone()'d before returning a reference to it.

The only caveat: you should not store non-const references to an ArrayData or to the elements of an ArrayData object for "long" periods of time. In this case, "long" means "longer than you are sure you have a unique reference", which in practice means "you can keep such references up until a new copy of the ArrayHandle<T> is made". This goes along with sensible coding practices anyway; a typical usage pattern would be:

1. you have an ArrayHandle<T> (or an Image<T>, which holds an ArrayHandle<T>) that you want to modify
2. get a pair of iterator's for that object so that you can perform your series of write operations
3. don't use those iterators anymore, and then you can safely make copies of the freshly-modified ArrayHandle<T> or Image<T> object (for example to return a copy of it as the return value from a function)

Definition at line 326 of file ArrayData.H.

Public Member Functions
	ArrayHandle ()
	Default construct with an empty array (i.e. 0-by-0).
	ArrayHandle (const ArrayData< T > *p) throw ()
	Construct with a new ArrayData, which the ArrayHandle now owns.
	ArrayHandle (const ArrayData< T > *p, const MemoryPolicy mp, const int dev) throw ()
	Construct with a new ArrayData, which the ArrayHandle now owns.
	ArrayHandle (const ArrayHandle &r) throw ()
	Copy construct; no deep-copy is incurred, just bumps the ref-count.
	~ArrayHandle () throw ()
	Destruct; delete's the ArrayData<T> if its ref count goes to zero.
void	swap (ArrayHandle< T > &other) throw ()
	Swap contents with another ArrayHandle.
ArrayHandle &	operator= (const ArrayHandle &r) throw ()
	Assignment; no deep-copy is incurred, just bumps the ref-count.
const ArrayData< T > &	get () const throw ()
	Get a read-only reference to the ArrayData object.
ArrayData< T > &	uniq (const MemoryPolicy mp, const int dev)
	Get a unique read-write reference to the ArrayData object.
ArrayData< T > &	uniq ()
	Get a unique read-write reference to the ArrayData object.
bool	isShared () const throw ()
	See if the ArrayData object is shared (i.e. ref-count > 1).
bool	hasSameData (const ArrayHandle< T > &b) const throw ()
	For testing/debugging only.
int	refCount () const throw ()
	For testing/debugging only.

---

Constructor & Destructor Documentation

template<class T> ArrayHandle< T >::ArrayHandle (   )  [inline]

Default construct with an empty array (i.e. 0-by-0). Definition at line 909 of file ArrayData.H.

template<class T> ArrayHandle< T >::ArrayHandle (  const ArrayData< T > *  p  )  throw () [inline, explicit]

Construct with a new ArrayData, which the ArrayHandle now owns. Definition at line 917 of file ArrayData.H.

template<class T> ArrayHandle< T >::ArrayHandle (  const ArrayData< T > *  p, const MemoryPolicy  mp, const int  dev )  throw () [inline, explicit]

Construct with a new ArrayData, which the ArrayHandle now owns. Definition at line 927 of file ArrayData.H.

template<class T> ArrayHandle< T >::ArrayHandle (  const ArrayHandle< T > &  r  )  throw () [inline]

Copy construct; no deep-copy is incurred, just bumps the ref-count. Definition at line 938 of file ArrayData.H.

template<class T> ArrayHandle< T >::~ArrayHandle (   )  throw () [inline]

Destruct; delete's the ArrayData<T> if its ref count goes to zero. Definition at line 946 of file ArrayData.H.

---

Member Function Documentation

template<class T> const ArrayData< T > & ArrayHandle< T >::get (   )  const throw () [inline]

Get a read-only reference to the ArrayData object. This is a "cheap" operation, since the ArrayData will never be copied in this operation. Definition at line 969 of file ArrayData.H. Referenced by RealVoxel< T >::impl().

template<class T> bool ArrayHandle< T >::hasSameData (  const ArrayHandle< T > &  b  )  const throw () [inline]

For testing/debugging only. See if we are pointing to the same ArrayData<T> as is the other ArrayHandle<T>. Definition at line 1005 of file ArrayData.H. Referenced by RealVoxel< T >::hasSameData().

template<class T> bool ArrayHandle< T >::isShared (   )  const throw () [inline]

See if the ArrayData object is shared (i.e. ref-count > 1). Definition at line 1000 of file ArrayData.H. Referenced by RealVoxel< T >::clear(), and RealVoxel< T >::isShared().

template<class T> ArrayHandle< T > & ArrayHandle< T >::operator= (  const ArrayHandle< T > &  r  )  throw () [inline]

Assignment; no deep-copy is incurred, just bumps the ref-count. Definition at line 962 of file ArrayData.H.

template<class T> int ArrayHandle< T >::refCount (   )  const throw () [inline]

For testing/debugging only. Returns the current reference count of the our ArrayData<T>. Definition at line 1010 of file ArrayData.H. Referenced by RealVoxel< T >::refCount().

template<class T> void ArrayHandle< T >::swap (  ArrayHandle< T > &  other  )  throw () [inline]

Swap contents with another ArrayHandle. Definition at line 953 of file ArrayData.H. Referenced by RealVoxel< T >::attach(), RealVoxel< T >::detach(), TCPmessage::freeMem(), TCPmessage::operator=(), RealVoxel< T >::resize(), RealVoxel< T >::swap(), and ArrayHandle< T >::uniq().

template<class T> ArrayData< T > & ArrayHandle< T >::uniq (   )  [inline]

Get a unique read-write reference to the ArrayData object. This is a potentially "expensive" operation, since in order to get a unique ArrayData object, the current one may have to be clone()'d if it is shared (i.e. ref-count > 1). Definition at line 987 of file ArrayData.H. References ArrayHandle< T >::swap().

template<class T> ArrayData< T > & ArrayHandle< T >::uniq (  const MemoryPolicy  mp, const int  dev )  [inline]

Get a unique read-write reference to the ArrayData object. This is a potentially "expensive" operation, since in order to get a unique ArrayData object, the current one may have to be clone()'d if it is shared (i.e. ref-count > 1). Definition at line 974 of file ArrayData.H. References ArrayHandle< T >::swap(). Referenced by VideoFrame::fromStream(), VideoFrame::getFlippedHoriz(), VideoFrame::makeBobDeinterlaced(), MgzDecoder::readFrame(), RGB24_to_RGB32(), RGB24_to_RGB555(), RGB24_to_RGB565(), RealVoxel< T >::uniq(), YUV24_to_UYVYx(), YUV24_to_YUV410P(), YUV24_to_YUV411(), YUV24_to_YUV411P(), YUV24_to_YUV420P(), YUV24_to_YUV422P(), YUV24_to_YUV444(), YUV24_to_YUV444P(), YUV24_to_YUYV(), yuv411p_to_VideoFrame(), yuv420p_to_VideoFrame(), and yuv422p_to_VideoFrame().

---

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

• src/Image/ArrayData.H

---