LCleanedupRef Class Reference

#include <emanaged.h>

class LCleanedupRef : protected LAutoRefBase

Inherits from

Detailed Description

A class template that provides CleanupStack-based local-scope automatic management of references to resource handles (often instances of R-classes).

Note:

This class can only be used to define locals, never data members. See below for an explanation and links to management classes suitable for use in different contexts. It should never be used in the same function as code that uses the CleanupStack API directly.

Unlike LCleanedupHandle which creates a fresh instance of its managed type, this class template can be used to reference and protect an existing resource handle of type T (typically an R-class). The instance of T referred to has a cleanup operation run on it automatically when either of the following occur:
  • The referring local variable goes out of scope normally

  • The referring local variable goes out of scope due to an untrapped leave causing the scope to be exited non-locally

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 may leave.

As a convenience, the methods of the managed handle 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:
	// block scope example
	void DoWithClosable(RClosable& aObj)
	  {
	  LCleanedupRef<RClosable> obj(aObj);
	  obj->DoSomethingL(); // leave-safe
	  if (obj->Finished())
		return; // RClosable::Close is invoked automatically
	  obj->DoSomethingElseL(); // leave-safe
	  // RClosable::Close is invoked automatically
	  }

Behind the scenes, this class template is implemented in terms of the thread-local CleanupStack, restricting its use to locals on the stack. This use of the CleanupStack ensures a consistent cleanup order between functions that call one another, even if they use different cleanup idioms.

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 LManagedRef which has the same interface, but does not use the cleanup stack and is suitable for protecting the data members of classes LCleanedupHandle which has a similar interface but creates a fresh local instance of T

Member Type Definition Documentation

Typedef CleanupStrategy

typedef CleanupStrategyTypeCleanupStrategy

Typedef ManagedType

typedef TManagedType

Constructor & Destructor Documentation

LCleanedupRef ( U & )

LCleanedupRef(U &aRef)[inline, explicit]

Explicit constructor.

~LCleanedupRef ( )

~LCleanedupRef()[inline]

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

Member Function Documentation

Cleanup ( TAny * )

voidCleanup(TAny *aPtr)[static, inline]

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.

Swap ( LCleanedupRef & )

voidSwap(LCleanedupRef &aRef)[inline]

operator= ( U & )

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

Reimplemented from LAutoRefBase::operator=(U &)

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