1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/textandloc/textrendering/textformatting/undo/UniqueInstance.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,335 @@
1.4 +/*
1.5 +* Copyright (c) 2000-2009 Nokia Corporation and/or its subsidiary(-ies).
1.6 +* All rights reserved.
1.7 +* This component and the accompanying materials are made available
1.8 +* under the terms of "Eclipse Public License v1.0"
1.9 +* which accompanies this distribution, and is available
1.10 +* at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.11 +*
1.12 +* Initial Contributors:
1.13 +* Nokia Corporation - initial contribution.
1.14 +*
1.15 +* Contributors:
1.16 +*
1.17 +* Description:
1.18 +*
1.19 +*/
1.20 +
1.21 +
1.22 +#ifndef UNIQUEINSTANCE_H_
1.23 +#define UNIQUEINSTANCE_H_
1.24 +
1.25 +#include "UniqueInstanceBase.h"
1.26 +
1.27 +// A user may only create and destroy the repository. All access is through the
1.28 +// RUniqueInstance class.
1.29 +//
1.30 +// Please note : Deleting the repository is unsafe unless all of its owned
1.31 +// objects have been destroyed or relinquished. If objects exist in the repository
1.32 +// (and provided that no RUniqueInstance objects have leaked) it follows that
1.33 +// there must be RUniqueInstance objects around that still reference these objects.
1.34 +// These RUniqueInstances will at some point try to access the repository to
1.35 +// relinquish or destroy these objects, but it will have been deleted! Therefore
1.36 +// the destructor panics if there are any objects in the repository.
1.37 +//
1.38 +// The compare function and copy function must co-operate like this:
1.39 +// A) aCompare is a total order. That is, for all valid objects of type T t, u and v:
1.40 +// i) aCompare(t, t) == 0 (idempotency)
1.41 +// ii) if aCompare(t, u) < 0 then aCompare(u, t) > 0 (associativity)
1.42 +// iii)if aCompare(t, u) < 0 and aCompare(u, v) < 0 then aCompare(t, v) < 0
1.43 +// (transitivity)
1.44 +// B) aCopyL always produces objects that compare equal to the arguments that
1.45 +// produced them, that is for all valid objects of type T t:
1.46 +// aCompare(t, aCopyL(t, sizeof(T))) == 0 (ignoring the memory leak!)
1.47 +// If these conditions are not met, the behaviour of the repository is undefined.
1.48 +// If the type does not own anything and does not have variable length, the
1.49 +// copy and delete functions can be omitted.
1.50 +//
1.51 +// The operation of the repository and its clients is not thread safe.
1.52 +//
1.53 +// For aMaxLinks give half the log(base 2) of the expected maximum size of the
1.54 +// repository. So for a repository of size 256, use 4. For size 65535 use 8. For
1.55 +// 16777216 use 12.
1.56 +
1.57 +/**
1.58 +Store of objects that coalesces repeated instances.
1.59 +
1.60 +@since App-frameworks6.1
1.61 +@internalComponent
1.62 +*/
1.63 +template <typename T> class CUniqueInstanceRepository
1.64 + : public UniqueInstance::CUniqueInstanceRepositoryBase
1.65 +
1.66 + {
1.67 +public:
1.68 +
1.69 + // typical implementation might be:
1.70 + // void CompareT(const T* aL, const T* aR)
1.71 + // {
1.72 + // if (*aL == *aR)
1.73 + // return 0;
1.74 + // if (*aL < *aR)
1.75 + // return -1;
1.76 + // return 1;
1.77 + // }
1.78 + typedef TInt TCompareFnType(const T*, const T*);
1.79 +
1.80 + // typical implementation might be:
1.81 + // void DeleteT(T* aDestroy)
1.82 + // {
1.83 + // delete aDestroy;
1.84 + // }
1.85 + typedef void TDeleteFnType(T* aObjectToBeDestroyed);
1.86 +
1.87 + // typical implementation might be:
1.88 + // T* CopyT(const T* aSrc, TInt aOffset, TInt)
1.89 + // {
1.90 + // return new(ELeave) T(*aSrc);
1.91 + // }
1.92 + typedef T* TCopyFnTypeL(const T* aTToBeCopied, TInt aSizeOfT);
1.93 +
1.94 + /**
1.95 + * Creates a new empty repository. aCompare must define a total order on
1.96 + * objects that may be added to the repository. In other words
1.97 + * aCompare(a,b) == 0 iff a and b are equivalent, aCompare(a,b) < 0
1.98 + * iff aCompare(a,b) > 0, aCompare(a,b) < 0 iff aCompare(b,a) < 0 and
1.99 + * aCompare(a,b) < 0 && aCompare(b,c) < 0 implies that aCompare(a,c) < 0.
1.100 + * aDelete(a) deletes a and aCopyL(a) generates a new object such that
1.101 + * aCompare(aCopyL(a),a) == 0.
1.102 + * aMaxLinks concerns the space against speed tradeoff of the
1.103 + * implementation. It should be a number greater than half log2 of the
1.104 + * expected maximum size of the repository.
1.105 + */
1.106 + static inline CUniqueInstanceRepository<T>* NewL(TCompareFnType* aCompare,
1.107 + TDeleteFnType* aDelete, TCopyFnTypeL* aCopyL, TInt aMaxLinks = 10);
1.108 + static inline CUniqueInstanceRepository<T>* NewLC(TCompareFnType* aCompare,
1.109 + TDeleteFnType* aDelete, TCopyFnTypeL* aCopyL, TInt aMaxLinks = 10);
1.110 + /**
1.111 + * Creates a new empty repository with aDelete(a) simply freeing memory
1.112 + * at a and aCopyL(a) simply bitwise copying the memory occupied by a.
1.113 + * This is suitable only if T has no destructor and only the automatic
1.114 + * copy constructor.
1.115 + */
1.116 + static inline CUniqueInstanceRepository<T>* NewL(TCompareFnType* aCompare,
1.117 + TInt aMaxLinks = 10);
1.118 + static inline CUniqueInstanceRepository<T>* NewLC(TCompareFnType* aCompare,
1.119 + TInt aMaxLinks = 10);
1.120 +private:
1.121 + CUniqueInstanceRepository() {}
1.122 + };
1.123 +
1.124 +/**
1.125 +Specialization for the odd semantics of TDes. Copy/Delete/Compare functions
1.126 +are provided free.
1.127 +
1.128 +@since App-frameworks6.1
1.129 +@internalComponent
1.130 +*/
1.131 +template <> class CUniqueInstanceRepository<TDes>
1.132 + : public UniqueInstance::CUniqueInstanceRepositoryBase
1.133 +
1.134 + {
1.135 + CUniqueInstanceRepository() {}
1.136 + static void* DesCopyL(void*, TInt);
1.137 + static TInt DesCompare(void*, void*);
1.138 + static void DesDelete(void*);
1.139 +public:
1.140 + static inline CUniqueInstanceRepository<TDes>* NewL(TInt aMaxLinks = 10);
1.141 + static inline CUniqueInstanceRepository<TDes>* NewLC(TInt aMaxLinks = 10);
1.142 + };
1.143 +
1.144 +/**
1.145 +Client of a CUniqueInstanceRepository.
1.146 +Holds a single object, which may be shared.
1.147 +
1.148 +@since App-frameworks6.1
1.149 +@internalComponent
1.150 +*/
1.151 +template <typename T> class RUniqueInstance
1.152 +
1.153 + {
1.154 +public:
1.155 + inline explicit RUniqueInstance(CUniqueInstanceRepository<T>& aRepository)
1.156 + : iImpl(aRepository) {}
1.157 + /**
1.158 + * Destructor. In debug builds this asserts that no object is owned.
1.159 + */
1.160 + inline ~RUniqueInstance() {}
1.161 +
1.162 + /**
1.163 + * Registers the argument as a unique instance, to be referenced by this
1.164 + * RUniqueInstance. Any previously owned object is destroyed.
1.165 + */
1.166 + inline void TakeL(T* aToAdd);
1.167 + /**
1.168 + * Makes a copy of the argument, as a unique instance. The argument is
1.169 + * still owned by the caller
1.170 + */
1.171 + inline void TakeCopyL(const T* aToCopy);
1.172 + /**
1.173 + * Returns a pointer to the referenced object without passing ownership
1.174 + */
1.175 + inline const T* Peek() const;
1.176 + /**
1.177 + * Makes another instance of the same object: both have ownership
1.178 + */
1.179 + inline void CopyTo(RUniqueInstance<T>& aOther) const;
1.180 + /**
1.181 + * Pass ownership of the owned object to another RUniqueInstance.
1.182 + * This object may not be referenced through this RUniqueInstance any
1.183 + * more, only through aOther.
1.184 + */
1.185 + inline void MoveTo(RUniqueInstance<T>& aOther);
1.186 + /**
1.187 + * Relinquishes ownership of the object to the caller. The object is
1.188 + * not destroyed. It may not be referenced through this RUniqueInstance
1.189 + * any more. The pointer returned may be different from that passed
1.190 + * to TakeL() or returned from Peek()
1.191 + */
1.192 + inline T* DropL();
1.193 + /**
1.194 + * Releases the owned object.
1.195 + */
1.196 + inline void Close();
1.197 +
1.198 +private:
1.199 + UniqueInstance::RInstanceImpl iImpl;
1.200 + };
1.201 +
1.202 +/**
1.203 +Specialization of RUniqueInstance for the odd semantics of TDes.
1.204 +Any descriptor that needs ownership to be passed around is an HBufC.
1.205 +Any time a copy or view over a descriptor is required, a const TDesC
1.206 +is used. Please note the different signature of NewL and NewLC. This is
1.207 +because copy, delete and compare functions are provided for free.
1.208 +
1.209 +@since App-frameworks6.1
1.210 +@internalComponent
1.211 +*/
1.212 +TEMPLATE_SPECIALIZATION class RUniqueInstance<TDes>
1.213 +
1.214 + {
1.215 +public:
1.216 + inline explicit RUniqueInstance(CUniqueInstanceRepository<TDes>& aRepository)
1.217 + : iImpl(aRepository) {}
1.218 + inline ~RUniqueInstance() {}
1.219 + inline void TakeL(HBufC* aToAdd);
1.220 + inline void TakeCopyL(const TDesC* aToCopy);
1.221 + inline const TDesC* Peek() const;
1.222 + inline void CopyTo(RUniqueInstance<TDes>& aOther) const;
1.223 + inline void MoveTo(RUniqueInstance<TDes>& aOther);
1.224 + inline HBufC* DropL();
1.225 + inline void Close();
1.226 +
1.227 +private:
1.228 + UniqueInstance::RInstanceImpl iImpl;
1.229 + };
1.230 +
1.231 +template <typename T>
1.232 +inline CUniqueInstanceRepository<T>* CUniqueInstanceRepository<T>::NewLC(
1.233 + typename CUniqueInstanceRepository<T>::TCompareFnType* aCompare,
1.234 + typename CUniqueInstanceRepository<T>::TDeleteFnType* aDelete,
1.235 + typename CUniqueInstanceRepository<T>::TCopyFnTypeL* aCopyL, TInt aMaxLinks)
1.236 + {
1.237 + CUniqueInstanceRepository<T>* that = new(ELeave) CUniqueInstanceRepository<T>;
1.238 + CleanupStack::PushL(that);
1.239 + that->ConstructL(reinterpret_cast<UniqueInstance::TCompareFn*>(aCompare),
1.240 + reinterpret_cast<UniqueInstance::TDeleteFn*>(aDelete),
1.241 + reinterpret_cast<UniqueInstance::TCopyFnL*>(aCopyL), aMaxLinks,
1.242 + sizeof(T));
1.243 + return that;
1.244 + }
1.245 +
1.246 +template <typename T>
1.247 +inline CUniqueInstanceRepository<T>* CUniqueInstanceRepository<T>::NewL(
1.248 + typename CUniqueInstanceRepository<T>::TCompareFnType* aComp,
1.249 + typename CUniqueInstanceRepository<T>::TDeleteFnType* aDel,
1.250 + typename CUniqueInstanceRepository<T>::TCopyFnTypeL* aCopyL, TInt aMaxLinks)
1.251 + {
1.252 + CUniqueInstanceRepository<T>* that = NewLC(aComp, aDel, aCopyL, aMaxLinks);
1.253 + CleanupStack::Pop(that);
1.254 + return that;
1.255 + }
1.256 +
1.257 +template <typename T>
1.258 +inline CUniqueInstanceRepository<T>* CUniqueInstanceRepository<T>::NewLC(
1.259 + typename CUniqueInstanceRepository<T>::TCompareFnType* aCompare, TInt aMaxLinks)
1.260 + {
1.261 + CUniqueInstanceRepository<T>* that = new(ELeave) CUniqueInstanceRepository<T>;
1.262 + CleanupStack::PushL(that);
1.263 + that->ConstructL(reinterpret_cast<UniqueInstance::TCompareFn*>(aCompare),
1.264 + DumbDelete, DumbCopyL, aMaxLinks,
1.265 + sizeof(T));
1.266 + return that;
1.267 + }
1.268 +
1.269 +template <typename T>
1.270 +inline CUniqueInstanceRepository<T>* CUniqueInstanceRepository<T>::NewL(
1.271 + typename CUniqueInstanceRepository<T>::TCompareFnType* aComp, TInt aMaxLinks)
1.272 + {
1.273 + CUniqueInstanceRepository<T>* that = NewLC(aComp, aMaxLinks);
1.274 + CleanupStack::Pop(that);
1.275 + return that;
1.276 + }
1.277 +
1.278 +inline CUniqueInstanceRepository<TDes>* CUniqueInstanceRepository<TDes>::NewLC(
1.279 + TInt aMaxLinks)
1.280 + {
1.281 + CUniqueInstanceRepository<TDes>* that = new(ELeave) CUniqueInstanceRepository<TDes>;
1.282 + CleanupStack::PushL(that);
1.283 + that->ConstructL(DesCompare, DesDelete, DesCopyL, aMaxLinks, 1);
1.284 + return that;
1.285 + }
1.286 +
1.287 +inline CUniqueInstanceRepository<TDes>* CUniqueInstanceRepository<TDes>::NewL(
1.288 + TInt aMaxLinks)
1.289 + {
1.290 + CUniqueInstanceRepository<TDes>* that = NewLC(aMaxLinks);
1.291 + CleanupStack::Pop(that);
1.292 + return that;
1.293 + }
1.294 +
1.295 +///////////////////////////////
1.296 +// //
1.297 +// RUniqueInstance inlines //
1.298 +// //
1.299 +///////////////////////////////
1.300 +
1.301 +template <typename T> inline
1.302 +void RUniqueInstance<T>::TakeL(T* aToAdd)
1.303 + { iImpl.TakeL(aToAdd); }
1.304 +template <typename T> inline
1.305 +void RUniqueInstance<T>::TakeCopyL(const T* aToCopy)
1.306 + { iImpl.TakeCopyL(const_cast<T*>(aToCopy)); }
1.307 +template <typename T> inline
1.308 +const T* RUniqueInstance<T>::Peek() const
1.309 + { return reinterpret_cast<const T*>(iImpl.Peek()); }
1.310 +template <typename T> inline
1.311 +void RUniqueInstance<T>::CopyTo(RUniqueInstance<T>& aOther) const
1.312 + { iImpl.CopyTo(aOther.iImpl); }
1.313 +template <typename T> inline
1.314 +void RUniqueInstance<T>::MoveTo(RUniqueInstance<T>& aOther)
1.315 + { iImpl.MoveTo(aOther.iImpl); }
1.316 +template <typename T> inline
1.317 +T* RUniqueInstance<T>::DropL()
1.318 + { return reinterpret_cast<T*>(iImpl.DropL()); }
1.319 +template <typename T> inline
1.320 +void RUniqueInstance<T>::Close()
1.321 + { iImpl.Close(); }
1.322 +
1.323 +inline void RUniqueInstance<TDes>::TakeL(HBufC* aToAdd)
1.324 + { iImpl.TakeL(aToAdd); }
1.325 +inline void RUniqueInstance<TDes>::TakeCopyL(const TDesC* aToCopy)
1.326 + { iImpl.TakeCopyL(const_cast<TDesC*>(aToCopy)); }
1.327 +inline const TDesC* RUniqueInstance<TDes>::Peek() const
1.328 + { return reinterpret_cast<HBufC*>(iImpl.Peek()); }
1.329 +inline void RUniqueInstance<TDes>::CopyTo(RUniqueInstance<TDes>& aOther) const
1.330 + { iImpl.CopyTo(aOther.iImpl); }
1.331 +inline void RUniqueInstance<TDes>::MoveTo(RUniqueInstance<TDes>& aOther)
1.332 + { iImpl.MoveTo(aOther.iImpl); }
1.333 +inline HBufC* RUniqueInstance<TDes>::DropL()
1.334 + { return reinterpret_cast<HBufC*>(iImpl.DropL()); }
1.335 +inline void RUniqueInstance<TDes>::Close()
1.336 + { iImpl.Close(); }
1.337 +
1.338 +#endif // UNIQUEINSTANCE_H_