LManagedRef Class Reference

#include <emanaged.h>

class LManagedRef : protected LAutoRefBase

Inherits from

Detailed Description

A class template that provides automatic management of references to resource handles (often R-class instances) held in the data members of objects.

Note:

This class should not used to define locals. See below for an explanation and links to management classes suitable for use in that context.

Unlike LManagedHandle which creates a fresh instance of its managed type, this class template can be used to protect an existing resource handle of type T (typically an R-class instance). The instance of T referred to has a cleanup operation run on it automatically when the management object is destroyed; typically when the object containing it is deleted.

By default, the cleanup action is to call the Close() member function of the referenced handle. An alternative cleanup strategy may be selected by specifying a cleanup strategy template class in the optional second template parameter position. The most common alternative cleanup strategies are predefined. It is also possible to specialize the default cleanup action for a given class using the DEFINE_CLEANUP_FUNCTION macro.

The constructors of this class never leave, so data members defined with this type may be initialized safely during any phase of construction of the owning class.

As a convenience, the methods of the managed pointer may be accessed via "->" notation directly on the management object, while "." notation is used to access the interface of the management object itself. Using "*" to dereference the management object yields a T&, and is often useful when passing the managed object as an argument.

Automatic cleanup may be disabled at any time by calling Unmanage(), while cleanup may be forced at any time by calling ReleaseResource().

Example:
   class CComposite : public CBase
	   {
	 public:
	   CONSTRUCTORS_MAY_LEAVE

	   // An existing RFs instance is given to us to reuse, but
	   // we are responsible for calling Close() when we're done
	   CComposite(RFs& aFs)
		   : iFileServ(aFs)
		   {
		   iFileServ->Connect() OR_LEAVE;
		   iFile->Open(*iFileServ, ...);
		   }

	   ~CComposite()
		   {
		   // the handles are automatically closed
		   }

	 private:

	   LManagedRef<RFs> iFileServ;
	   LManagedHandle<RFile> iFile;
	   };

Behind the scenes, this class template simply relies on reliable execution of its destructor. If used for a local variable rather than a data member, cleanup will occur but out-of-order compared to objects protected using the LCleanupXxx variants or the CleanupStack directly. Therefore it is not recommended for use in that context.

These management classes may be used as the basis for implementing leave-safe single-phase construction, since fully initialized data members protected in this way will get destroyed (so reliably triggering cleanup) if their containing classes leave during execution of their constructors. Note, however, that single-phase construction must be explicitly enabled in the containing class using the CONSTRUCTORS_MAY_LEAVE macro.

This class template together with the cleanup strategy class templates provide a template-based implementation of the Strategy design pattern (See also: Policy-based design).

See also: TClose which implements the default Close() calling cleanup strategy TResetAndDestroy which implements an alternative ResetAndDestroy() calling cleanup strategy TFree which implements an alternative Free() calling cleanup strategy TDestroy which implements an alternative Destroy() calling cleanup strategy TRelease which implements an alternative Release() calling cleanup strategy LCleanedupRef which has the same interface, but uses the cleanup stack and is suitable for protecting locals LManagedHandle which has a similar interface but creates a fresh local instance of T CONSTRUCTORS_MAY_LEAVE

Member Type Definition Documentation

Typedef CleanupStrategy

typedef CleanupStrategyTypeCleanupStrategy

Typedef ManagedType

typedef TManagedType

Constructor & Destructor Documentation

LManagedRef ( U & )

LManagedRef(U &aRef)[inline, explicit]

Explicit constructor.

~LManagedRef ( )

~LManagedRef()[inline]

Destructor. When automatic resource management is enabled, the destructor invokes the specified cleanup strategy for the managed reference.

Member Function Documentation

ReleaseResource ( )

voidReleaseResource()[inline]

If automatic resource management is enabled, the specified cleanup strategy is invoked for the managed reference and the automatic resource management is then disabled for this object.

Swap ( LManagedRef & )

voidSwap(LManagedRef &aRef)[inline]

operator= ( U & )

LManagedRef &operator=(U &aRef)[inline]

Reimplemented from LAutoRefBase::operator=(U &)

Assigns a new reference to be managed. If the LManagedRef object already contains a managed reference, then the specified cleanup strategy is invoked for the managed reference before assigning the new managed reference.