LockableHandleCache<T> Class

Manages object handles in Excel and allows explicit extension of handle lifetimes.

class psl::LockableHandleCache<T>

Overview

The LockableHandleCache<T> class is a specialized handle cache which can be used in place of HandleCache<T>. Like HandleCache<T>, it actively manages the lifetime of the cached objects, but it also allows the developer to lock handles into memory, so that they are only deleted when they are explicitly unlocked by code.

This form of cache allows developers to create and control object handles from VBA code (or other automation code).

Use pattern

1. To use this cache, the developer should instantiate it explicitly in global scope. Otherwise a cache of the base type HandleCache<T> will be created at run-time.

   CopyC++

   LockableHandleCache<Thing> theLockableThingCache;

2. In order to allow automation code to lock a handle, create an XLL add-in function that takes a string handle as its only argument. In this function, create a lock token using the cache's LockHandle method, and return the token as the result of the function.

   CopyC++

   CXlOper* LockThingHandle_Impl(CXlOper& xloResult, const CXlStringArg& t_op)
   {
       // Input buffers 
       const Thing* t;
       // Validate and translate inputs
       XlReadScalarEx(t_op, t, psl::HandleConverter<Thing >(), CScalarConvertParams
           <const Thing*>(L"t", 0, 0, -1).SetStringParam(0, L"Thing"));
       // End of generated code 
   //}}XLP_SRC
   
       xloResult = theLockableThingCache.LockHandle(t_op);
       return xloResult.Ret();
   }

3. When calling add-in functions that expect an RTD handle from automation, pass the token in place of the handle.

4. Author another XLL add-in function that uses the cache's UnlockHandle method.

   CopyC++

   CXlOper* UnlockThingHandle_Impl(CXlOper& xloResult, const CXlStringArg& token)
   {
       // End of generated code 
   //}}XLP_SRC
       theLockableThingCache.UnlockHandle(token);
       return xloResult.Ret();
   }

   When the lock is no longer required, call this add-in function from the automation code, passing the token.

   The object referred to by the handle is available for destruction when the last token is unlocked, and Excel has stopped using the handle.

See the LockableHandles sample project for an example of the class in use.

Requirements

Header: rtdhandleslock.h
Namespace: psl

See Also

LockableHandleCache<T> Methods | rtdhandleslock.h | LockableHandles Sample