1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/ossrv/lowlevellibsandfws/genericusabilitylib/inc/emanaged.h Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,3207 @@
1.4 +// Copyright (c) 2008-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +//
1.18 +
1.19 +#ifndef EMANAGED_H
1.20 +#define EMANAGED_H
1.21 +
1.22 +#include <e32base.h>
1.23 +
1.24 +#include <typerel.h>
1.25 +#include <swap.h>
1.26 +
1.27 +
1.28 +
1.29 +
1.30 +/**
1.31 + @file
1.32 + @brief Utility class templates that provide RAII-based automatic
1.33 + resource management.
1.34 +
1.35 + @publishedAll
1.36 + @released
1.37 +*/
1.38 +
1.39 +
1.40 + /**
1.41 + Implementation function.In order to override the default cleanup
1.42 + strategy for a particular type, use the provided
1.43 + DEFINE_CLEANUP_FUNCTION utility macro
1.44 + @internalComponent
1.45 + */
1.46 +// Not for Client Use , Only to be used Internally.
1.47 +template<class T>
1.48 +inline void CallCleanupFunction(T* aObjPtr)
1.49 + {
1.50 + aObjPtr->Close();
1.51 + }
1.52 +
1.53 +
1.54 +/**
1.55 +Utility macro that can be used for defining the cleanup member
1.56 +function for a class (typically a R-class).
1.57 +
1.58 +This macro can be used in the same namespace in which the R-class is
1.59 +defined or in a namespace in which the R-class is used.
1.60 +
1.61 +Example:
1.62 +
1.63 +class RDestroyableClass
1.64 + {
1.65 + public:
1.66 + // ...
1.67 + void Destroy(); // member function used for cleanup and releasing the resources owned by a RDestroyableClass object
1.68 + // ...
1.69 + };
1.70 +
1.71 +DEFINE_CLEANUP_FUNCTION(RDestroyableClass, Destroy)
1.72 +
1.73 +@param AClass the name of the class
1.74 +@param CleanupMemFun the name of the cleanup member function of the class
1.75 + */
1.76 +#define DEFINE_CLEANUP_FUNCTION(AClass, CleanupMemFun) \
1.77 + inline void CallCleanupFunction(AClass* aObjPtr) \
1.78 + { \
1.79 + aObjPtr->CleanupMemFun(); \
1.80 + }
1.81 +
1.82 +/**
1.83 +Utility macro that can be used for specializing the default cleanup
1.84 +strategy class template TResourceCleanupStrategy for a particular
1.85 +class (typically a R-class). The default cleanup strategy for a class
1.86 +specified using DEFINE_CLEANUP_STRATEGY overrides any other cleanup
1.87 +strategy specified using DEFINE_CLEANUP_FUNCTION for that class.
1.88 +
1.89 +This macro must be used in the same namespace in which the R-class is
1.90 +defined.
1.91 +
1.92 +
1.93 + Utility macro that can be used for enabling single phase
1.94 + construction for CBase-derived classes. This is necessary because
1.95 + Symbian OS currently lacks the placement delete operator
1.96 + counterparts corresponding to the placement new operators that take
1.97 + a TLeave parameter (new(ELeave)), which will result in memory leaks
1.98 + if a class constructor leaves.
1.99 +
1.100 + This macro must be used within a public section of a class
1.101 + definition, if the single phase construction is part of the public
1.102 + interface of the class.
1.103 +
1.104 + Current Limitation CONSTRUCTORS_MAY_LEAVE is an unfortunate blight on the
1.105 + usability of single-phase construction, but we have yet to come up
1.106 + with a better alternative in the face of the legacy handling of
1.107 + ELeave.
1.108 +*/
1.109 +#define CONSTRUCTORS_MAY_LEAVE \
1.110 + static void operator delete(TAny* aPtr) __NO_THROW \
1.111 + { \
1.112 + ::operator delete(aPtr); \
1.113 + } \
1.114 + \
1.115 + static void operator delete(TAny*, TAny*) __NO_THROW \
1.116 + { \
1.117 + } \
1.118 + \
1.119 + static void operator delete(TAny* aPtr, TLeave) __NO_THROW \
1.120 + { \
1.121 + ::operator delete(aPtr); \
1.122 + } \
1.123 + \
1.124 + static void operator delete(TAny* aPtr, TUint) __NO_THROW \
1.125 + { \
1.126 + ::operator delete(aPtr); \
1.127 + } \
1.128 + \
1.129 + static void operator delete(TAny* aPtr, TLeave, TUint) __NO_THROW \
1.130 + { \
1.131 + ::operator delete(aPtr); \
1.132 + } \
1.133 + \
1.134 + static void operator delete[](TAny* aPtr) __NO_THROW \
1.135 + { \
1.136 + ::operator delete[](aPtr); \
1.137 + } \
1.138 + \
1.139 + static void operator delete[](TAny* aPtr, TLeave) __NO_THROW \
1.140 + { \
1.141 + ::operator delete[](aPtr); \
1.142 + }
1.143 +
1.144 +
1.145 +// Implementation function.
1.146 +template<typename T>
1.147 +void ManagedPopCleanupStackItem(T aIsManaged)
1.148 + {
1.149 +// CleanupStack-based cleanup is automatically triggered by a Leave,
1.150 +// so, in the case when __LEAVE_EQUALS_THROW__,
1.151 +// CleanupStack::PopAndDestroy must not be called again here
1.152 +#ifndef __GCCXML__
1.153 +// for gccxml builds the std::uncaught_exception function is not listed in std name space
1.154 +// to supress GCCXML error
1.155 + if (!std::uncaught_exception())
1.156 + {
1.157 + if (aIsManaged)
1.158 + {
1.159 + CleanupStack::PopAndDestroy();
1.160 + }
1.161 + else
1.162 + {
1.163 + CleanupStack::Pop();
1.164 + }
1.165 + }
1.166 +#endif
1.167 + }
1.168 +
1.169 +/**
1.170 + Strategy (policy) class that defines the default cleanup strategy
1.171 + for managed resource class objects.
1.172 +
1.173 + The default cleanup strategy is to call the cleanup member function
1.174 + of the managed class, which is the Close() member function of the
1.175 + managed class, unless explicitly defined otherwise, for example by
1.176 + using the provided DEFINE_CLEANUP_FUNCTION macro.
1.177 +
1.178 + @internalComponent
1.179 +*/
1.180 +// Not for Client Use , Only to be used Internally.
1.181 +class TResourceCleanupStrategy
1.182 + {
1.183 + public:
1.184 + template<typename T>
1.185 + static void Cleanup(T* aObjPtr)
1.186 + {
1.187 + CallCleanupFunction(aObjPtr);
1.188 + }
1.189 + };
1.190 +
1.191 +/**
1.192 + Strategy (policy) class that defines a cleanup strategy for managed
1.193 + resource class objects. This cleanup strategy calls the Close()
1.194 + member function of the managed class.
1.195 +
1.196 + @see LCleanedupHandle to which this strategy type may be supplied as
1.197 + an (optional) second tamplate parameter
1.198 + @see LManagedHandle to which this strategy type may be supplied as
1.199 + an (optional) second tamplate parameter
1.200 +*/
1.201 +class TClose
1.202 + {
1.203 + public:
1.204 + template<class T>
1.205 + static void Cleanup(T* aObjPtr)
1.206 + {
1.207 + aObjPtr->Close();
1.208 + }
1.209 + };
1.210 +
1.211 +/**
1.212 + Strategy (policy) class that defines a cleanup strategy for managed
1.213 + resource class objects. This cleanup strategy calls the Release()
1.214 + member function of the managed class.
1.215 +
1.216 + @see LCleanedupHandle to which this strategy type may be supplied as
1.217 + an (optional) second tamplate parameter
1.218 + @see LManagedHandle to which this strategy type may be supplied as
1.219 + an (optional) second tamplate parameter
1.220 +*/
1.221 +class TRelease
1.222 + {
1.223 + public:
1.224 + template<class T>
1.225 + static void Cleanup(T* aObjPtr)
1.226 + {
1.227 + aObjPtr->Release();
1.228 + }
1.229 + };
1.230 +
1.231 +/**
1.232 + Strategy (policy) class that defines a cleanup strategy for managed
1.233 + resource class objects. This cleanup strategy calls the Destroy()
1.234 + member function of the managed class.
1.235 +
1.236 + @see LCleanedupHandle to which this strategy type may be supplied as
1.237 + an (optional) second tamplate parameter
1.238 + @see LManagedHandle to which this strategy type may be supplied as
1.239 + an (optional) second tamplate parameter
1.240 +*/
1.241 +class TDestroy
1.242 + {
1.243 + public:
1.244 + template<class T>
1.245 + static void Cleanup(T* aObjPtr)
1.246 + {
1.247 + aObjPtr->Destroy();
1.248 + }
1.249 + };
1.250 +
1.251 +/**
1.252 + Strategy (policy) class that defines a cleanup strategy for managed
1.253 + resource class objects. This cleanup strategy calls the Free()
1.254 + member function of the managed class.
1.255 +
1.256 + @see LCleanedupHandle to which this strategy type may be supplied as
1.257 + an (optional) second tamplate parameter
1.258 + @see LManagedHandle to which this strategy type may be supplied as
1.259 + an (optional) second tamplate parameter
1.260 +*/
1.261 +class TFree
1.262 + {
1.263 + public:
1.264 + template<class T>
1.265 + static void Cleanup(T* aObjPtr)
1.266 + {
1.267 + aObjPtr->Free();
1.268 + }
1.269 + };
1.270 +
1.271 +/**
1.272 + Strategy (policy) class that defines a cleanup strategy for managed
1.273 + resource class objects. This cleanup strategy calls the
1.274 + ResetAndDestroy() member function of the managed class.
1.275 +
1.276 + @see LCleanedupHandle to which this strategy type may be supplied as
1.277 + an (optional) second tamplate parameter
1.278 + @see LManagedHandle to which this strategy type may be supplied as
1.279 + an (optional) second tamplate parameter
1.280 +*/
1.281 +class TResetAndDestroy
1.282 + {
1.283 + public:
1.284 + template<class T>
1.285 + static void Cleanup(T* aObjPtr)
1.286 + {
1.287 + aObjPtr->ResetAndDestroy();
1.288 + }
1.289 + };
1.290 +
1.291 +
1.292 +/**
1.293 + Strategy (policy) class that defines the default cleanup strategy
1.294 + for pointer types. For pointers to CBase-derived types, the
1.295 + default cleanup strategy is to call CBase::Delete with the managed
1.296 + pointer. For pointers to types that are not derived from CBase,
1.297 + the default cleanup strategy is to delete the managed pointer using
1.298 + non-array delete.
1.299 +
1.300 + @see LCleanedupPtr to which this strategy type may be supplied as
1.301 + an (optional) second tamplate parameter
1.302 + @see LManagedPtr to which this strategy type may be supplied as
1.303 + an (optional) second tamplate parameter
1.304 +*/
1.305 +class TPtrCleanupStrategy
1.306 + {
1.307 + public:
1.308 + template<typename T>
1.309 + static void Cleanup(T* aPtr)
1.310 + {
1.311 + delete aPtr;
1.312 + }
1.313 +
1.314 + static void Cleanup(CBase* aPtr)
1.315 + {
1.316 + CBase::Delete(aPtr);
1.317 + }
1.318 + };
1.319 +
1.320 +
1.321 +/**
1.322 + Strategy (policy) class that defines a cleanup strategy for pointer
1.323 + types. This cleanup strategy deletes the managed pointer by using
1.324 + non-array delete.
1.325 +
1.326 + @see LCleanedupPtr to which this strategy type may be supplied as
1.327 + an (optional) second tamplate parameter
1.328 + @see LManagedPtr to which this strategy type may be supplied as
1.329 + an (optional) second tamplate parameter
1.330 +*/
1.331 +class TPointerDeleteStrategy
1.332 + {
1.333 + public:
1.334 + template<typename T>
1.335 + static void Cleanup(T* aPtr)
1.336 + {
1.337 + delete aPtr;
1.338 + }
1.339 + };
1.340 +
1.341 +
1.342 +/**
1.343 + Strategy (policy) class that defines a cleanup strategy for
1.344 + pointers to CBase-derived types. This cleanup strategy calls
1.345 + CBase::Delete with the managed pointer.
1.346 +
1.347 + @see LCleanedupPtr to which this strategy type may be supplied as
1.348 + an (optional) second tamplate parameter
1.349 + @see LManagedPtr to which this strategy type may be supplied as
1.350 + an (optional) second tamplate parameter
1.351 +*/
1.352 +class TCBaseDeleteStrategy
1.353 + {
1.354 + public:
1.355 + static void Cleanup(CBase* aPtr)
1.356 + {
1.357 + CBase::Delete(aPtr);
1.358 + }
1.359 + };
1.360 +
1.361 +
1.362 +/**
1.363 + Strategy (policy) class that defines a cleanup strategy for pointer
1.364 + types. This cleanup strategy calls User::Free with the managed
1.365 + pointer.
1.366 +
1.367 + @see LCleanedupPtr to which this strategy type may be supplied as
1.368 + an (optional) second tamplate parameter
1.369 + @see LManagedPtr to which this strategy type may be supplied as
1.370 + an (optional) second tamplate parameter
1.371 +*/
1.372 +class TPointerFree
1.373 + {
1.374 + public:
1.375 + static void Cleanup(TAny* aPtr)
1.376 + {
1.377 + User::Free(aPtr);
1.378 + }
1.379 + };
1.380 +
1.381 +
1.382 +/**
1.383 + Strategy (policy) class that defines the default cleanup strategy
1.384 + for heap-allocated arrays. This cleanup strategy deallocates the
1.385 + managed array by using array delete.
1.386 +*/
1.387 +class TArrayDelete
1.388 + {
1.389 + public:
1.390 + template<typename T>
1.391 + static void Cleanup(T* aPtr)
1.392 + {
1.393 + delete[] aPtr;
1.394 + }
1.395 + };
1.396 +
1.397 +
1.398 +// enum type used for identifying the categories of managed pointer types
1.399 +enum TManagedPtrType
1.400 +{
1.401 + EPtrNonSpecial,
1.402 + EPtrCBaseDerived
1.403 +};
1.404 +
1.405 +
1.406 +// macro used for determining whether a pointer is special
1.407 +#define IS_PTR_SPECIAL(T) IS_BASE_OF(CBase, T)
1.408 +
1.409 +
1.410 +// enum type used for identifying the categories of resource handle types
1.411 +enum TAutoHandleType
1.412 +{
1.413 + EAutoHandleNonSpecial,
1.414 + EAutoRHandleBaseDerived,
1.415 + EAutoHandleRBuf
1.416 +};
1.417 +
1.418 +
1.419 +// macro used for determining whether a resource handle type is special
1.420 +#define IS_HANDLE_SPECIAL(T) IS_BASE_OF(RHandleBase, T) ? EAutoRHandleBaseDerived : ( (IS_SAME(RBuf8, T) || IS_SAME(RBuf16, T)) ? EAutoHandleRBuf : EAutoHandleNonSpecial )
1.421 +
1.422 +
1.423 +/**
1.424 + Implementation base class - not designed for public inheritance or
1.425 + direct use.
1.426 +
1.427 + @internalComponent
1.428 +*/
1.429 +// Not for Client Use , Only to be used Internally.
1.430 +template<typename T,
1.431 + TInt isHandleSpecial = IS_HANDLE_SPECIAL(T)>
1.432 +class LAutoHandleBase
1.433 + {
1.434 + protected:
1.435 + LAutoHandleBase()
1.436 + : iEnabled(ETrue)
1.437 + {
1.438 + }
1.439 +
1.440 + template<typename Param1>
1.441 + explicit LAutoHandleBase(const Param1& aParam1)
1.442 + : iHandle(aParam1),
1.443 + iEnabled(ETrue)
1.444 + {
1.445 + }
1.446 +
1.447 + template<typename Param1>
1.448 + explicit LAutoHandleBase(Param1& aParam1)
1.449 + : iHandle(aParam1),
1.450 + iEnabled(ETrue)
1.451 + {
1.452 + }
1.453 +
1.454 + template<typename Param1,
1.455 + typename Param2>
1.456 + LAutoHandleBase(const Param1& aParam1,
1.457 + const Param2& aParam2)
1.458 + : iHandle(aParam1,
1.459 + aParam2),
1.460 + iEnabled(ETrue)
1.461 + {
1.462 + }
1.463 +
1.464 + template<typename Param1,
1.465 + typename Param2>
1.466 + LAutoHandleBase(Param1& aParam1,
1.467 + const Param2& aParam2)
1.468 + : iHandle(aParam1,
1.469 + aParam2),
1.470 + iEnabled(ETrue)
1.471 + {
1.472 + }
1.473 +
1.474 + template<typename Param1,
1.475 + typename Param2>
1.476 + LAutoHandleBase(const Param1& aParam1,
1.477 + Param2& aParam2)
1.478 + : iHandle(aParam1,
1.479 + aParam2),
1.480 + iEnabled(ETrue)
1.481 + {
1.482 + }
1.483 +
1.484 + template<typename Param1,
1.485 + typename Param2>
1.486 + LAutoHandleBase(Param1& aParam1,
1.487 + Param2& aParam2)
1.488 + : iHandle(aParam1,
1.489 + aParam2),
1.490 + iEnabled(ETrue)
1.491 + {
1.492 + }
1.493 +
1.494 + template<typename U>
1.495 + LAutoHandleBase& operator=(const U& aHandle)
1.496 + {
1.497 + iHandle = aHandle;
1.498 + iEnabled = ETrue;
1.499 + return *this;
1.500 + }
1.501 +
1.502 + T& Get()
1.503 + {
1.504 + return iHandle;
1.505 + }
1.506 +
1.507 + const T& Get() const
1.508 + {
1.509 + return iHandle;
1.510 + }
1.511 +
1.512 + T& operator*()
1.513 + {
1.514 + return iHandle;
1.515 + }
1.516 +
1.517 + const T& operator*() const
1.518 + {
1.519 + return iHandle;
1.520 + }
1.521 +
1.522 + T* operator->()
1.523 + {
1.524 + return &iHandle;
1.525 + }
1.526 +
1.527 + const T* operator->() const
1.528 + {
1.529 + return &iHandle;
1.530 + }
1.531 +
1.532 + T Unmanage()
1.533 + {
1.534 + iEnabled = EFalse;
1.535 + return iHandle;
1.536 + }
1.537 +
1.538 + TBool IsEnabled() const
1.539 + {
1.540 + return iEnabled;
1.541 + }
1.542 +
1.543 + void Disable()
1.544 + {
1.545 + iEnabled = EFalse;
1.546 + }
1.547 +
1.548 + void Swap(LAutoHandleBase& aAutoHandle)
1.549 + {
1.550 + ::Swap(iHandle, aAutoHandle.iHandle);
1.551 + ::Swap(iEnabled, aAutoHandle.iEnabled);
1.552 + }
1.553 +
1.554 + protected:
1.555 + T iHandle;
1.556 + TBool iEnabled;
1.557 +
1.558 + private:
1.559 + LAutoHandleBase(const LAutoHandleBase&);
1.560 + LAutoHandleBase& operator=(const LAutoHandleBase&);
1.561 + };
1.562 +
1.563 +
1.564 +/**
1.565 + Implementation base class - not designed for public inheritance or
1.566 + direct use. Specialization for types derived from RHandleBase.
1.567 +*/
1.568 +template<typename T>
1.569 +class LAutoHandleBase<T, EAutoRHandleBaseDerived>
1.570 + {
1.571 + protected:
1.572 + LAutoHandleBase()
1.573 + {
1.574 + }
1.575 +
1.576 + template<typename Param1>
1.577 + explicit LAutoHandleBase(const Param1& aParam1)
1.578 + : iHandle(aParam1)
1.579 + {
1.580 + }
1.581 +
1.582 + template<typename Param1>
1.583 + explicit LAutoHandleBase(Param1& aParam1)
1.584 + : iHandle(aParam1)
1.585 + {
1.586 + }
1.587 +
1.588 + template<typename Param1,
1.589 + typename Param2>
1.590 + LAutoHandleBase(const Param1& aParam1,
1.591 + const Param2& aParam2)
1.592 + : iHandle(aParam1,
1.593 + aParam2)
1.594 + {
1.595 + }
1.596 +
1.597 + template<typename Param1,
1.598 + typename Param2>
1.599 + LAutoHandleBase(Param1& aParam1,
1.600 + const Param2& aParam2)
1.601 + : iHandle(aParam1,
1.602 + aParam2)
1.603 + {
1.604 + }
1.605 +
1.606 + template<typename Param1,
1.607 + typename Param2>
1.608 + LAutoHandleBase(const Param1& aParam1,
1.609 + Param2& aParam2)
1.610 + : iHandle(aParam1,
1.611 + aParam2)
1.612 + {
1.613 + }
1.614 +
1.615 + template<typename Param1,
1.616 + typename Param2>
1.617 + LAutoHandleBase(Param1& aParam1,
1.618 + Param2& aParam2)
1.619 + : iHandle(aParam1,
1.620 + aParam2)
1.621 + {
1.622 + }
1.623 +
1.624 + template<typename U>
1.625 + LAutoHandleBase& operator=(const U& aHandle)
1.626 + {
1.627 + iHandle = aHandle;
1.628 + return *this;
1.629 + }
1.630 +
1.631 + T& Get()
1.632 + {
1.633 + return iHandle;
1.634 + }
1.635 +
1.636 + const T& Get() const
1.637 + {
1.638 + return iHandle;
1.639 + }
1.640 +
1.641 + T& operator*()
1.642 + {
1.643 + return iHandle;
1.644 + }
1.645 +
1.646 + const T& operator*() const
1.647 + {
1.648 + return iHandle;
1.649 + }
1.650 +
1.651 + T* operator->()
1.652 + {
1.653 + return &iHandle;
1.654 + }
1.655 +
1.656 + const T* operator->() const
1.657 + {
1.658 + return &iHandle;
1.659 + }
1.660 +
1.661 + T Unmanage()
1.662 + {
1.663 + T handle = iHandle;
1.664 + iHandle.SetHandle(KNullHandle);
1.665 + return handle;
1.666 + }
1.667 +
1.668 + TBool IsEnabled() const
1.669 + {
1.670 + return iHandle.Handle() != KNullHandle;
1.671 + }
1.672 +
1.673 + void Disable()
1.674 + {
1.675 + iHandle.SetHandle(KNullHandle);
1.676 + }
1.677 +
1.678 + void Swap(LAutoHandleBase& aAutoHandle)
1.679 + {
1.680 + ::Swap(iHandle, aAutoHandle.iHandle);
1.681 + }
1.682 +
1.683 + protected:
1.684 + T iHandle;
1.685 +
1.686 + private:
1.687 + LAutoHandleBase(const LAutoHandleBase&);
1.688 + LAutoHandleBase& operator=(const LAutoHandleBase&);
1.689 + };
1.690 +
1.691 +
1.692 +// N.B. RBuf8, RBuf16 and RBuf cannot be used with LManagedHandle and
1.693 +// LCleanedupHandle. Use LString or managed references instead.
1.694 +// The following specialization must not be used.
1.695 +template<typename T>
1.696 +class LAutoHandleBase<T, EAutoHandleRBuf>: protected T
1.697 + {
1.698 + private:
1.699 + LAutoHandleBase()
1.700 + {
1.701 + }
1.702 +
1.703 + ~LAutoHandleBase()
1.704 + {
1.705 + }
1.706 + };
1.707 +
1.708 +
1.709 +/**
1.710 + A class template for the creation and automatic management of
1.711 + resource handles (typically R-class instances) held in the data
1.712 + members of objects.
1.713 +
1.714 + @note This class should not used to define locals. See below for
1.715 + an explanation and links to management classes suitable for use in
1.716 + that context.
1.717 +
1.718 + This class template can be used to protect a resource handle of
1.719 + type T (typically an R-class instance) such that the instance of T
1.720 + protected is automatically cleaned up when the management object is
1.721 + destroyed; typically when the object containing it is deleted.
1.722 +
1.723 + By default, the cleanup action is to call the Close() member
1.724 + function of the managed handle. An alternative cleanup strategy may
1.725 + be selected by specifying a cleanup strategy template class in the
1.726 + optional second template parameter position. The most common
1.727 + alternative cleanup strategies are predefined. It is also possible
1.728 + to specialize the default cleanup action for a given class using
1.729 + the DEFINE_CLEANUP_FUNCTION macro.
1.730 +
1.731 + The constructors of this class never leave (unless construction of
1.732 + the underlying T instance can leave, which is rare), so data
1.733 + members defined with this type may be initialized safely during any
1.734 + phase of construction of the owning class.
1.735 +
1.736 + Any arguments supplied when initializing an instance of this class
1.737 + are automatically passed through to T's constructors.
1.738 +
1.739 + As a convenience, the methods of the managed pointer may be
1.740 + accessed via "->" notation directly on the management object, while
1.741 + "." notation is used to access the interface of the management
1.742 + object itself. Using "*" to dereference the management object
1.743 + yields a T&, and is often useful when passing the managed object as
1.744 + an argument.
1.745 +
1.746 + Automatic cleanup may be disabled at any time by calling
1.747 + Unmanage(), while cleanup may be forced at any time by calling
1.748 + ReleaseResource().
1.749 +
1.750 + Example:
1.751 + @code
1.752 + class CComposite : public CBase
1.753 + {
1.754 + public:
1.755 + CONSTRUCTORS_MAY_LEAVE
1.756 +
1.757 + CComposite()
1.758 + {
1.759 + iFileServ->Connect() OR_LEAVE;
1.760 + iFile->Open(*iFileServ, ...);
1.761 + }
1.762 +
1.763 + ~CComposite()
1.764 + {
1.765 + // the handles are automatically closed
1.766 + }
1.767 +
1.768 + private:
1.769 +
1.770 + LManagedHandle<RFs> iFileServ;
1.771 + LManagedHandle<RFile> iFile;
1.772 + };
1.773 + @endcode
1.774 +
1.775 + Behind the scenes, this class template simply relies on reliable
1.776 + execution of its destructor. If used for a local variable rather
1.777 + than a data member, cleanup will occur but out-of-order compared to
1.778 + objects protected using the LCleanupXxx variants or the
1.779 + CleanupStack directly. Therefore it is not recommended for use in
1.780 + that context.
1.781 +
1.782 + These management classes may be used as the basis for implementing
1.783 + leave-safe single-phase construction, since fully initialized
1.784 + data members protected in this way will get destroyed (so reliably
1.785 + triggering cleanup) if their containing classes leave during
1.786 + execution of their constructors. Note, however, that single-phase
1.787 + construction must be explicitly enabled in the containing class
1.788 + using the CONSTRUCTORS_MAY_LEAVE macro.
1.789 +
1.790 + This class template together with the cleanup strategy class
1.791 + templates provide a template-based implementation of the Strategy
1.792 + design pattern (See also: Policy-based design).
1.793 +
1.794 + @see TClose which implements the default Close() calling cleanup strategy
1.795 + @see TResetAndDestroy which implements an alternative
1.796 + ResetAndDestroy() calling cleanup strategy
1.797 + @see TFree which implements an alternative Free() calling cleanup
1.798 + strategy
1.799 + @see TDestroy which implements an alternative Destroy() calling
1.800 + cleanup strategy
1.801 + @see TRelease which implements an alternative Release() calling cleanup strategy
1.802 + @see LCleanedupHandle which has the same interface, but uses the cleanup
1.803 + stack and is suitable for protecting locals
1.804 + @see CONSTRUCTORS_MAY_LEAVE
1.805 +*/
1.806 +template<typename T,
1.807 + class CleanupStrategyType = TResourceCleanupStrategy>
1.808 +class LManagedHandle: protected LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)>
1.809 + {
1.810 + typedef LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)> LAutoHandleBase;
1.811 +
1.812 + public:
1.813 + typedef T ManagedType;
1.814 + typedef CleanupStrategyType CleanupStrategy;
1.815 +
1.816 +/**
1.817 + Default constructor.
1.818 +*/
1.819 + LManagedHandle()
1.820 + {
1.821 + }
1.822 +
1.823 + template<typename Param1>
1.824 + explicit LManagedHandle(const Param1& aParam1)
1.825 + : LAutoHandleBase(aParam1)
1.826 + {
1.827 + }
1.828 +
1.829 + template<typename Param1>
1.830 + explicit LManagedHandle(Param1& aParam1)
1.831 + : LAutoHandleBase(aParam1)
1.832 + {
1.833 + }
1.834 +
1.835 + template<typename Param1,
1.836 + typename Param2>
1.837 + LManagedHandle(const Param1& aParam1,
1.838 + const Param2& aParam2)
1.839 + : LAutoHandleBase(aParam1,
1.840 + aParam2)
1.841 + {
1.842 + }
1.843 +
1.844 + template<typename Param1,
1.845 + typename Param2>
1.846 + LManagedHandle(const Param1& aParam1,
1.847 + Param2& aParam2)
1.848 + : LAutoHandleBase(aParam1,
1.849 + aParam2)
1.850 + {
1.851 + }
1.852 +
1.853 + template<typename Param1,
1.854 + typename Param2>
1.855 + LManagedHandle(Param1& aParam1,
1.856 + const Param2& aParam2)
1.857 + : LAutoHandleBase(aParam1,
1.858 + aParam2)
1.859 + {
1.860 + }
1.861 +
1.862 + template<typename Param1,
1.863 + typename Param2>
1.864 + LManagedHandle(Param1& aParam1,
1.865 + Param2& aParam2)
1.866 + : LAutoHandleBase(aParam1,
1.867 + aParam2)
1.868 + {
1.869 + }
1.870 +
1.871 +/**
1.872 + Assigns a new resource to be managed. If the LManagedHandle object
1.873 + already contains a managed resource handle, then the managed
1.874 + resource is released using the specified cleanup strategy before
1.875 + assigning the new managed resource.
1.876 +
1.877 + @param aHandle a reference to a handle object of a type that can be assigned to a handle object of type T
1.878 + */
1.879 + template<typename U>
1.880 + LManagedHandle& operator=(const U& aHandle)
1.881 + {
1.882 + ReleaseResource();
1.883 + LAutoHandleBase::operator=(aHandle);
1.884 + return *this;
1.885 + }
1.886 +
1.887 +/**
1.888 + Destructor. When automatic resource management is enabled, the
1.889 + destructor calls the cleanup function defined by the cleanup
1.890 + strategy with the contained resource handle object.
1.891 + */
1.892 + ~LManagedHandle()
1.893 + {
1.894 + if (IsEnabled())
1.895 + {
1.896 + CleanupStrategy::Cleanup(&Get());
1.897 + }
1.898 + }
1.899 +
1.900 +/**
1.901 + If automatic resource management is enabled, calls the cleanup
1.902 + function defined by the cleanup strategy with the managed resource
1.903 + handle object and then disables the automatic resource management
1.904 + for this object. The cleanup strategy is specified by the
1.905 + CleanupStrategy template template parameter. The default cleanup
1.906 + strategy is to call the cleanup member function on the contained
1.907 + resource handle object. which is a member function named Close(),
1.908 + unless explicitly defined otherwise for the class of the object,
1.909 + for example by using the provided DEFINE_CLEANUP_FUNCTION macro.
1.910 +*/
1.911 + void ReleaseResource()
1.912 + {
1.913 + if (!IsEnabled())
1.914 + return;
1.915 +
1.916 + CleanupStrategy::Cleanup(&Get());
1.917 + LAutoHandleBase::Disable();
1.918 + }
1.919 +
1.920 +/**
1.921 + Disables the automatic resource management for this object and
1.922 + returns a copy of the resource handle.
1.923 +
1.924 + @return A copy of the resource handle.
1.925 +*/
1.926 + using LAutoHandleBase::Unmanage;
1.927 +
1.928 +/**
1.929 + Returns ETrue if automatic resource management is enabled; EFalse
1.930 + otherwise.
1.931 +
1.932 + @return ETrue if automatic resource management is enabled; EFalse
1.933 + otherwise.
1.934 +*/
1.935 + using LAutoHandleBase::IsEnabled;
1.936 +
1.937 +/**
1.938 + Returns a reference to the resource handle.
1.939 +
1.940 + @return A reference to the resource handle.
1.941 +*/
1.942 + using LAutoHandleBase::Get;
1.943 +
1.944 +/**
1.945 + Overloaded indirection operator function.
1.946 +
1.947 + @return A reference to the resource handle.
1.948 +*/
1.949 + using LAutoHandleBase::operator*;
1.950 +
1.951 +/**
1.952 + Overloaded class member access operator function.
1.953 +
1.954 + @return A pointer to the resource handle.
1.955 +*/
1.956 + using LAutoHandleBase::operator->;
1.957 +
1.958 + using LAutoHandleBase::Disable;
1.959 +
1.960 + void Swap(LManagedHandle& aManagedHandle)
1.961 + {
1.962 + LAutoHandleBase::Swap(aManagedHandle);
1.963 + }
1.964 + };
1.965 +
1.966 +
1.967 +/**
1.968 + Implementation base class - not designed for public inheritance or
1.969 + direct use.
1.970 +
1.971 + @internalComponent
1.972 +*/
1.973 +// Not for Client Use , Only to be used Internally.
1.974 +template<typename T>
1.975 +class LAutoPtrBase
1.976 + {
1.977 + protected:
1.978 + LAutoPtrBase()
1.979 + : iPtr(NULL)
1.980 + {
1.981 + }
1.982 +
1.983 + explicit LAutoPtrBase(T* aPtr)
1.984 + : iPtr(aPtr)
1.985 + {
1.986 + }
1.987 +
1.988 + LAutoPtrBase& operator=(T* aPtr)
1.989 + {
1.990 + iPtr = aPtr;
1.991 + return *this;
1.992 + }
1.993 +
1.994 + T* Unmanage()
1.995 + {
1.996 + T* ptr = iPtr;
1.997 + iPtr = NULL;
1.998 + return ptr;
1.999 + }
1.1000 +
1.1001 + TBool IsEnabled() const
1.1002 + {
1.1003 + return iPtr != NULL;
1.1004 + }
1.1005 +
1.1006 + T* Get() const
1.1007 + {
1.1008 + return iPtr;
1.1009 + }
1.1010 +
1.1011 + T* operator->() const
1.1012 + {
1.1013 + return iPtr;
1.1014 + }
1.1015 +
1.1016 + void Disable()
1.1017 + {
1.1018 + iPtr = NULL;
1.1019 + }
1.1020 +
1.1021 + void Swap(LAutoPtrBase& aAutoPtr)
1.1022 + {
1.1023 + ::Swap(iPtr, aAutoPtr.iPtr);
1.1024 + }
1.1025 +
1.1026 + protected:
1.1027 + T* iPtr;
1.1028 +
1.1029 + private:
1.1030 + LAutoPtrBase(const LAutoPtrBase&);
1.1031 + LAutoPtrBase& operator=(const LAutoPtrBase&);
1.1032 + };
1.1033 +
1.1034 +
1.1035 +// Cleanup traits class template
1.1036 +template<typename T,
1.1037 + class CleanupStrategyType,
1.1038 + TInt isPtrSpecial = IS_PTR_SPECIAL(T)>
1.1039 +struct TPtrCleanupTraits
1.1040 + {
1.1041 + };
1.1042 +
1.1043 +
1.1044 +// Cleanup traits class template specialization for pointers to types
1.1045 +// that are not derived from CBase
1.1046 +template<typename T,
1.1047 + class CleanupStrategyType>
1.1048 +struct TPtrCleanupTraits<T, CleanupStrategyType, EPtrNonSpecial>
1.1049 + {
1.1050 + typedef T ManagedType;
1.1051 + typedef T BaseManagedType;
1.1052 + typedef CleanupStrategyType CleanupStrategy;
1.1053 + };
1.1054 +
1.1055 +// Cleanup traits class template specialization for pointers to types
1.1056 +// that are derived from CBase
1.1057 +template<typename T,
1.1058 + class CleanupStrategyType>
1.1059 +struct TPtrCleanupTraits<T, CleanupStrategyType, EPtrCBaseDerived>
1.1060 + {
1.1061 + typedef T ManagedType;
1.1062 + typedef CBase BaseManagedType;
1.1063 + typedef CleanupStrategyType CleanupStrategy;
1.1064 + };
1.1065 +
1.1066 +// Cleanup traits class template specialization for pointers to types
1.1067 +// that are derived from CBase and the default pointer cleanup
1.1068 +// strategy (TPtrCleanupStrategy)
1.1069 +template<typename T>
1.1070 +struct TPtrCleanupTraits<T, TPtrCleanupStrategy, EPtrCBaseDerived>
1.1071 + {
1.1072 + typedef CBase ManagedType;
1.1073 + typedef CBase BaseManagedType;
1.1074 + typedef TPtrCleanupStrategy CleanupStrategy;
1.1075 + };
1.1076 +
1.1077 +
1.1078 +/**
1.1079 + Implementation base class - not designed for public inheritance or
1.1080 + direct use.
1.1081 +*/
1.1082 +template<typename T,
1.1083 + class CleanupStrategyType>
1.1084 +class LManagedPtrBase: protected LAutoPtrBase<typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType>
1.1085 + {
1.1086 + typedef LAutoPtrBase<typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType> LAutoPtrBase;
1.1087 +
1.1088 + protected:
1.1089 + typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::ManagedType ManagedType;
1.1090 + typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType BaseManagedType;
1.1091 + typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::CleanupStrategy CleanupStrategy;
1.1092 +
1.1093 + LManagedPtrBase()
1.1094 + {
1.1095 + }
1.1096 +
1.1097 + template<typename U>
1.1098 + explicit LManagedPtrBase(U* aPtr)
1.1099 + : LAutoPtrBase(aPtr)
1.1100 + {
1.1101 + }
1.1102 +
1.1103 +/**
1.1104 + Destructor. When automatic resource management is enabled, the
1.1105 + destructor invokes the specified cleanup strategy for the managed
1.1106 + pointer.
1.1107 + */
1.1108 + ~LManagedPtrBase()
1.1109 + {
1.1110 + if (IsEnabled())
1.1111 + {
1.1112 + CleanupStrategy::Cleanup(static_cast<ManagedType*>(iPtr));
1.1113 + }
1.1114 + }
1.1115 +
1.1116 + template<typename U>
1.1117 + LManagedPtrBase& operator=(U* aPtr)
1.1118 + {
1.1119 + ReleaseResource();
1.1120 + LAutoPtrBase::operator=(aPtr);
1.1121 + return *this;
1.1122 + }
1.1123 +
1.1124 +/**
1.1125 + If automatic resource management is enabled, the specified cleanup
1.1126 + strategy is invoked for the managed pointer and the automatic
1.1127 + resource management is then disabled. The underlying pointer is
1.1128 + reset to NULL.
1.1129 +
1.1130 + @post Get() == NULL
1.1131 +*/
1.1132 + void ReleaseResource()
1.1133 + {
1.1134 + if (!IsEnabled())
1.1135 + return;
1.1136 +
1.1137 + CleanupStrategy::Cleanup(static_cast<ManagedType*>(iPtr));
1.1138 + LAutoPtrBase::Disable();
1.1139 + }
1.1140 +
1.1141 + using LAutoPtrBase::Unmanage;
1.1142 +
1.1143 + using LAutoPtrBase::IsEnabled;
1.1144 +
1.1145 + using LAutoPtrBase::Get;
1.1146 +
1.1147 + using LAutoPtrBase::operator->;
1.1148 +
1.1149 + using LAutoPtrBase::Disable;
1.1150 +
1.1151 + using LAutoPtrBase::iPtr;
1.1152 +
1.1153 + void Swap(LManagedPtrBase& aManagedPtr)
1.1154 + {
1.1155 + LAutoPtrBase::Swap(aManagedPtr);
1.1156 + }
1.1157 + };
1.1158 +
1.1159 +
1.1160 +/**
1.1161 + A class template that provides automatic management of pointers
1.1162 + held in the data members of objects.
1.1163 +
1.1164 + @note This class should not used to define locals. See below for
1.1165 + an explanation and links to management classes suitable for use in
1.1166 + that context.
1.1167 +
1.1168 + This class template can be used to protect a pointer to type T such
1.1169 + that the instance of T referred to is automatically cleaned up when
1.1170 + the management object is destroyed; typically when the object
1.1171 + containing it is deleted.
1.1172 +
1.1173 + By default, the cleanup action is to delete the managed pointer
1.1174 + using a (non-array) delete operation. An alternative cleanup
1.1175 + strategy can be specified using the optional CleanupStrategy class
1.1176 + template parameter of the LManagedPtr class template. The most
1.1177 + common alternative cleanup strategies are predefined
1.1178 + (e.g. TPointerFree).
1.1179 +
1.1180 + The constructors of this class never leave, so data members defined with
1.1181 + this type may be initialized safely during any phase of
1.1182 + construction of the owning class.
1.1183 +
1.1184 + As a convenience, the methods of the managed pointer may be
1.1185 + accessed via "->" notation directly on the management object, while
1.1186 + "." notation is used to access the interface of the management
1.1187 + object itself. Using "*" to dereference the management object
1.1188 + yields a T&, and is often useful when passing the managed object as
1.1189 + an argument.
1.1190 +
1.1191 + Automatic cleanup may be disabled at any time by calling
1.1192 + Unmanage(), while cleanup may be forced at any time by calling
1.1193 + ReleaseResource().
1.1194 +
1.1195 + Example:
1.1196 + @code
1.1197 + class CComposite : public CBase
1.1198 + {
1.1199 + public:
1.1200 + CONSTRUCTORS_MAY_LEAVE
1.1201 +
1.1202 + CComposite()
1.1203 + : iComponent(CComponent::NewL())
1.1204 + {
1.1205 + //...
1.1206 + }
1.1207 +
1.1208 + ~CComposite()
1.1209 + {
1.1210 + // the pointer to the CComponent object is automatically
1.1211 + // deleted
1.1212 + }
1.1213 +
1.1214 + private:
1.1215 + LManagedPtr<CComponent> iComponent;
1.1216 + };
1.1217 + @endcode
1.1218 +
1.1219 + Behind the scenes, this class template simply relies on reliable
1.1220 + execution of its destructor. If used for a local variable rather
1.1221 + than a data member, cleanup will occur but out-of-order compared to
1.1222 + objects protected using the LCleanupXxx variants or the
1.1223 + CleanupStack directly. Therefore it is not recommended for use in
1.1224 + that context.
1.1225 +
1.1226 + These management classes may be used as the basis for implementing
1.1227 + leave-safe single-phase construction, since fully initialized
1.1228 + data members protected in this way will get destroyed (so reliably
1.1229 + triggering cleanup) if their containing classes leave during
1.1230 + execution of their constructors. Note, however, that single-phase
1.1231 + construction must be explicitly enabled in the containing class
1.1232 + using the CONSTRUCTORS_MAY_LEAVE macro.
1.1233 +
1.1234 + This class template together with the cleanup strategy class
1.1235 + templates provide a template-based implementation of the Strategy
1.1236 + design pattern (See also: Policy-based design).
1.1237 +
1.1238 + @see TPointerDelete which implements the default deleting cleanup strategy
1.1239 + @see TPointerFree which implements the alternative User::Free() cleanup strategy
1.1240 + @see LCleanedupPtr which has the same interface, but uses the cleanup
1.1241 + stack and is suitable for protecting locals
1.1242 + @see CONSTRUCTORS_MAY_LEAVE
1.1243 +*/
1.1244 +template<typename T,
1.1245 + class CleanupStrategyType = TPtrCleanupStrategy>
1.1246 +class LManagedPtr: protected LManagedPtrBase<T, CleanupStrategyType>
1.1247 + {
1.1248 + typedef LManagedPtrBase<T, CleanupStrategyType> LManagedPtrBase;
1.1249 +
1.1250 + public:
1.1251 + typedef T ManagedType;
1.1252 + typedef CleanupStrategyType CleanupStrategy;
1.1253 +
1.1254 +
1.1255 +/**
1.1256 + Default constructor. Constructs an empty LManagedPtr object.
1.1257 +
1.1258 + @post Get() == NULL
1.1259 + */
1.1260 + LManagedPtr()
1.1261 + {
1.1262 + }
1.1263 +
1.1264 +/**
1.1265 + Explicit constructor template. Constructs a LManagedPtr object
1.1266 + that manages the pointer aPtr of a type convertible to T* that can
1.1267 + be cleaned up using the cleanup strategy of the LManagedPtr class.
1.1268 + The default cleanup strategy is to delete the pointer to a
1.1269 + heap-allocated object by using non-array delete. Alternative
1.1270 + cleanup strategies can be specified by using the CleanupStrategy
1.1271 + template parameter of the LManagedPtr class template.
1.1272 +
1.1273 + @param aPtr A pointer of a type that is convertible to T* that can
1.1274 + be cleaned up using the cleanup strategy.
1.1275 +
1.1276 + @pre aPtr is of a type convertible to T* and can be cleaned up
1.1277 + using the cleanup strategy.
1.1278 +
1.1279 + @post Get() == aPtr
1.1280 + */
1.1281 + explicit LManagedPtr(T* aPtr)
1.1282 + : LManagedPtrBase(aPtr)
1.1283 + {
1.1284 + }
1.1285 +
1.1286 +/**
1.1287 + Destructor. When automatic resource management is enabled, the
1.1288 + destructor invokes the specified cleanup strategy for the managed
1.1289 + pointer.
1.1290 + */
1.1291 +
1.1292 +
1.1293 +/**
1.1294 + Assigns a new pointer to be managed. The new pointer must be of a
1.1295 + type convertible to T* and it must be possible to use the cleanup
1.1296 + strategy of the LManagedPtr object for the cleanup of the new
1.1297 + managed pointer. If the LManagedPtr object already contains a
1.1298 + managed pointer, then the cleanup strategy is invoked with the
1.1299 + managed pointer before assigning the new managed pointer.
1.1300 +
1.1301 + @param aPtr A pointer of a type that is convertible to T* that can
1.1302 + be cleaned up using the cleanup strategy.
1.1303 +
1.1304 + @pre aPtr is a pointer of a type that is convertible to T* and can
1.1305 + be cleaned up using the cleanup strategy.
1.1306 +
1.1307 + @post Get() == aPtr
1.1308 + */
1.1309 + LManagedPtr& operator=(T* aPtr)
1.1310 + {
1.1311 + LManagedPtrBase::operator=(aPtr);
1.1312 + return *this;
1.1313 + }
1.1314 +
1.1315 +/**
1.1316 + Assigns a new pointer to be managed. The new pointer must be of a
1.1317 + type convertible to T* and it must be possible to use the cleanup
1.1318 + strategy of the LManagedPtr object for the cleanup of the new
1.1319 + managed pointer. If the LManagedPtr object already contains a
1.1320 + managed pointer, then the cleanup strategy is invoked with the
1.1321 + managed pointer before assigning the new managed pointer.
1.1322 +
1.1323 + @param aPtr A pointer of a type that is convertible to T* that can
1.1324 + be cleaned up using the cleanup strategy.
1.1325 +
1.1326 + @pre aPtr is a pointer of a type that is convertible to T* and can
1.1327 + be cleaned up using the cleanup strategy.
1.1328 +
1.1329 + @post Get() == aPtr
1.1330 + */
1.1331 + template<typename U>
1.1332 + LManagedPtr& operator=(U* aPtr)
1.1333 + {
1.1334 + LManagedPtrBase::operator=(aPtr);
1.1335 + return *this;
1.1336 + }
1.1337 +
1.1338 + using LManagedPtrBase::ReleaseResource;
1.1339 +
1.1340 +/**
1.1341 + Disables the automatic resource management for this object and
1.1342 + returns a pointer to the object of type T.
1.1343 +
1.1344 + @return A pointer to the object of type T.
1.1345 +*/
1.1346 + T* Unmanage()
1.1347 + {
1.1348 + return static_cast<T*>(LManagedPtrBase::Unmanage());
1.1349 + }
1.1350 +
1.1351 +/**
1.1352 + Returns ETrue if automatic resource management is enabled; EFalse
1.1353 + otherwise.
1.1354 +
1.1355 + @return ETrue if automatic resource management is enabled; EFalse
1.1356 + otherwise.
1.1357 +*/
1.1358 + using LManagedPtrBase::IsEnabled;
1.1359 +
1.1360 +/**
1.1361 + Returns a pointer to the managed object of type T.
1.1362 +
1.1363 + @return A pointer to the managed object of type T.
1.1364 +*/
1.1365 + T* Get() const
1.1366 + {
1.1367 + return static_cast<T*>(iPtr);
1.1368 + }
1.1369 +
1.1370 +/**
1.1371 + Overloaded indirection operator function.
1.1372 +
1.1373 + @return A reference to the managed object of type T.
1.1374 +*/
1.1375 + T& operator*() const
1.1376 + {
1.1377 + return *(static_cast<T*>(iPtr));
1.1378 + }
1.1379 +
1.1380 +/**
1.1381 + Overloaded class member access operator function.
1.1382 +
1.1383 + @return A pointer to the managed object of type T.
1.1384 +*/
1.1385 + T* operator->() const
1.1386 + {
1.1387 + return static_cast<T*>(iPtr);
1.1388 + }
1.1389 +
1.1390 +
1.1391 +// Implementation type - do not use
1.1392 + typedef typename LManagedPtrBase::BaseManagedType* LManagedPtr<T, CleanupStrategy>::*TUnspecifiedBoolType;
1.1393 +
1.1394 +/**
1.1395 + Conversion operator that enables LCleanedupPtr objects to be used
1.1396 + in boolean contexts.
1.1397 +
1.1398 + @return An unspecified value of an unspecified type convertible to
1.1399 + boolean, which has a boolean value equal to Get() != NULL
1.1400 + */
1.1401 + operator TUnspecifiedBoolType()
1.1402 + {
1.1403 + return iPtr ? &LManagedPtr::iPtr : NULL;
1.1404 + }
1.1405 +
1.1406 +
1.1407 + using LManagedPtrBase::Disable;
1.1408 +
1.1409 + void Swap(LManagedPtr& aManagedPtr)
1.1410 + {
1.1411 + LManagedPtrBase::Swap(aManagedPtr);
1.1412 + }
1.1413 +
1.1414 + private:
1.1415 + using LManagedPtrBase::iPtr;
1.1416 + };
1.1417 +
1.1418 +
1.1419 +// function template used for comparing two LManagedPtr-managed
1.1420 +// pointers for equality
1.1421 +template<typename T, typename U>
1.1422 +TBool operator==(const LManagedPtr<T>& aPtr1, const LManagedPtr<U>& aPtr2)
1.1423 + {
1.1424 + return aPtr1.Get() == aPtr2.Get();
1.1425 + }
1.1426 +
1.1427 +// function template used for comparing two LManagedPtr-managed
1.1428 +// pointers for inequality
1.1429 +template<typename T, typename U>
1.1430 +TBool operator!=(const LManagedPtr<T>& aPtr1, const LManagedPtr<U>& aPtr2)
1.1431 + {
1.1432 + return aPtr1.Get() != aPtr2.Get();
1.1433 + }
1.1434 +
1.1435 +// function template used for testing the ordering of two
1.1436 +// LManagedPtr-managed pointers
1.1437 +template<typename T, typename U>
1.1438 +TBool operator<(const LManagedPtr<T>& aPtr1, const LManagedPtr<U>& aPtr2)
1.1439 + {
1.1440 + return aPtr1.Get() < aPtr2.Get();
1.1441 + }
1.1442 +
1.1443 +
1.1444 +/**
1.1445 + A class template that provides automatic management of arrays. Such
1.1446 + managed arrays can be data members of composite classes.
1.1447 +
1.1448 + @note This class should not used to define locals. See below for
1.1449 + an explanation and links to management classes suitable for use in
1.1450 + that context.
1.1451 +
1.1452 + @par
1.1453 +
1.1454 + @note This class can only be used with raw arrays, which are used
1.1455 + only rarely on Symbian OS. Instances of Symbian array container
1.1456 + classes (e.g. RArray, RPointerArray) should be managed using the
1.1457 + automatic management template classes appropriate for the array's
1.1458 + type (LManagedHandle template classes for Symbian R arrays or
1.1459 + LManagedPtr template classes for Symbian C arrays).
1.1460 +
1.1461 + This class template can be used to protect a heap-allocated array
1.1462 + of objects of type T such that the managed array is automatically
1.1463 + deallocated when the management object is destroyed.
1.1464 +
1.1465 + The default cleanup strategy is to deallocate the managed array
1.1466 + using arrray delete (delete[]), assuming that the array is
1.1467 + heap-allocated. An alternative cleanup strategy can be selected by
1.1468 + specifying a cleanup strategy template class as the optional second
1.1469 + template argument (corresponding to the CleanupStrategy template
1.1470 + parameter).
1.1471 +
1.1472 + The constructors of this class never leave, so data members defined with
1.1473 + this type may be initialized safely during any phase of
1.1474 + construction of the owning class.
1.1475 +
1.1476 + As a convenience, the elements of the managed array may be accessed
1.1477 + via "[]" notation directly on the management object.
1.1478 +
1.1479 + Automatic cleanup may be disabled at any time by calling
1.1480 + Unmanage(), while cleanup may be forced at any time by calling
1.1481 + ReleaseResource().
1.1482 +
1.1483 +
1.1484 + Example:
1.1485 + @code
1.1486 + class CComposite : public CBase
1.1487 + {
1.1488 + public:
1.1489 + CONSTRUCTORS_MAY_LEAVE
1.1490 +
1.1491 + CComposite()
1.1492 + : iComponents(new(ELeave) CComponent[KNumComponents])
1.1493 + {
1.1494 + //...
1.1495 + }
1.1496 +
1.1497 + ~CComposite()
1.1498 + {
1.1499 + // the array is automatically deleted
1.1500 + }
1.1501 +
1.1502 + private:
1.1503 + LManagedArray<CComponent> iComponents;
1.1504 + };
1.1505 + @endcode
1.1506 +
1.1507 +
1.1508 + Behind the scenes, this class template simply relies on reliable
1.1509 + execution of its destructor. If used for a local variable rather
1.1510 + than a data member, cleanup will occur but out-of-order compared to
1.1511 + objects protected using the LCleanupXxx variants or the
1.1512 + CleanupStack directly. Therefore it is not recommended for use in
1.1513 + that context.
1.1514 +
1.1515 + These management classes may be used as the basis for implementing
1.1516 + leave-safe single-phase construction, since fully initialized
1.1517 + data members protected in this way will get destroyed (so reliably
1.1518 + triggering cleanup) if their containing classes leave during
1.1519 + execution of their constructors. Note, however, that single-phase
1.1520 + construction must be explicitly enabled in the containing class
1.1521 + using the CONSTRUCTORS_MAY_LEAVE macro.
1.1522 +
1.1523 + This class template together with the cleanup strategy class
1.1524 + templates provide a template-based implementation of the Strategy
1.1525 + design pattern (See also: Policy-based design).
1.1526 +
1.1527 + @see LCleanedupArray which has the same interface, but uses the cleanup
1.1528 + stack and is suitable for protecting locals
1.1529 + @see CONSTRUCTORS_MAY_LEAVE
1.1530 +*/
1.1531 +template<typename T,
1.1532 + class CleanupStrategyType = TArrayDelete>
1.1533 +class LManagedArray: protected LAutoPtrBase<T>
1.1534 + {
1.1535 + typedef LAutoPtrBase<T> LAutoPtrBase;
1.1536 +
1.1537 + public:
1.1538 + typedef T ManagedType;
1.1539 + typedef CleanupStrategyType CleanupStrategy;
1.1540 +
1.1541 +/**
1.1542 + Default constructor. Constructs an empty LManagedArray object.
1.1543 +
1.1544 + @post Get() == NULL
1.1545 + */
1.1546 + LManagedArray()
1.1547 + {
1.1548 + }
1.1549 +
1.1550 +/**
1.1551 + Explicit constructor. Constructs a LManagedArray object that
1.1552 + manages an array of objects of type T that can be cleaned up using
1.1553 + the cleanup strategy of the LManagedArray class. The default
1.1554 + cleanup strategy is to deallocate the managed array by using array
1.1555 + delete (delete[]), assuming that the array is heap-allocated.
1.1556 + Alternative cleanup strategies can be specified by using the
1.1557 + CleanupStrategy template parameter of the LManagedArray class
1.1558 + template.
1.1559 +
1.1560 + @param aPtr A pointer to the first element of an array of objects
1.1561 + of type T - array that can be cleaned up using the cleanup strategy
1.1562 + of the the LManagedArray class.
1.1563 +
1.1564 + @pre The array can be cleaned up using the cleanup strategy.
1.1565 +
1.1566 + @post Get() == aPtr
1.1567 + */
1.1568 + explicit LManagedArray(T* aPtr)
1.1569 + : LAutoPtrBase(aPtr)
1.1570 + {
1.1571 + }
1.1572 +
1.1573 +/**
1.1574 + Destructor. When automatic resource management is enabled, the
1.1575 + destructor invokes the specified cleanup strategy for the managed
1.1576 + pointer.
1.1577 + */
1.1578 + ~LManagedArray()
1.1579 + {
1.1580 + if (LAutoPtrBase::IsEnabled())
1.1581 + {
1.1582 + CleanupStrategy::Cleanup(iPtr);
1.1583 + }
1.1584 + }
1.1585 +
1.1586 +/**
1.1587 + Assigns a new array of objects of type T to be managed. It needs
1.1588 + to be possible use the cleanup strategy of the LManagedArray object
1.1589 + for the cleanup of the new managed array. The default cleanup
1.1590 + strategy is to delete the heap-allocated array by using array
1.1591 + delete (delete[]). If the LManagedArray object already manages an
1.1592 + array, then the cleanup strategy is invoked with the managed array
1.1593 + before assigning the new managed array.
1.1594 +
1.1595 + @param aPtr A pointer to the first element of the array of objects
1.1596 + of type T - array that can be cleaned up using the cleanup
1.1597 + strategy.
1.1598 +
1.1599 + @pre The new array to be managed can be cleaned up using the
1.1600 + cleanup strategy.
1.1601 +
1.1602 + @post Get() == aPtr
1.1603 + */
1.1604 + LManagedArray& operator=(T* aPtr)
1.1605 + {
1.1606 + ReleaseResource();
1.1607 + LAutoPtrBase::operator=(aPtr);
1.1608 + return *this;
1.1609 + }
1.1610 +
1.1611 +/**
1.1612 + If automatic resource management is enabled, the specified cleanup
1.1613 + strategy is invoked for the managed pointer and the automatic
1.1614 + resource management is then disabled. The underlying pointer is
1.1615 + reset to NULL.
1.1616 +
1.1617 + @post Get() == NULL
1.1618 +*/
1.1619 + void ReleaseResource()
1.1620 + {
1.1621 + if (!LAutoPtrBase::IsEnabled())
1.1622 + return;
1.1623 +
1.1624 + CleanupStrategy::Cleanup(iPtr);
1.1625 + LAutoPtrBase::Disable();
1.1626 + }
1.1627 +
1.1628 +/**
1.1629 + Disables the automatic resource management for this object and
1.1630 + returns a pointer to the first element of the array of objects of
1.1631 + type T.
1.1632 +
1.1633 + @return A pointer to the first element of the array of objects of
1.1634 + type T.
1.1635 +*/
1.1636 + T* Unmanage()
1.1637 + {
1.1638 + return static_cast<T*>(LAutoPtrBase::Unmanage());
1.1639 + }
1.1640 +
1.1641 +/**
1.1642 + Returns ETrue if automatic resource management is enabled; EFalse
1.1643 + otherwise.
1.1644 +
1.1645 + @return ETrue if automatic resource management is enabled; EFalse
1.1646 + otherwise.
1.1647 +*/
1.1648 + using LAutoPtrBase::IsEnabled;
1.1649 +
1.1650 +/**
1.1651 + Returns a pointer to the first element of the managed array of
1.1652 + objects of type T.
1.1653 +
1.1654 + @return A pointer to the first element of the managed array of
1.1655 + objects of type T.
1.1656 +*/
1.1657 + using LAutoPtrBase::Get;
1.1658 +
1.1659 +/**
1.1660 + Overloaded subscript operator.
1.1661 +
1.1662 + @return A reference to the object of type T at the position aIndex.
1.1663 + */
1.1664 + T& operator[](TInt aIndex) const
1.1665 + {
1.1666 + return iPtr[aIndex];
1.1667 + }
1.1668 +
1.1669 + using LAutoPtrBase::Disable;
1.1670 +
1.1671 + void Swap(LManagedArray& aArray)
1.1672 + {
1.1673 + LAutoPtrBase::Swap(aArray);
1.1674 + }
1.1675 +
1.1676 + private:
1.1677 + using LAutoPtrBase::iPtr;
1.1678 + };
1.1679 +
1.1680 +
1.1681 +/**
1.1682 + Implementation base class - not designed for public inheritance or
1.1683 + direct use.
1.1684 +
1.1685 + @internalComponent
1.1686 +*/
1.1687 +// Not for Client Use , Only to be used Internally.
1.1688 +template<typename T>
1.1689 +class LAutoRefBase
1.1690 + {
1.1691 + protected:
1.1692 + template<typename U>
1.1693 + explicit LAutoRefBase(U& aRef)
1.1694 + : iPtr(&aRef)
1.1695 + {
1.1696 + }
1.1697 +
1.1698 + template<typename U>
1.1699 + LAutoRefBase& operator=(U& aRef)
1.1700 + {
1.1701 + iPtr = &aRef;
1.1702 + return *this;
1.1703 + }
1.1704 +
1.1705 + T& Unmanage()
1.1706 + {
1.1707 + T* ptr = iPtr;
1.1708 + iPtr = NULL;
1.1709 + return *ptr;
1.1710 + }
1.1711 +
1.1712 + TBool IsEnabled() const
1.1713 + {
1.1714 + return iPtr != NULL;
1.1715 + }
1.1716 +
1.1717 + T& Get() const
1.1718 + {
1.1719 + return *iPtr;
1.1720 + }
1.1721 +
1.1722 + T& operator*() const
1.1723 + {
1.1724 + return *iPtr;
1.1725 + }
1.1726 +
1.1727 + T* operator->() const
1.1728 + {
1.1729 + return iPtr;
1.1730 + }
1.1731 +
1.1732 + void Disable()
1.1733 + {
1.1734 + iPtr = NULL;
1.1735 + }
1.1736 +
1.1737 + void Swap(LAutoRefBase& aAutoRef)
1.1738 + {
1.1739 + ::Swap(iPtr, aAutoRef.iPtr);
1.1740 + }
1.1741 +
1.1742 + protected:
1.1743 + T* iPtr;
1.1744 +
1.1745 + private:
1.1746 + LAutoRefBase(const LAutoRefBase&);
1.1747 + LAutoRefBase& operator=(const LAutoRefBase&);
1.1748 + };
1.1749 +
1.1750 +
1.1751 +/**
1.1752 + A class template that provides automatic management of references
1.1753 + to resource handles (often R-class instances) held in the data
1.1754 + members of objects.
1.1755 +
1.1756 + @note This class should not used to define locals. See below for
1.1757 + an explanation and links to management classes suitable for use in
1.1758 + that context.
1.1759 +
1.1760 + Unlike LManagedHandle which creates a fresh instance of its managed
1.1761 + type, this class template can be used to protect an existing
1.1762 + resource handle of type T (typically an R-class instance). The
1.1763 + instance of T referred to has a cleanup operation run on it
1.1764 + automatically when the management object is destroyed; typically
1.1765 + when the object containing it is deleted.
1.1766 +
1.1767 + By default, the cleanup action is to call the Close() member
1.1768 + function of the referenced handle. An alternative cleanup strategy may
1.1769 + be selected by specifying a cleanup strategy template class in the
1.1770 + optional second template parameter position. The most common
1.1771 + alternative cleanup strategies are predefined. It is also possible
1.1772 + to specialize the default cleanup action for a given class using
1.1773 + the DEFINE_CLEANUP_FUNCTION macro.
1.1774 +
1.1775 + The constructors of this class never leave, so data members defined with
1.1776 + this type may be initialized safely during any phase of
1.1777 + construction of the owning class.
1.1778 +
1.1779 + As a convenience, the methods of the managed pointer may be
1.1780 + accessed via "->" notation directly on the management object, while
1.1781 + "." notation is used to access the interface of the management
1.1782 + object itself. Using "*" to dereference the management object
1.1783 + yields a T&, and is often useful when passing the managed object as
1.1784 + an argument.
1.1785 +
1.1786 + Automatic cleanup may be disabled at any time by calling
1.1787 + Unmanage(), while cleanup may be forced at any time by calling
1.1788 + ReleaseResource().
1.1789 +
1.1790 + Example:
1.1791 + @code
1.1792 + class CComposite : public CBase
1.1793 + {
1.1794 + public:
1.1795 + CONSTRUCTORS_MAY_LEAVE
1.1796 +
1.1797 + // An existing RFs instance is given to us to reuse, but
1.1798 + // we are responsible for calling Close() when we're done
1.1799 + CComposite(RFs& aFs)
1.1800 + : iFileServ(aFs)
1.1801 + {
1.1802 + iFileServ->Connect() OR_LEAVE;
1.1803 + iFile->Open(*iFileServ, ...);
1.1804 + }
1.1805 +
1.1806 + ~CComposite()
1.1807 + {
1.1808 + // the handles are automatically closed
1.1809 + }
1.1810 +
1.1811 + private:
1.1812 +
1.1813 + LManagedRef<RFs> iFileServ;
1.1814 + LManagedHandle<RFile> iFile;
1.1815 + };
1.1816 + @endcode
1.1817 +
1.1818 + Behind the scenes, this class template simply relies on reliable
1.1819 + execution of its destructor. If used for a local variable rather
1.1820 + than a data member, cleanup will occur but out-of-order compared to
1.1821 + objects protected using the LCleanupXxx variants or the
1.1822 + CleanupStack directly. Therefore it is not recommended for use in
1.1823 + that context.
1.1824 +
1.1825 + These management classes may be used as the basis for implementing
1.1826 + leave-safe single-phase construction, since fully initialized
1.1827 + data members protected in this way will get destroyed (so reliably
1.1828 + triggering cleanup) if their containing classes leave during
1.1829 + execution of their constructors. Note, however, that single-phase
1.1830 + construction must be explicitly enabled in the containing class
1.1831 + using the CONSTRUCTORS_MAY_LEAVE macro.
1.1832 +
1.1833 + This class template together with the cleanup strategy class
1.1834 + templates provide a template-based implementation of the Strategy
1.1835 + design pattern (See also: Policy-based design).
1.1836 +
1.1837 + @see TClose which implements the default Close() calling cleanup strategy
1.1838 + @see TResetAndDestroy which implements an alternative
1.1839 + ResetAndDestroy() calling cleanup strategy
1.1840 + @see TFree which implements an alternative Free() calling cleanup
1.1841 + strategy
1.1842 + @see TDestroy which implements an alternative Destroy() calling
1.1843 + cleanup strategy
1.1844 + @see TRelease which implements an alternative Release() calling
1.1845 + cleanup strategy
1.1846 + @see LCleanedupRef which has the same interface, but uses the cleanup
1.1847 + stack and is suitable for protecting locals
1.1848 + @see LManagedHandle which has a similar interface but creates a fresh
1.1849 + local instance of T
1.1850 + @see CONSTRUCTORS_MAY_LEAVE
1.1851 +*/
1.1852 +template<typename T,
1.1853 + class CleanupStrategyType = TResourceCleanupStrategy>
1.1854 +class LManagedRef: protected LAutoRefBase<T>
1.1855 + {
1.1856 + typedef LAutoRefBase<T> LAutoRefBase;
1.1857 +
1.1858 + public:
1.1859 + typedef T ManagedType;
1.1860 + typedef CleanupStrategyType CleanupStrategy;
1.1861 +
1.1862 +/**
1.1863 + Explicit constructor.
1.1864 + */
1.1865 + template<typename U>
1.1866 + explicit LManagedRef(U& aRef)
1.1867 + : LAutoRefBase(aRef)
1.1868 + {
1.1869 + }
1.1870 +
1.1871 +/**
1.1872 + Destructor. When automatic resource management is enabled, the
1.1873 + destructor invokes the specified cleanup strategy for the managed
1.1874 + reference.
1.1875 + */
1.1876 + ~LManagedRef()
1.1877 + {
1.1878 + if (LAutoRefBase::IsEnabled())
1.1879 + {
1.1880 + CleanupStrategy::Cleanup(iPtr);
1.1881 + }
1.1882 + }
1.1883 +
1.1884 +/**
1.1885 + Assigns a new reference to be managed. If the LManagedRef
1.1886 + object already contains a managed reference, then the specified
1.1887 + cleanup strategy is invoked for the managed reference before
1.1888 + assigning the new managed reference.
1.1889 + */
1.1890 + template<typename U>
1.1891 + LManagedRef& operator=(U& aRef)
1.1892 + {
1.1893 + ReleaseResource();
1.1894 + LAutoRefBase::operator=(aRef);
1.1895 + return *this;
1.1896 + }
1.1897 +
1.1898 +/**
1.1899 + If automatic resource management is enabled, the specified cleanup
1.1900 + strategy is invoked for the managed reference and the automatic
1.1901 + resource management is then disabled for this object.
1.1902 +*/
1.1903 + void ReleaseResource()
1.1904 + {
1.1905 + if (!LAutoRefBase::IsEnabled())
1.1906 + return;
1.1907 +
1.1908 + CleanupStrategy::Cleanup(iPtr);
1.1909 + LAutoRefBase::Disable();
1.1910 + }
1.1911 +
1.1912 +/**
1.1913 + Disables the automatic resource management for this object and
1.1914 + returns a reference to the object of type T.
1.1915 +
1.1916 + @return A reference to the object of type T.
1.1917 +*/
1.1918 + using LAutoRefBase::Unmanage;
1.1919 +
1.1920 +/**
1.1921 + Returns ETrue if automatic resource management is enabled; EFalse
1.1922 + otherwise.
1.1923 +
1.1924 + @return ETrue if automatic resource management is enabled; EFalse
1.1925 + otherwise.
1.1926 +*/
1.1927 + using LAutoRefBase::IsEnabled;
1.1928 +
1.1929 +/**
1.1930 + Returns a reference to the managed object of type T.
1.1931 +
1.1932 + @return A reference to the managed object of type T.
1.1933 +*/
1.1934 + using LAutoRefBase::Get;
1.1935 +
1.1936 +/**
1.1937 + Overloaded indirection operator function.
1.1938 +
1.1939 + @return A reference to the managed object of type T.
1.1940 +*/
1.1941 + using LAutoRefBase::operator*;
1.1942 +
1.1943 +/**
1.1944 + Overloaded class member access operator function.
1.1945 +
1.1946 + @return A pointer to the managed object of type T.
1.1947 +*/
1.1948 + using LAutoRefBase::operator->;
1.1949 +
1.1950 + using LAutoRefBase::Disable;
1.1951 +
1.1952 + void Swap(LManagedRef& aRef)
1.1953 + {
1.1954 + LAutoRefBase::Swap(aRef);
1.1955 + }
1.1956 +
1.1957 + private:
1.1958 + using LAutoRefBase::iPtr;
1.1959 + };
1.1960 +
1.1961 +
1.1962 +/**
1.1963 + A class template for the creation and CleanupStack-based
1.1964 + local-scope automatic management of resource handles (typically
1.1965 + instances of R-classes).
1.1966 +
1.1967 + @note This class can only be used to define locals, never
1.1968 + data members. See below for an explanation and links to management
1.1969 + classes suitable for use in different contexts. It should never be
1.1970 + used in the same function as code that uses the CleanupStack API
1.1971 + directly.
1.1972 +
1.1973 + This class template can be used to create and protect a resource
1.1974 + handle of type T (typically a R-class) such that the instance of T
1.1975 + referred to is automatically cleaned up when either of the
1.1976 + following occur:
1.1977 +
1.1978 + - The referring local variable goes out of scope normally
1.1979 + - The referring local variable goes out of scope due to an
1.1980 + untrapped leave causing the scope to be exited non-locally
1.1981 +
1.1982 + By default, the cleanup action is to call the Close() member
1.1983 + function of the managed handle. An alternative cleanup strategy may
1.1984 + be selected by specifying a cleanup strategy template class in the
1.1985 + optional second template parameter position. The most common
1.1986 + alternative cleanup strategies are predefined. It is also possible
1.1987 + to specialize the default cleanup action for a given class using
1.1988 + the DEFINE_CLEANUP_FUNCTION macro.
1.1989 +
1.1990 + The constructors of this class may leave.
1.1991 +
1.1992 + Any arguments supplied when initializing an instance of this class
1.1993 + are automatically passed through to T's constructors.
1.1994 +
1.1995 + As a convenience, the methods of the managed handle may be
1.1996 + accessed via "->" notation directly on the management object, while
1.1997 + "." notation is used to access the interface of the management
1.1998 + object itself. Using "*" to dereference the management object
1.1999 + yields a T&, and is often useful when passing the managed object as
1.2000 + an argument.
1.2001 +
1.2002 + Automatic cleanup may be disabled at any time by calling
1.2003 + Unmanage(), while cleanup may be forced at any time by calling
1.2004 + ReleaseResource().
1.2005 +
1.2006 + Example:
1.2007 + @code
1.2008 + // block scope example
1.2009 + {
1.2010 + LCleanedupHandle<RClosable> obj;
1.2011 + obj->DoSomethingL(); // leave-safe
1.2012 + if (obj->Finished())
1.2013 + return; // RClosable::Close is invoked automatically
1.2014 + obj->DoSomethingElseL(); // leave-safe
1.2015 + // RClosable::Close is invoked automatically
1.2016 + }
1.2017 + @endcode
1.2018 +
1.2019 + Behind the scenes, this class template is implemented in terms of
1.2020 + the thread-local CleanupStack, restricting its use to locals on the
1.2021 + stack. This use of the CleanupStack ensures a consistent cleanup
1.2022 + order between functions that call one another, even if they use
1.2023 + different cleanup idioms.
1.2024 +
1.2025 + This class template together with the cleanup strategy class
1.2026 + templates provide a template-based implementation of the Strategy
1.2027 + design pattern (See also: Policy-based design).
1.2028 +
1.2029 + @see TClose which implements the default Close() calling cleanup strategy
1.2030 + @see TResetAndDestroy which implements an alternative
1.2031 + ResetAndDestroy() calling cleanup strategy
1.2032 + @see TFree which implements an alternative Free() calling cleanup
1.2033 + strategy
1.2034 + @see TDestroy which implements an alternative Destroy() calling
1.2035 + cleanup strategy
1.2036 + @see TRelease which implements an alternative Release() calling cleanup strategy
1.2037 + @see LManagedHandle which has the same interface, but does not use the cleanup
1.2038 + stack and is suitable for protecting the data members of classes
1.2039 +*/
1.2040 +template<typename T,
1.2041 + class CleanupStrategyType = TResourceCleanupStrategy>
1.2042 +class LCleanedupHandle: protected LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)>
1.2043 + {
1.2044 + typedef LAutoHandleBase<T, IS_HANDLE_SPECIAL(T)> LAutoHandleBase;
1.2045 +
1.2046 + public:
1.2047 + typedef T ManagedType;
1.2048 + typedef CleanupStrategyType CleanupStrategy;
1.2049 +
1.2050 +
1.2051 +/**
1.2052 + Default constructor.
1.2053 +*/
1.2054 + LCleanedupHandle()
1.2055 + {
1.2056 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2057 + }
1.2058 +
1.2059 + template<typename Param1>
1.2060 + explicit LCleanedupHandle(const Param1& aParam1)
1.2061 + : LAutoHandleBase(aParam1)
1.2062 + {
1.2063 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2064 + }
1.2065 +
1.2066 + template<typename Param1>
1.2067 + explicit LCleanedupHandle(Param1& aParam1)
1.2068 + : LAutoHandleBase(aParam1)
1.2069 + {
1.2070 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2071 + }
1.2072 +
1.2073 + template<typename Param1,
1.2074 + typename Param2>
1.2075 + LCleanedupHandle(const Param1& aParam1,
1.2076 + const Param2& aParam2)
1.2077 + : LAutoHandleBase(aParam1,
1.2078 + aParam2)
1.2079 + {
1.2080 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2081 + }
1.2082 +
1.2083 + template<typename Param1,
1.2084 + typename Param2>
1.2085 + LCleanedupHandle(const Param1& aParam1,
1.2086 + Param2& aParam2)
1.2087 + : LAutoHandleBase(aParam1,
1.2088 + aParam2)
1.2089 + {
1.2090 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2091 + }
1.2092 +
1.2093 + template<typename Param1,
1.2094 + typename Param2>
1.2095 + LCleanedupHandle(Param1& aParam1,
1.2096 + const Param2& aParam2)
1.2097 + : LAutoHandleBase(aParam1,
1.2098 + aParam2)
1.2099 + {
1.2100 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2101 + }
1.2102 +
1.2103 + template<typename Param1,
1.2104 + typename Param2>
1.2105 + LCleanedupHandle(Param1& aParam1,
1.2106 + Param2& aParam2)
1.2107 + : LAutoHandleBase(aParam1,
1.2108 + aParam2)
1.2109 + {
1.2110 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2111 + }
1.2112 +
1.2113 +
1.2114 + ~LCleanedupHandle()
1.2115 + {
1.2116 + ManagedPopCleanupStackItem(IsEnabled());
1.2117 + }
1.2118 +
1.2119 +/**
1.2120 + Assigns a new resource to be managed. If the LCleanedupHandle
1.2121 + object already contains a managed resource handle, then the managed
1.2122 + resource is released using the specified cleanup strategy before
1.2123 + assigning the new managed resource.
1.2124 + */
1.2125 + template<typename U>
1.2126 + LCleanedupHandle& operator=(const U& aHandle)
1.2127 + {
1.2128 + ReleaseResource();
1.2129 + LAutoHandleBase::operator=(aHandle);
1.2130 + return *this;
1.2131 + }
1.2132 +
1.2133 +
1.2134 +/**
1.2135 + If automatic resource management is enabled, calls the cleanup
1.2136 + function defined by the cleanup strategy with the managed resource
1.2137 + handle object and then disables the automatic resource management
1.2138 + for this object. The cleanup strategy is specified by the
1.2139 + CleanupStrategy template template parameter. The default cleanup
1.2140 + strategy is to call the cleanup member function on the contained
1.2141 + resource handle object. which is a member function named Close(),
1.2142 + unless explicitly defined otherwise for the class of the object,
1.2143 + for example by using the provided DEFINE_CLEANUP_FUNCTION macro.
1.2144 +*/
1.2145 + void ReleaseResource()
1.2146 + {
1.2147 + if (!IsEnabled())
1.2148 + return;
1.2149 +
1.2150 + CleanupStrategy::Cleanup(&Get());
1.2151 + LAutoHandleBase::Disable();
1.2152 + }
1.2153 +
1.2154 +/**
1.2155 + Disables the automatic resource management for this obkect and
1.2156 + returns a copy of the resource handle.
1.2157 +
1.2158 + @return A copy of the resource handle.
1.2159 +*/
1.2160 + using LAutoHandleBase::Unmanage;
1.2161 +
1.2162 +/**
1.2163 + Returns ETrue if automatic resource management is enabled; EFalse
1.2164 + otherwise.
1.2165 +
1.2166 + @return ETrue if automatic resource management is enabled; EFalse
1.2167 + otherwise.
1.2168 +*/
1.2169 + using LAutoHandleBase::IsEnabled;
1.2170 +
1.2171 +
1.2172 +/**
1.2173 + Returns a reference to the resource handle.
1.2174 +
1.2175 + @return A reference to the resource handle.
1.2176 +*/
1.2177 + using LAutoHandleBase::Get;
1.2178 +
1.2179 +
1.2180 +/**
1.2181 + Overloaded indirection operator function.
1.2182 +
1.2183 + @return A reference to the resource handle.
1.2184 +*/
1.2185 + using LAutoHandleBase::operator*;
1.2186 +
1.2187 +/**
1.2188 + Overloaded class member access operator function.
1.2189 +
1.2190 + @return A pointer to the resource handle.
1.2191 +*/
1.2192 + using LAutoHandleBase::operator->;
1.2193 +
1.2194 + static void Cleanup(TAny* aPtr)
1.2195 + {
1.2196 + LCleanedupHandle* autoh = static_cast<LCleanedupHandle*>(aPtr);
1.2197 +
1.2198 + if (autoh->IsEnabled())
1.2199 + {
1.2200 + CleanupStrategy::Cleanup(&autoh->Get());
1.2201 + }
1.2202 + }
1.2203 +
1.2204 + using LAutoHandleBase::Disable;
1.2205 +
1.2206 + void Swap(LCleanedupHandle& aCleanedupHandle)
1.2207 + {
1.2208 + LAutoHandleBase::Swap(aCleanedupHandle);
1.2209 + }
1.2210 + };
1.2211 +
1.2212 +
1.2213 +/**
1.2214 + Implementation base class - not designed for public inheritance or
1.2215 + direct use.
1.2216 +
1.2217 + @internalComponent
1.2218 +*/
1.2219 +// Not for Client Use , Only to be used Internally.
1.2220 +template<typename T,
1.2221 + class CleanupStrategyType>
1.2222 +class LCleanedupPtrBase: protected LAutoPtrBase<typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType>
1.2223 + {
1.2224 + typedef LAutoPtrBase<typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType> LAutoPtrBase;
1.2225 +
1.2226 + protected:
1.2227 + typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::ManagedType ManagedType;
1.2228 + typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::BaseManagedType BaseManagedType;
1.2229 + typedef typename TPtrCleanupTraits<T, CleanupStrategyType>::CleanupStrategy CleanupStrategy;
1.2230 +
1.2231 + LCleanedupPtrBase()
1.2232 + {
1.2233 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2234 + }
1.2235 +
1.2236 + template<typename U>
1.2237 + explicit LCleanedupPtrBase(U* aPtr)
1.2238 + : LAutoPtrBase(aPtr)
1.2239 + {
1.2240 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2241 + }
1.2242 +
1.2243 + ~LCleanedupPtrBase()
1.2244 + {
1.2245 + ManagedPopCleanupStackItem(LAutoPtrBase::IsEnabled());
1.2246 + }
1.2247 +
1.2248 + template<typename U>
1.2249 + LCleanedupPtrBase& operator=(U* aPtr)
1.2250 + {
1.2251 + ReleaseResource();
1.2252 + LAutoPtrBase::operator=(aPtr);
1.2253 + return *this;
1.2254 + }
1.2255 +
1.2256 + void ReleaseResource()
1.2257 + {
1.2258 + if (!LAutoPtrBase::IsEnabled())
1.2259 + return;
1.2260 +
1.2261 + CleanupStrategy::Cleanup(static_cast<ManagedType*>(iPtr));
1.2262 + LAutoPtrBase::Disable();
1.2263 + }
1.2264 +
1.2265 + using LAutoPtrBase::Unmanage;
1.2266 +
1.2267 + using LAutoPtrBase::IsEnabled;
1.2268 +
1.2269 + using LAutoPtrBase::Get;
1.2270 +
1.2271 + using LAutoPtrBase::operator->;
1.2272 +
1.2273 + static void Cleanup(TAny* aPtr)
1.2274 + {
1.2275 + LCleanedupPtrBase* cleanupPtr = static_cast<LCleanedupPtrBase*>(aPtr);
1.2276 +
1.2277 + if (cleanupPtr->IsEnabled())
1.2278 + {
1.2279 + CleanupStrategy::Cleanup(static_cast<ManagedType*>(cleanupPtr->iPtr));
1.2280 + }
1.2281 + }
1.2282 +
1.2283 + using LAutoPtrBase::iPtr;
1.2284 +
1.2285 + void Swap(LCleanedupPtrBase& aCleanedupPtr)
1.2286 + {
1.2287 + LAutoPtrBase::Swap(aCleanedupPtr);
1.2288 + }
1.2289 + };
1.2290 +
1.2291 +
1.2292 +/**
1.2293 + A class template that provides CleanupStack-based local-scope
1.2294 + automatic management of pointers.
1.2295 +
1.2296 + @note This class can only be used to define locals, never
1.2297 + data members. See below for an explanation and links to management
1.2298 + classes suitable for use in different contexts. It should never be
1.2299 + used in the same function as code that uses the CleanupStack API
1.2300 + directly
1.2301 +
1.2302 + This class template can be used to protect a pointer to type T such
1.2303 + that the instance of T referred to is automatically cleaned up
1.2304 + when either of the following occur:
1.2305 +
1.2306 + - The referring local variable goes out of scope normally
1.2307 + - The referring local variable goes out of scope due to an
1.2308 + untrapped leave causing the scope to be exited non-locally
1.2309 +
1.2310 + By default, the cleanup action is to delete the managed pointer
1.2311 + using non-array delete. An alternative cleanup strategy may be
1.2312 + selected by specifying a cleanup strategy template class in the
1.2313 + optional second template parameter position. The most common
1.2314 + alternative cleanup strategies are predefined.
1.2315 +
1.2316 + The constructors of this class may leave.
1.2317 +
1.2318 + As a convenience, the methods of the managed pointer may be
1.2319 + accessed via "->" notation directly on the management object, while
1.2320 + "." notation is used to access the interface of the management
1.2321 + object itself. Using "*" to dereference the management object
1.2322 + yields a T&, and is often useful when passing the managed object as
1.2323 + an argument.
1.2324 +
1.2325 + Automatic cleanup may be disabled at any time by calling
1.2326 + Unmanage(), while cleanup may be forced at any time by calling
1.2327 + ReleaseResource().
1.2328 +
1.2329 + Example:
1.2330 + @code
1.2331 + // block scope example
1.2332 + {
1.2333 + LCleanedupPtr<CDynamic> autop(new(ELeave) CDynamic);
1.2334 + autop->DoSomethingL(); // leave-safe
1.2335 + if (autop->Finished())
1.2336 + return; // the pointer is deleted automatically when exiting from scope
1.2337 + autop->DoSomethingElseL(); // leave-safe
1.2338 + // the pointer is deleted automatically when exiting from scope
1.2339 + }
1.2340 + @endcode
1.2341 +
1.2342 + Behind the scenes, this class template is implemented in terms of
1.2343 + the thread-local CleanupStack, restricting its use to locals on the
1.2344 + stack. This use of the CleanupStack ensures a consistent cleanup
1.2345 + order between functions that call one another, even if they use
1.2346 + different cleanup idioms.
1.2347 +
1.2348 + This class template together with the cleanup strategy class
1.2349 + templates provide a template-based implementation of the Strategy
1.2350 + design pattern (See also: Policy-based design).
1.2351 +
1.2352 + @see TPointerDelete which implements the default deleting cleanup strategy
1.2353 + @see TPointerFree which implements the alternative User::Free() cleanup strategy
1.2354 + @see LManagedPtr which has the same interface, but does not use the cleanup
1.2355 + stack and is suitable for protecting the data members of classes
1.2356 +*/
1.2357 +template<typename T,
1.2358 + class CleanupStrategyType = TPtrCleanupStrategy>
1.2359 +class LCleanedupPtr: protected LCleanedupPtrBase<T, CleanupStrategyType>
1.2360 + {
1.2361 + typedef LCleanedupPtrBase<T, CleanupStrategyType> LCleanedupPtrBase;
1.2362 +
1.2363 + public:
1.2364 + typedef T ManagedType;
1.2365 + typedef CleanupStrategyType CleanupStrategy;
1.2366 +
1.2367 +
1.2368 +/**
1.2369 + Default constructor. Constructs an empty LCleanedupPtr object.
1.2370 +
1.2371 + @post Get() == NULL
1.2372 +*/
1.2373 + LCleanedupPtr()
1.2374 + {
1.2375 + }
1.2376 +
1.2377 +/**
1.2378 + Explicit constructor template. Constructs a LCleanedupPtr object
1.2379 + that manages the pointer aPtr of a type convertible to T* that can
1.2380 + be cleaned up using the cleanup strategy of the LCleanedupPtr
1.2381 + class. The default cleanup strategy is to delete the pointer to a
1.2382 + heap-allocated object by using non-array delete. Alternative
1.2383 + cleanup strategies can be specified by using the CleanupStrategy
1.2384 + template parameter of the LCleanedupPtr class template.
1.2385 +
1.2386 + @param aPtr A pointer of a type that is convertible to T* that can
1.2387 + be cleaned up using the cleanup strategy.
1.2388 +
1.2389 + @pre aPtr is of a type convertible to T* and can be cleaned up
1.2390 + using the cleanup strategy.
1.2391 +
1.2392 + @post Get() == aPtr
1.2393 +*/
1.2394 + explicit LCleanedupPtr(T* aPtr)
1.2395 + : LCleanedupPtrBase(aPtr)
1.2396 + {
1.2397 + }
1.2398 +
1.2399 +/**
1.2400 + Assigns a new pointer to be managed. The new pointer must be of a
1.2401 + type convertible to T* and it must be possible to use the cleanup
1.2402 + strategy of the LCleanedupPtr object for the cleanup of the new
1.2403 + managed pointer. If the LCleanedupPtr object already contains a
1.2404 + managed pointer, then the cleanup strategy is invoked with the
1.2405 + managed pointer before assigning the new managed pointer.
1.2406 +
1.2407 + @param aPtr A pointer of a type that is convertible to T* that can
1.2408 + be cleaned up using the cleanup strategy.
1.2409 +
1.2410 + @pre aPtr is a pointer of a type that is convertible to T* and can
1.2411 + be cleaned up using the cleanup strategy.
1.2412 +
1.2413 + @post Get() == aPtr
1.2414 + */
1.2415 + LCleanedupPtr& operator=(T* aPtr)
1.2416 + {
1.2417 + LCleanedupPtrBase::operator=(aPtr);
1.2418 + return *this;
1.2419 + }
1.2420 +
1.2421 +/**
1.2422 + Assigns a new pointer to be managed. The new pointer must be of a
1.2423 + type convertible to T* and it must be possible to use the cleanup
1.2424 + strategy of the LCleanedupPtr object for the cleanup of the new
1.2425 + managed pointer. If the LCleanedupPtr object already contains a
1.2426 + managed pointer, then the cleanup strategy is invoked with the
1.2427 + managed pointer before assigning the new managed pointer.
1.2428 +
1.2429 + @param aPtr A pointer of a type that is convertible to T* that can
1.2430 + be cleaned up using the cleanup strategy.
1.2431 +
1.2432 + @pre aPtr is a pointer of a type that is convertible to T* and can
1.2433 + be cleaned up using the cleanup strategy.
1.2434 +
1.2435 + @post Get() == aPtr
1.2436 + */
1.2437 + template<typename U>
1.2438 + LCleanedupPtr& operator=(U* aPtr)
1.2439 + {
1.2440 + LCleanedupPtrBase::operator=(aPtr);
1.2441 + return *this;
1.2442 + }
1.2443 +
1.2444 +
1.2445 +/**
1.2446 + If automatic resource management is enabled, the specified cleanup
1.2447 + strategy is invoked with the managed pointer and the automatic
1.2448 + resource management is then disabled. The underlying pointer is
1.2449 + reset to NULL.
1.2450 +
1.2451 + @post Get() == NULL
1.2452 +*/
1.2453 + using LCleanedupPtrBase::ReleaseResource;
1.2454 +
1.2455 +/**
1.2456 + Disables the automatic resource management for this object and
1.2457 + returns a pointer to the object of type T.
1.2458 +
1.2459 + @return A pointer to the object of type T.
1.2460 +*/
1.2461 + T* Unmanage()
1.2462 + {
1.2463 + return static_cast<T*>(LCleanedupPtrBase::Unmanage());
1.2464 + }
1.2465 +
1.2466 +/**
1.2467 + Returns ETrue if automatic resource management is enabled; EFalse
1.2468 + otherwise.
1.2469 +
1.2470 + @return ETrue if automatic resource management is enabled; EFalse
1.2471 + otherwise.
1.2472 +*/
1.2473 + using LCleanedupPtrBase::IsEnabled;
1.2474 +
1.2475 +/**
1.2476 + Returns a pointer to the managed object of type T.
1.2477 +
1.2478 + @return A pointer to the managed object of type T.
1.2479 +*/
1.2480 + T* Get() const
1.2481 + {
1.2482 + return static_cast<T*>(iPtr);
1.2483 + }
1.2484 +
1.2485 +/**
1.2486 + Overloaded indirection operator function.
1.2487 +
1.2488 + @return A reference to the managed object of type T.
1.2489 +*/
1.2490 + T& operator*() const
1.2491 + {
1.2492 + return *(static_cast<T*>(iPtr));
1.2493 + }
1.2494 +
1.2495 +/**
1.2496 + Overloaded class member access operator function.
1.2497 +
1.2498 + @return A pointer to the managed object of type T.
1.2499 +*/
1.2500 + T* operator->() const
1.2501 + {
1.2502 + return static_cast<T*>(iPtr);
1.2503 + }
1.2504 +
1.2505 +// Implementation type - do not use
1.2506 + typedef typename LCleanedupPtrBase::BaseManagedType* LCleanedupPtr<T, CleanupStrategy>::*TUnspecifiedBoolType;
1.2507 +
1.2508 +/**
1.2509 + Conversion operator that enables LCleanedupPtr objects to be used
1.2510 + in boolean contexts.
1.2511 +
1.2512 + @return An unspecified value of an unspecified type convertible to
1.2513 + boolean, which has a boolean value equal to Get() != NULL
1.2514 + */
1.2515 + operator TUnspecifiedBoolType()
1.2516 + {
1.2517 + return iPtr ? &LCleanedupPtr::iPtr : NULL;
1.2518 + }
1.2519 +
1.2520 + using LCleanedupPtrBase::Disable;
1.2521 +
1.2522 + void Swap(LCleanedupPtr& aCleanedupPtr)
1.2523 + {
1.2524 + LCleanedupPtrBase::Swap(aCleanedupPtr);
1.2525 + }
1.2526 +
1.2527 + private:
1.2528 + using LCleanedupPtrBase::iPtr;
1.2529 + };
1.2530 +
1.2531 +
1.2532 +// function template used for comparing two LCleanedupPtr-managed
1.2533 +// pointers for equality
1.2534 +template<typename T, typename U>
1.2535 +TBool operator==(const LCleanedupPtr<T>& aPtr1, const LCleanedupPtr<U>& aPtr2)
1.2536 + {
1.2537 + return aPtr1.Get() == aPtr2.Get();
1.2538 + }
1.2539 +
1.2540 +// function template used for comparing two LCleanedupPtr-managed
1.2541 +// pointers for inequality
1.2542 +template<typename T, typename U>
1.2543 +TBool operator!=(const LCleanedupPtr<T>& aPtr1, const LCleanedupPtr<U>& aPtr2)
1.2544 + {
1.2545 + return aPtr1.Get() != aPtr2.Get();
1.2546 + }
1.2547 +
1.2548 +// function template used for testing the ordering of two
1.2549 +// LCleanedupPtr-managed pointers
1.2550 +template<typename T, typename U>
1.2551 +TBool operator<(const LCleanedupPtr<T>& aPtr1, const LCleanedupPtr<U>& aPtr2)
1.2552 + {
1.2553 + return aPtr1.Get() < aPtr2.Get();
1.2554 + }
1.2555 +
1.2556 +
1.2557 +/**
1.2558 + A class template that provides CleanupStack-based local-scope
1.2559 + automatic management of arrays.
1.2560 +
1.2561 + @note This class can only be used to define locals, never
1.2562 + data members. See below for an explanation and links to management
1.2563 + classes suitable for use in different contexts. It should never be
1.2564 + used in the same function as code that uses the CleanupStack API
1.2565 + directly
1.2566 +
1.2567 + @par
1.2568 +
1.2569 + @note This class can only be used with raw arrays, which are used
1.2570 + only rarely on Symbian OS. Instances of Symbian array container
1.2571 + classes (e.g. RArray, RPointerArray) should be managed using the
1.2572 + automatic management template classes appropriate for the array's
1.2573 + type (LCleanedupHandle template classes for Symbian R arrays or
1.2574 + LCleanedupPtr template classes for Symbian C arrays).
1.2575 +
1.2576 + This class template can be used to protect a heap-allocated array
1.2577 + of objects of type T such that the array of T referred to is
1.2578 + automatically cleaned up when either of the following occur:
1.2579 +
1.2580 + - The referring local variable goes out of scope normally
1.2581 + - The referring local variable goes out of scope due to an
1.2582 + untrapped leave causing the scope to be exited non-locally
1.2583 +
1.2584 + The default cleanup strategy is to deallocate the managed array
1.2585 + using arrray delete (delete[]), assuming that the array is
1.2586 + heap-allocated. An alternative cleanup strategy can be selected by
1.2587 + specifying a cleanup strategy template class as the optional second
1.2588 + template argument (corresponding to the CleanupStrategy template
1.2589 + parameter).
1.2590 +
1.2591 + The constructors of this class may leave.
1.2592 +
1.2593 + As a convenience, the elements of the managed array may be accessed
1.2594 + via "[]" notation directly on the management object.
1.2595 +
1.2596 + Automatic cleanup may be disabled at any time by calling
1.2597 + Unmanage(), while cleanup may be forced at any time by calling
1.2598 + ReleaseResource().
1.2599 +
1.2600 + @code
1.2601 + // block scope example
1.2602 + {
1.2603 + LCleanedupArray<TValue> arrayp(new(ELeave) TValue[KArraySize]);
1.2604 + arrayp[0].DoSomethingL(); // leave-safe
1.2605 + if (arrayp[0].Finished())
1.2606 + return; // the array is deleted automatically when exiting from scope
1.2607 + arrayp[1].DoSomethingElseL(); // leave-safe
1.2608 + // the array is deleted automatically when exiting from scope
1.2609 + }
1.2610 + @endcode
1.2611 +
1.2612 + Behind the scenes, this class template is implemented in terms of
1.2613 + the thread-local CleanupStack, restricting its use to locals on the
1.2614 + stack. This use of the CleanupStack ensures a consistent cleanup
1.2615 + order between functions that call one another, even if they use
1.2616 + different cleanup idioms.
1.2617 +
1.2618 + This class template together with the cleanup strategy class
1.2619 + templates provide a template-based implementation of the Strategy
1.2620 + design pattern (See also: Policy-based design).
1.2621 +
1.2622 + @see LManagedArray which has the same interface, but does not use
1.2623 + the cleanup stack and is suitable for protecting the data members
1.2624 + of classes
1.2625 +*/
1.2626 +template<typename T,
1.2627 + class CleanupStrategyType = TArrayDelete>
1.2628 +class LCleanedupArray: protected LAutoPtrBase<T>
1.2629 + {
1.2630 + typedef LAutoPtrBase<T> LAutoPtrBase;
1.2631 +
1.2632 + public:
1.2633 + typedef T ManagedType;
1.2634 + typedef CleanupStrategyType CleanupStrategy;
1.2635 +
1.2636 +/**
1.2637 + Default constructor. Constructs an empty LCleanedupArray object.
1.2638 +
1.2639 + @post Get() == NULL
1.2640 + */
1.2641 + LCleanedupArray()
1.2642 + {
1.2643 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2644 + }
1.2645 +
1.2646 +/**
1.2647 + Explicit constructor. Constructs a LCleanedupArray object that
1.2648 + manages an array of objects of type T that can be cleaned up using
1.2649 + the cleanup strategy of the LCleanedupArray class. The default
1.2650 + cleanup strategy is to deallocate the heap-allocated array by using
1.2651 + array delete. An alternative cleanup strategy can be selected by
1.2652 + specifying a cleanup strategy template class as the optional second
1.2653 + template argument (corresponding to the CleanupStrategy template
1.2654 + parameter).
1.2655 +
1.2656 + @param aPtr A pointer to the first element of an array of objects
1.2657 + of type T, array that can be cleaned up using the cleanup strategy
1.2658 + of the the LCleanedupArray class.
1.2659 +
1.2660 + @pre The array can be cleaned up using the cleanup strategy.
1.2661 +
1.2662 + @post Get() == aPtr
1.2663 + */
1.2664 + explicit LCleanedupArray(T* aPtr)
1.2665 + : LAutoPtrBase(aPtr)
1.2666 + {
1.2667 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2668 + }
1.2669 +
1.2670 +
1.2671 +/**
1.2672 + Destructor. When automatic resource management is enabled, the
1.2673 + destructor invokes the specified cleanup strategy for the managed
1.2674 + pointer.
1.2675 + */
1.2676 + ~LCleanedupArray()
1.2677 + {
1.2678 + ManagedPopCleanupStackItem(LAutoPtrBase::IsEnabled());
1.2679 + }
1.2680 +
1.2681 +/**
1.2682 + Assigns a new array of objects of type T to be managed. It needs
1.2683 + to be be possible to use the cleanup strategy of the
1.2684 + LCleanedupArray object for the cleanup of the new managed array.
1.2685 + The default cleanup strategy is to delete the heap-allocated array
1.2686 + by using array delete (delete[]). If the LCleanedupArray object
1.2687 + already manages an array, then the cleanup strategy is invoked with
1.2688 + the managed array before assigning the new managed array.
1.2689 +
1.2690 + @param aPtr A pointer to the first element of the array of objects
1.2691 + of type T - array that can be cleaned up using the cleanup
1.2692 + strategy.
1.2693 +
1.2694 + @pre The new array to be managed can be cleaned up using the
1.2695 + cleanup strategy.
1.2696 +
1.2697 + @post Get() == aPtr
1.2698 + */
1.2699 + LCleanedupArray& operator=(T* aPtr)
1.2700 + {
1.2701 + ReleaseResource();
1.2702 + LAutoPtrBase::operator=(aPtr);
1.2703 + return *this;
1.2704 + }
1.2705 +
1.2706 +/**
1.2707 + If automatic resource management is enabled, the specified cleanup
1.2708 + strategy is invoked for the managed pointer and the automatic
1.2709 + resource management is then disabled. The underlying pointer is
1.2710 + reset to NULL.
1.2711 +
1.2712 + @post Get() == NULL
1.2713 +*/
1.2714 + void ReleaseResource()
1.2715 + {
1.2716 + if (!LAutoPtrBase::IsEnabled())
1.2717 + return;
1.2718 +
1.2719 + CleanupStrategy::Cleanup(iPtr);
1.2720 + iPtr = NULL;
1.2721 + }
1.2722 +
1.2723 +
1.2724 +/**
1.2725 + Disables the automatic resource management for this object and
1.2726 + returns a pointer to the first element of the array of objects of
1.2727 + type T.
1.2728 +
1.2729 + @return A pointer to the first element of the array of objects of
1.2730 + type T.
1.2731 +*/
1.2732 + using LAutoPtrBase::Unmanage;
1.2733 +
1.2734 +/**
1.2735 + Returns ETrue if automatic resource management is enabled; EFalse
1.2736 + otherwise.
1.2737 +
1.2738 + @return ETrue if automatic resource management is enabled; EFalse
1.2739 + otherwise.
1.2740 +*/
1.2741 + using LAutoPtrBase::IsEnabled;
1.2742 +
1.2743 +/**
1.2744 + Returns a pointer to the first element of the managed array of
1.2745 + objects of type T.
1.2746 +
1.2747 + @return A pointer to the first element of the managed array of
1.2748 + objects of type T.
1.2749 +*/
1.2750 + using LAutoPtrBase::Get;
1.2751 +
1.2752 +/**
1.2753 + Overloaded subscript operator.
1.2754 +
1.2755 + @return A reference to the object of type T at the position aIndex.
1.2756 + */
1.2757 + T& operator[](TInt aIndex) const
1.2758 + {
1.2759 + return iPtr[aIndex];
1.2760 + }
1.2761 +
1.2762 + static void Cleanup(TAny* aPtr)
1.2763 + {
1.2764 + LCleanedupArray* cleanupPtr = static_cast<LCleanedupArray*>(aPtr);
1.2765 +
1.2766 + if (cleanupPtr->IsEnabled())
1.2767 + {
1.2768 + CleanupStrategy::Cleanup(cleanupPtr->iPtr);
1.2769 + }
1.2770 + }
1.2771 +
1.2772 + using LAutoPtrBase::Disable;
1.2773 +
1.2774 + void Swap(LCleanedupArray& aArray)
1.2775 + {
1.2776 + LAutoPtrBase::Swap(aArray);
1.2777 + }
1.2778 +
1.2779 + private:
1.2780 + using LAutoPtrBase::iPtr;
1.2781 + };
1.2782 +
1.2783 +
1.2784 +/**
1.2785 + A class template that provides CleanupStack-based local-scope
1.2786 + automatic management of references to resource handles (often
1.2787 + instances of R-classes).
1.2788 +
1.2789 + @note This class can only be used to define locals, never
1.2790 + data members. See below for an explanation and links to management
1.2791 + classes suitable for use in different contexts. It should never be
1.2792 + used in the same function as code that uses the CleanupStack API
1.2793 + directly.
1.2794 +
1.2795 + Unlike LCleanedupHandle which creates a fresh instance of its
1.2796 + managed type, this class template can be used to reference and
1.2797 + protect an existing resource handle of type T (typically an
1.2798 + R-class). The instance of T referred to has a cleanup operation run
1.2799 + on it automatically when either of the following occur:
1.2800 +
1.2801 + - The referring local variable goes out of scope normally
1.2802 + - The referring local variable goes out of scope due to an
1.2803 + untrapped leave causing the scope to be exited non-locally
1.2804 +
1.2805 + By default, the cleanup action is to call the Close() member
1.2806 + function of the referenced handle. An alternative cleanup strategy
1.2807 + may be selected by specifying a cleanup strategy template class in
1.2808 + the optional second template parameter position. The most common
1.2809 + alternative cleanup strategies are predefined. It is also possible
1.2810 + to specialize the default cleanup action for a given class using
1.2811 + the DEFINE_CLEANUP_FUNCTION macro.
1.2812 +
1.2813 + The constructors of this class may leave.
1.2814 +
1.2815 + As a convenience, the methods of the managed handle may be
1.2816 + accessed via "->" notation directly on the management object, while
1.2817 + "." notation is used to access the interface of the management
1.2818 + object itself. Using "*" to dereference the management object
1.2819 + yields a T&, and is often useful when passing the managed object as
1.2820 + an argument.
1.2821 +
1.2822 + Automatic cleanup may be disabled at any time by calling
1.2823 + Unmanage(), while cleanup may be forced at any time by calling
1.2824 + ReleaseResource().
1.2825 +
1.2826 + Example:
1.2827 + @code
1.2828 + // block scope example
1.2829 + void DoWithClosable(RClosable& aObj)
1.2830 + {
1.2831 + LCleanedupRef<RClosable> obj(aObj);
1.2832 + obj->DoSomethingL(); // leave-safe
1.2833 + if (obj->Finished())
1.2834 + return; // RClosable::Close is invoked automatically
1.2835 + obj->DoSomethingElseL(); // leave-safe
1.2836 + // RClosable::Close is invoked automatically
1.2837 + }
1.2838 + @endcode
1.2839 +
1.2840 + Behind the scenes, this class template is implemented in terms of
1.2841 + the thread-local CleanupStack, restricting its use to locals on the
1.2842 + stack. This use of the CleanupStack ensures a consistent cleanup
1.2843 + order between functions that call one another, even if they use
1.2844 + different cleanup idioms.
1.2845 +
1.2846 + This class template together with the cleanup strategy class
1.2847 + templates provide a template-based implementation of the Strategy
1.2848 + design pattern (See also: Policy-based design).
1.2849 +
1.2850 + @see TClose which implements the default Close() calling cleanup strategy
1.2851 + @see TResetAndDestroy which implements an alternative
1.2852 + ResetAndDestroy() calling cleanup strategy
1.2853 + @see TFree which implements an alternative Free() calling cleanup
1.2854 + strategy
1.2855 + @see TDestroy which implements an alternative Destroy() calling
1.2856 + cleanup strategy
1.2857 + @see TRelease which implements an alternative Release() calling
1.2858 + cleanup strategy
1.2859 + @see LManagedRef which has the same interface, but does not use
1.2860 + the cleanup stack and is suitable for protecting the data members of
1.2861 + classes
1.2862 + @see LCleanedupHandle which has a similar interface but creates a
1.2863 + fresh local instance of T
1.2864 +*/
1.2865 +template<typename T,
1.2866 + class CleanupStrategyType = TResourceCleanupStrategy>
1.2867 +class LCleanedupRef: protected LAutoRefBase<T>
1.2868 + {
1.2869 + typedef LAutoRefBase<T> LAutoRefBase;
1.2870 +
1.2871 + public:
1.2872 + typedef T ManagedType;
1.2873 + typedef CleanupStrategyType CleanupStrategy;
1.2874 +
1.2875 +/**
1.2876 + Explicit constructor.
1.2877 + */
1.2878 + template<typename U>
1.2879 + explicit LCleanedupRef(U& aRef)
1.2880 + : LAutoRefBase(aRef)
1.2881 + {
1.2882 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.2883 + }
1.2884 +
1.2885 +/**
1.2886 + Destructor. When automatic resource management is enabled, the
1.2887 + destructor invokes the specified cleanup strategy for the managed
1.2888 + reference.
1.2889 + */
1.2890 + ~LCleanedupRef()
1.2891 + {
1.2892 + ManagedPopCleanupStackItem(LAutoRefBase::IsEnabled());
1.2893 + }
1.2894 +
1.2895 +/**
1.2896 + Assigns a new reference to be managed. If the LCleanedupRef
1.2897 + object already contains a managed reference, then the specified
1.2898 + cleanup strategy is invoked for the managed reference before
1.2899 + assigning the new managed reference.
1.2900 + */
1.2901 + template<typename U>
1.2902 + LCleanedupRef& operator=(U& aRef)
1.2903 + {
1.2904 + ReleaseResource();
1.2905 + LAutoRefBase::operator=(aRef);
1.2906 + return *this;
1.2907 + }
1.2908 +
1.2909 +/**
1.2910 + If automatic resource management is enabled, the specified cleanup
1.2911 + strategy is invoked for the managed reference and the automatic
1.2912 + resource management is then disabled.
1.2913 +*/
1.2914 + void ReleaseResource()
1.2915 + {
1.2916 + if (!LAutoRefBase::IsEnabled())
1.2917 + return;
1.2918 +
1.2919 + CleanupStrategy::Cleanup(iPtr);
1.2920 + iPtr = NULL;
1.2921 + }
1.2922 +
1.2923 +/**
1.2924 + Disables the automatic resource management for this object and
1.2925 + returns a reference to the object of type T.
1.2926 +
1.2927 + @return A reference to the object of type T.
1.2928 +*/
1.2929 + using LAutoRefBase::Unmanage;
1.2930 +
1.2931 +/**
1.2932 + Returns ETrue if automatic resource management is enabled; EFalse
1.2933 + otherwise.
1.2934 +
1.2935 + @return ETrue if automatic resource management is enabled; EFalse
1.2936 + otherwise.
1.2937 +*/
1.2938 + using LAutoRefBase::IsEnabled;
1.2939 +
1.2940 +/**
1.2941 + Returns a reference to the managed object of type T.
1.2942 +
1.2943 + @return A reference to the managed object of type T.
1.2944 +*/
1.2945 + using LAutoRefBase::Get;
1.2946 +
1.2947 +/**
1.2948 + Overloaded indirection operator function.
1.2949 +
1.2950 + @return A reference to the managed object of type T.
1.2951 +*/
1.2952 + using LAutoRefBase::operator*;
1.2953 +
1.2954 +/**
1.2955 + Overloaded class member access operator function.
1.2956 +
1.2957 + @return A pointer to the managed object of type T.
1.2958 +*/
1.2959 + using LAutoRefBase::operator->;
1.2960 +
1.2961 +
1.2962 + static void Cleanup(TAny* aPtr)
1.2963 + {
1.2964 + LCleanedupRef* cleanupRef = static_cast<LCleanedupRef*>(aPtr);
1.2965 +
1.2966 + if (cleanupRef->IsEnabled())
1.2967 + {
1.2968 + CleanupStrategy::Cleanup(cleanupRef->iPtr);
1.2969 + }
1.2970 + }
1.2971 +
1.2972 + using LAutoRefBase::Disable;
1.2973 +
1.2974 + void Swap(LCleanedupRef& aRef)
1.2975 + {
1.2976 + LAutoRefBase::Swap(aRef);
1.2977 + }
1.2978 +
1.2979 + private:
1.2980 + using LAutoRefBase::iPtr;
1.2981 + };
1.2982 +
1.2983 +
1.2984 +/**
1.2985 + A class that provides automatic cleanup using a TCleanupOperation
1.2986 + on the destruction of the LManagedGuard object.
1.2987 +
1.2988 + @note This class can only be used to define object scoped cleanup
1.2989 + to guard object destruction, never local stack scoped cleanup. See
1.2990 + below for an explanation and links to management classes suitable
1.2991 + for use in different contexts.
1.2992 +
1.2993 + This class can be used to manage a TCleanupOperation in such a way
1.2994 + that the specified cleanup operation is guaranteed to be called
1.2995 + when the guarding object is destroyed; typically when the object
1.2996 + containing it is deleted.
1.2997 +
1.2998 + The constructors of this class never leave, so data members defined with
1.2999 + this type may be initialized safely during any phase of
1.3000 + construction of the owning class.
1.3001 +
1.3002 + Automatic cleanup may be disabled at any time by calling
1.3003 + Dismiss(), while cleanup may be forced at any time by calling
1.3004 + Execute().
1.3005 +
1.3006 + @code
1.3007 + class CComposite : public CBase
1.3008 + {
1.3009 + public:
1.3010 + CONSTRUCTORS_MAY_LEAVE
1.3011 +
1.3012 + CComposite(RCleanable* aObj)
1.3013 + : iObj(RCleanable::Cleanup, aObj)
1.3014 + {
1.3015 + }
1.3016 +
1.3017 + ~CComposite()
1.3018 + {
1.3019 + // RCleanable::Cleanup(iObj) is automatically invoked
1.3020 + }
1.3021 +
1.3022 + private:
1.3023 + LManagedGuard<RCleanable> iObj;
1.3024 + };
1.3025 + @endcode
1.3026 +
1.3027 + Behind the scenes, this class template simply relies on reliable
1.3028 + execution of its destructor. If used for a local variable rather
1.3029 + than a data member, cleanup will occur but out-of-order compared to
1.3030 + objects protected using the LCleanupXxx variants or the
1.3031 + CleanupStack directly. Therefore it is not recommended for use in
1.3032 + that context.
1.3033 +
1.3034 + These management classes may be used as the basis for implementing
1.3035 + leave-safe single-phase construction, since fully initialized
1.3036 + data members protected in this way will get destroyed (so reliably
1.3037 + triggering cleanup) if their containing classes leave during
1.3038 + execution of their constructors. Note, however, that single-phase
1.3039 + construction must be explicitly enabled in the containing class
1.3040 + using the CONSTRUCTORS_MAY_LEAVE macro.
1.3041 +
1.3042 + @see LCleanedupGuard which has the same interface, but uses the cleanup
1.3043 + stack and is suitable for use as a local to guard local scope exit
1.3044 + @see CONSTRUCTORS_MAY_LEAVE
1.3045 +*/
1.3046 +class LManagedGuard
1.3047 + {
1.3048 + public:
1.3049 +/**
1.3050 + Constructor. Creates a LCleanedupGuard object that, when enabled,
1.3051 + automatically invokes upon destruction a cleanup operation
1.3052 + specified by the aCleanupOperation parameter with the pointer to
1.3053 + data specified by the aData parameter.
1.3054 +
1.3055 + @param aCleanupOperation A cleanup operation.
1.3056 + @param aData Pointer to data to be passed to the cleanup operation
1.3057 + */
1.3058 + LManagedGuard(TCleanupOperation aCleanupOperation, TAny* aData = 0)
1.3059 + : iCleanupOperation(aCleanupOperation),
1.3060 + iData(aData)
1.3061 + {
1.3062 + }
1.3063 +
1.3064 +/**
1.3065 + Destructor.
1.3066 + */
1.3067 + ~LManagedGuard()
1.3068 + {
1.3069 + Execute();
1.3070 + }
1.3071 +
1.3072 +/**
1.3073 + Executes the guard cleanup operation.
1.3074 +*/
1.3075 + void Execute()
1.3076 + {
1.3077 + if (iCleanupOperation)
1.3078 + {
1.3079 + iCleanupOperation(iData);
1.3080 + }
1.3081 + }
1.3082 +
1.3083 +/**
1.3084 + Disables the guard.
1.3085 +*/
1.3086 + void Dismiss()
1.3087 + {
1.3088 + iCleanupOperation = NULL;
1.3089 + }
1.3090 +
1.3091 + private:
1.3092 + LManagedGuard(const LManagedGuard&);
1.3093 + LManagedGuard& operator=(const LManagedGuard&);
1.3094 +
1.3095 + TCleanupOperation iCleanupOperation;
1.3096 + TAny* iData;
1.3097 + };
1.3098 +
1.3099 +
1.3100 +/**
1.3101 + A class that provides CleanupStack-based local-scope automatic
1.3102 + cleanup using a TCleanupOperation on the destruction of the
1.3103 + LManagedGuard object.
1.3104 +
1.3105 + @note This class can only be used to define a local stack scoped
1.3106 + cleanup, never an object scoped cleanup to guard object
1.3107 + destruction. See below for an explanation and links to management
1.3108 + classes suitable for use in different contexts.
1.3109 +
1.3110 + This class can be used to manage a TCleanupOperation in such a way
1.3111 + that the specified cleanup operation is guaranteed to be called
1.3112 + when either of the following occur:
1.3113 +
1.3114 + - The guarding local variable goes out of scope normally
1.3115 + - The guarding local variable goes out of scope due to an
1.3116 + untrapped leave causing the scope to be exited non-locally
1.3117 +
1.3118 + The constructors of this class may leave.
1.3119 +
1.3120 + Automatic cleanup may be disabled at any time by calling
1.3121 + Dismiss(), while cleanup may be forced at any time by calling
1.3122 + Execute().
1.3123 +
1.3124 + @code
1.3125 + // block scope example
1.3126 + {
1.3127 + RCleanable obj;
1.3128 + LCleanedupGuard cleanGuard(RCleanable::Cleanup, &obj);
1.3129 +
1.3130 + obj.DoSomethingL(); // leave-safe
1.3131 + if (Finished())
1.3132 + return; // RCleanable::Cleanup is invoked automatically when exiting from scope
1.3133 + obj.DoSomethingElseL(); // leave-safe
1.3134 + // RCleanable::Cleanup is invoked automatically when exiting from scope
1.3135 + }
1.3136 + @endcode
1.3137 +
1.3138 + Behind the scenes, this class template is implemented in terms of
1.3139 + the thread-local CleanupStack, restricting its use to local stack
1.3140 + scope. This use of the CleanupStack ensures a consistent cleanup
1.3141 + order between functions that call one another, even if they use
1.3142 + different cleanup idioms.
1.3143 +
1.3144 + @see LManagedGuard which has the same interface, but does not use the cleanup
1.3145 + stack and is suitable for use as the data member of a class to guard
1.3146 + object destruction.
1.3147 +*/
1.3148 +class LCleanedupGuard
1.3149 + {
1.3150 + public:
1.3151 +/**
1.3152 + Constructor. Creates a LCleanedupGuard object that, when enabled,
1.3153 + automatically invokes upon destruction a cleanup operation
1.3154 + specified by the aCleanupOperation parameter with the pointer to
1.3155 + data specified by the aData parameter.
1.3156 +
1.3157 + @param aCleanupOperation A cleanup operation.
1.3158 + @param aData Pointer to data to be passed to the cleanup operation
1.3159 + */
1.3160 + LCleanedupGuard(TCleanupOperation aCleanupOperation, TAny* aData = 0)
1.3161 + : iCleanupOperation(aCleanupOperation),
1.3162 + iData(aData)
1.3163 + {
1.3164 + CleanupStack::PushL(TCleanupItem(Cleanup, this));
1.3165 + }
1.3166 +
1.3167 +/**
1.3168 + Destructor.
1.3169 + */
1.3170 + ~LCleanedupGuard()
1.3171 + {
1.3172 + ManagedPopCleanupStackItem(iCleanupOperation);
1.3173 + }
1.3174 +
1.3175 +/**
1.3176 + Executes the guard cleanup operation.
1.3177 +*/
1.3178 + void Execute()
1.3179 + {
1.3180 + if (iCleanupOperation)
1.3181 + {
1.3182 + iCleanupOperation(iData);
1.3183 + }
1.3184 + }
1.3185 +
1.3186 +/**
1.3187 + Disables the guard.
1.3188 +*/
1.3189 + void Dismiss()
1.3190 + {
1.3191 + iCleanupOperation = NULL;
1.3192 + }
1.3193 +
1.3194 + static void Cleanup(TAny* aPtr)
1.3195 + {
1.3196 + LCleanedupGuard* guard = static_cast<LCleanedupGuard*>(aPtr);
1.3197 + guard->Execute();
1.3198 + }
1.3199 +
1.3200 + private:
1.3201 + LCleanedupGuard(const LCleanedupGuard&);
1.3202 + LCleanedupGuard& operator=(const LCleanedupGuard&);
1.3203 +
1.3204 +
1.3205 + TCleanupOperation iCleanupOperation;
1.3206 + TAny* iData;
1.3207 + };
1.3208 +
1.3209 +#endif // !EMANAGED_H
1.3210 +