home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / tlx501.zip / DISPOSE.H < prev    next >
C/C++ Source or Header  |  1996-01-05  |  6KB  |  178 lines
  1. /****************************************************************************
  2.     $Id: dispose.h 501.0 1995/03/07 12:26:42 RON Exp $
  3.  
  4.     Copyright (c) 1991-95 Tarma Software Research. All rights reserved.
  5.  
  6.     Project:    Tarma Library for C++ V5.0
  7.     Author:    Ron van der Wal
  8.  
  9.     Declarations for the Disposable pattern.
  10.  
  11.     $Log: dispose.h $
  12.     Revision 501.0  1995/03/07 12:26:42  RON
  13.     Updated for TLX 5.01
  14.     Revision 1.2  1995/01/31 16:29:18  RON
  15.     Update for release 012
  16.     Added partial support for SunPro C++ compiler
  17.     Revision 1.1  1995/01/05  15:33:17  ron
  18.     Initial revision
  19.  
  20. ****************************************************************************/
  21.  
  22. #ifndef _TLX_DISPOSE_H
  23. #define _TLX_DISPOSE_H
  24.  
  25. /*-----    Disposable pattern --------------------------------------------------
  26.  
  27.     Intent:
  28.  
  29.     This pattern models the situation where one or more objects must be
  30.     disposed, but only at controlled moments. A primary example is a
  31.     GUI application with a central event dispatching loop, where during
  32.     the dispatch of a single event one or more objects might become
  33.     ripe for disposal. However, it is often not safe to do so
  34.     immediately, because other objects might still need access to
  35.     the doomed objects. As a special case, the objects might 'commit
  36.     suicide' as the (indirect) result of the event, but cannot safely
  37.     do so at once. In those cases, the disposable object is marked as
  38.     such, and a specialized garbage manager will take care of the
  39.     actual clean-up at a more appropriate moment, e.g. before the next
  40.     event is dispatched.
  41.  
  42.     Participants:
  43.  
  44.     class TLDisposable    - (virtual) base class for disposable objects
  45.         MarkForDisposal()    - marks the object for garbage collection
  46.         ReclaimObject()    - removes the object from garbage collection
  47.         CollectGarbage()    - destroys all objects marked for disposal
  48.  
  49.     class TLCDChecker    - (virtual base class to check con/destruction
  50.         AssertValid()    - ensures that the object is valid
  51.  
  52.     Usage:
  53.  
  54.     Derive the class(es) that must be disposable from the TLDisposable
  55.     base class, possibly with virtual derivation to allow multiple
  56.     inheritance. When an instance of the class must be disposed, call
  57.     its MarkForDisposal() member function. The instance will be marked
  58.     for destruction, but not be destroyed until the static member
  59.     function TLDisposable::CollectGarbage() is called.
  60.  
  61. ---------------------------------------------------------------------------*/
  62.  
  63. #ifndef _TLX_TLX_H
  64. #include <tlx\501\tlx\h>
  65. #endif
  66.  
  67. /*---------------------------------------------------------------------------
  68.     TLCDChecker -
  69.  
  70.     Class for objects that need a check on construction and destruction.
  71.     It can be used a a member or a (virtual) base class; using it as a
  72.     member allows easier use of the containing class with respect to
  73.     derivation from other bases.
  74.  
  75.     In the non-debug version, the class is empty.
  76. ---------------------------------------------------------------------------*/
  77.  
  78. // Helper macro that can be used to include a member of class TLCDChecker,
  79. // This macro is only useful when combined with the debug version of the
  80. // library.
  81.  
  82. #ifdef NDEBUG
  83. #define INSERT_CHECKER
  84. #define TLX_ASSERT_VALID()    ((void)0)
  85. #else
  86. #define INSERT_CHECKER        TLCDChecker _mChecker;
  87. #define TLX_ASSERT_VALID()    _mChecker.AssertValid(__FILE__,__LINE__)
  88. #endif
  89.  
  90. class _TLXCLASS TLCDChecker
  91. {
  92.     // During debugging only, we insert extra checks as to the validity of
  93.     // the object with respect to initialization and destruction.
  94.  
  95.     enum {
  96.     osConstructed    = 0x4B4F,    // Marker for constructed object
  97.     osDestructed    = 0x3F21    // Marker for destructed object
  98.     };
  99.   #ifdef _TLXDBG
  100.     int16        mState;        // Current state
  101.   #endif
  102.  
  103. public:
  104.     TLCDChecker();
  105.     ~TLCDChecker();
  106.  
  107.     // Copying and assignment do not copy the check field
  108.  
  109.     TLCDChecker(const TLCDChecker &);
  110.     TLCDChecker &    operator =(const TLCDChecker &);
  111.  
  112.     // Function to check the validity of the object
  113.  
  114.     void        AssertValid(const char *, int) const;
  115. };
  116.  
  117. /*---------------------------------------------------------------------------
  118.     TLDisposable -
  119.  
  120.     (Virtual) base class for disposable objects. In the debug version, it
  121.     also contains a construction/destruction check.
  122. ---------------------------------------------------------------------------*/
  123.  
  124. class _TLXCLASS TLDisposable
  125. {
  126.     // Objects marked for disposal are put in a linked list with a static
  127.     // data member as its head.
  128.  
  129.     static TLDisposable *sGarbage;    // Chain of garbage objects
  130.     TLDisposable *    mNext;        // Next disposable object
  131.  
  132.     // During debugging only, we insert extra checks as to the validity of
  133.     // the object with respect to initialization and destruction.
  134.  
  135.   #ifdef _TLXDBG
  136.     TLCDChecker        _mChecker;
  137.   #endif
  138.  
  139. public:
  140.     TLDisposable();
  141.     virtual ~TLDisposable();
  142.  
  143.     // Copying and assignment do not copy the pointer fields
  144.  
  145.     TLDisposable(const TLDisposable &);
  146.     TLDisposable &    operator =(const TLDisposable &);
  147.  
  148.     // Functions to manage the disposal/reclamation process per instance
  149.  
  150.     void        MarkForDisposal();
  151.     void        ReclaimObject();
  152.     bool        IsMarkedForDisposal() const;
  153.  
  154.     // Static function to perform garbage collection on all disposed objects.
  155.  
  156.     static void        CollectGarbage();
  157.  
  158. private:
  159.     // Helper functions to add and remove instances from the linked list
  160.     // of disposable objects.
  161.  
  162.     void        AddToGarbage();
  163.     void        ExtractFromGarbage();
  164. };
  165.  
  166. /*---------------------------------------------------------------------------
  167.     Inline function definitions
  168. ---------------------------------------------------------------------------*/
  169.  
  170. //-----    TLCDChecker
  171.  
  172. #ifndef _TLXDBG
  173. inline void TLCDChecker::AssertValid(const char *, int) const
  174.     {}
  175. #endif
  176.  
  177. #endif    // _TLX_DISPOSE_H
  178.