home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / odtlktv4.zip / ODTLKT / TOOLKIT / BETA / SAMPLES / OPENDOC / PUBUTILS / TEMPOBJ.H < prev   
Text File  |  1995-11-29  |  5KB  |  193 lines
  1. /*
  2.   File:    TempObj.h
  3.  
  4.   Contains:  Template utilities for exception-safe temporary object references
  5.  
  6.   Theory Of Operation:
  7.  
  8.     *** See the Tech Note "Temporary References/Objects" for full documentation.
  9.  
  10.  
  11.     TempObj<T>    T :ODObject        A pointer to a temporary object
  12.     TempRef<T>    T :ODRefCntObject    A pointer to a temporary reference
  13.  
  14.     Specific instantiations:
  15.     TempRefs:
  16.       TempODPart
  17.       TempODFrame
  18.       TempODShape
  19.       TempODTransform
  20.       TempODStorageUnit
  21.     TempObjs:
  22.       TempODFrameFacetIterator
  23.       TempFocusSetIterator
  24.     (you can extend this set.)
  25.  
  26.     These are simple template classes that act as a transparent wrapper around
  27.     an OpenDoc object pointer. The temp object can be used wherever a pointer
  28.     to the object would be used. When the temp object goes out of scope, the
  29.     object it wraps will be deleted (in the case of TempObj) or released (in
  30.     the case of TempRef.) This includes the case where an exception is thrown:
  31.     the wrapper is exception-safe.
  32.  
  33.     Example:
  34.  
  35.       RgnHandle r;
  36.       {
  37.         TempODShape s = frame->GetUsedShape(ev,kODNULL);
  38.         r = s->GetQDRegion(ev);
  39.       }
  40.  
  41.     In this example, s is wrapped around the actual ODShape returned by
  42.     the GetUsedShape method. It is used just as an ODShape* in the next
  43.     line. In the normal course of events, the shape will be released after
  44.     GetQDRegion returns, since s goes out of scope. If GetUsedShape runs
  45.     out of memory and throws an exception, the shape will also be safely
  46.     released.
  47.  
  48.     There is a certain amount of overhead associated with the TempRef
  49.     object. However, the only safe alternative to using it would be to
  50.     wrap an exception handler around the call to GetUsedShape and release
  51.     the shape in the CATCH block (and then reraise the exception) as well
  52.     as after the ENDTRY. This ends up using significantly more code and
  53.     execution time than the TempRef object -- exception handlers are
  54.     quite expensive.
  55.  
  56.   In Progress:
  57.  
  58. */
  59.  
  60. #ifndef _TEMPOBJ_
  61. #define _TEMPOBJ_
  62.  
  63. #ifndef _EXCEPT_
  64. #include <Except.h>
  65. #endif
  66.  
  67. #ifndef INCL_ODDTS // include non-DTS C++ headers
  68.  
  69. #ifndef SOM_ODRefCntObject_xh
  70. #include "RefCtObj.xh"
  71. #endif
  72.  
  73. #else // include DTS C++ headers
  74.  
  75. #ifndef _DTS_HH_INCLUDED_RefCtObj
  76. #include <RefCtObj.hh>
  77. #endif
  78.  
  79. #endif // ! INCL_ODDTS
  80.  
  81. class TempPtr
  82. {
  83.   public:
  84.   TempPtr( );
  85.   TempPtr( void *block );
  86.   ~TempPtr( );
  87.   operator void* ( )        {return fBlock;}
  88.   void* operator= ( void *b )    {return (fBlock = b);}
  89.  
  90.   protected:
  91.   void* fBlock;
  92. };
  93.  
  94.  
  95. class BaseTempObj
  96. {
  97.   public:
  98.   virtual ~BaseTempObj();
  99.  
  100.   protected:
  101.   ODObject *fObj;
  102. };
  103.  
  104.  
  105. class BaseTempRef
  106. {
  107.   public:
  108.   void Release();
  109.   virtual ~BaseTempRef();
  110.  
  111.   protected:
  112.   ODRefCntObject *fObj;
  113. };
  114.  
  115.  
  116. //===========================================================================
  117. //  TempObj <T>
  118. //===========================================================================
  119.  
  120.  
  121. template<class T> class TempObj :public BaseTempObj
  122. {
  123.   public:
  124.   TempObj( T* );
  125.   T* operator-> ()    {return (T*)fObj;}
  126.   operator T* ()      {return (T*)fObj;}
  127.  
  128.   T* operator= (T* t)    {fObj=t; return t;}
  129.  
  130.   T* DontDelete()      {T* temp=(T*)fObj; fObj=kODNULL; return temp;}
  131. };
  132.  
  133. // Implementation of the TempObj constructor:
  134. template<class T> TempObj<T>::TempObj( T *obj )
  135. {
  136.   fObj = obj;
  137. }
  138.  
  139.  
  140. //===========================================================================
  141. //  TempRef <T>
  142. //
  143. //  Supports a few extra goodies:
  144. //    Release()    Releases the object and sets the pointer to NULL.
  145. //    DontRelease()  Sets the pointer to NULL (so the destructor will not
  146. //              release the object) but returns the old pointer.
  147. //
  148. //===========================================================================
  149.  
  150.  
  151. template<class T> class TempRef :public BaseTempRef
  152. {
  153.   public:
  154.   TempRef( T* );
  155.   T* operator-> ()    {return (T*)fObj;}
  156.   operator T* ()      {return (T*)fObj;}
  157.   T* operator=( T *t )  {fObj=t; return t;}
  158.  
  159.   T* DontRelease()    {T* temp=(T*)fObj; fObj=kODNULL; return temp;}
  160. };
  161.  
  162.  
  163. // Implementation of the TempRef constructor:
  164. template<class T> TempRef<T>::TempRef( T *obj )
  165. {
  166.   fObj = obj;
  167. }
  168.  
  169. //===========================================================================
  170. //  Instantiations of TempObj and TempRef. Add your own if necessary.
  171. //===========================================================================
  172.  
  173. class ODFrameFacetIterator;
  174. class ODFocusSetIterator;
  175. class ODFrame;
  176. class ODPart;
  177. class ODShape;
  178. class ODTransform;
  179. class ODStorageUnit;
  180. class ODWindow;
  181.  
  182. typedef TempObj<ODFrameFacetIterator>  TempODFrameFacetIterator;
  183. typedef TempObj<ODFocusSetIterator>    TempODFocusSetIterator;
  184.  
  185. typedef TempRef<ODFrame>        TempODFrame;
  186. typedef TempRef<ODPart>          TempODPart;
  187. typedef TempRef<ODShape>        TempODShape;
  188. typedef TempRef<ODTransform>      TempODTransform;
  189. typedef TempRef<ODStorageUnit>      TempODStorageUnit;
  190. typedef TempRef<ODWindow>        TempODWindow;
  191.  
  192. #endif /*_TEMPOBJ_*/
  193.