home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / odtlktv4.zip / ODTLKT / TOOLKIT / BETA / SAMPLES / OPENDOC / PUBUTILS / ODUTILS.H < prev    next >
Text File  |  1995-11-29  |  7KB  |  145 lines
  1. /**********************************************************************/
  2. /*  Licensed Materials - Property of IBM                              */
  3. /*                                                                    */
  4. /*                                                                    */
  5. /* Copyright (C) International Business Machines Corp., 1994.         */
  6. /* Copyright (C) Apple Computer, Inc., 1994                           */
  7. /*                                                                    */
  8. /*  US Government Users Restricted Rights -                           */
  9. /*  Use, duplication, or disclosure restricted                        */
  10. /*  by GSA ADP Schedule Contract with IBM Corp.                       */
  11. /*                                                                    */
  12. /*  File:     ODUtils.h                                               */
  13. /*                                                                    */
  14. /*  Contains: Object utility functions                                */
  15. /*                                                                    */
  16. /*  Theory Of Operation:                                              */
  17. /*                                                                    */
  18. /*  These are useful utilities for use with objects, particularly     */
  19. /*  counted objects. Some are functions rather than macros, to reduce */
  20. /*  code size, and can be made inline later if necessary.             */
  21. /*                                                                    */
  22. /*  ODDeleteObject deletes an object (which doesn't need to           */
  23. /*  need to be a SOM object) and sets the variable pointing to it to  */
  24. /*  NULL.                                                             */
  25. /*                                                                    */
  26. /*  ODReleaseObject is similar, but releases the object instead of    */
  27. /*  deleting it.  Use this one for ref-counted objects.               */
  28. /*                                                                    */
  29. /*  ODFinalReleaseObject is similar to ODReleaseObject, except that   */
  30. /*  it is meant to be used in code which is releasing the last        */
  31. /*  reference to that object.  I.E.  it does an ASSERT(refcount == 1) */
  32. /*  before calling release.                                           */
  33. /*                                                                    */
  34. /*  ODAcquireObject bumps the ref-count of an object, unless it's     */
  35. /*  NULL.                                                             */
  36. /*                                                                    */
  37. /*  ODSafeReleaseObject also releases an object, but requires no      */
  38. /*  Environment parameter and can't throw an exception.  It's for use */
  39. /*  _only_ in somUninit methods, where no Environment is available.   */
  40. /*                                                                    */
  41. /*  ODTransferReference lowers one object's refCount while            */
  42. /*  incrementing another's.  It's useful in things like setters where */
  43. /*  you want to forget about one object and remember another.  It     */
  44. /*  does the right thing if either pointer is NULL or if they point   */
  45. /*  to the same object.  ** This function may throw an exception in   */
  46. /*  the unlikely case that the Acquire or Release call fails.         */
  47. /*                                                                    */
  48. /*  ODCopyAndRelease returns a copy of an object while releasing the  */
  49. /*  object.  This is useful when transferring control of an object to */
  50. /*  the caller, but the caller has permission to modify the object.   */
  51. /*  It's optimized for the case where the ref-count of the object is  */
  52. /*  1, in which case it just returns the original object since no     */
  53. /*  copying is needed.  (This function works only on ODShapes and     */
  54. /*  ODTransforms, which are the only classes that provide a Copy      */
  55. /*  method.)  ** This function may throw an exception in the unlikely */
  56. /*  case that the GetRefCount or Release call fails.                  */
  57. /*                                                                    */
  58. /*                                                                    */
  59. /*  The "do...while(0)" blocks wrapped around the macros are there to */
  60. /*  prevent syntactic problems if a macro call is immediately         */
  61. /*  followed by an "else" statement, to keep the "else" from binding  */
  62. /*  to the "if" in the macro body.  The "while" loop is optimized out */
  63. /*  by the compiler and has no effect on the flow of control or code  */
  64. /*  quality.                                                          */
  65. /*                                                                    */
  66. /**********************************************************************/
  67.  
  68. #ifndef _ODUTILS_
  69. #define _ODUTILS_
  70.  
  71. #ifndef _ODTYPES_
  72. #include "ODTypes.h"
  73. #endif
  74.  
  75.  
  76. struct Environment;
  77. class ODObject;
  78. class ODShape;
  79. class ODTransform;
  80. class ODRefCntObject;
  81.  
  82.  
  83. #define  ODDeleteObject(object)  \
  84.    do{                     \
  85.       if (object!=kODNULL) {  \
  86.          delete object;    \
  87.          object = kODNULL; \
  88.       }                 \
  89.    }while(0)
  90.  
  91. #ifndef INCL_ODDTS 
  92.  
  93. #define  ODReleaseObject(ev, object) \
  94.    do{                        \
  95.       if (object!=kODNULL) {     \
  96.          object->Release(ev); \
  97.          object = kODNULL;    \
  98.       }                    \
  99.    }while(0)
  100.  
  101. #define  ODFinalReleaseObject(ev, object) \
  102.    do{                        \
  103.       if (object!=kODNULL) {     \
  104.          WASSERT(object->GetRefCount(ev) == 1); \
  105.          object->Release(ev); \
  106.          object = kODNULL;    \
  107.       }                    \
  108.    }while(0)
  109.  
  110. #else
  111.  
  112. #define  ODReleaseObject(object) \
  113.    do{                        \
  114.       if (object!=kODNULL) {     \
  115.          object->Release(); \
  116.          object = kODNULL;    \
  117.       }                    \
  118.    }while(0)
  119.  
  120. #define  ODFinalReleaseObject(object) \
  121.    do{                        \
  122.       if (object!=kODNULL) {     \
  123.          WASSERT(object->GetRefCount() == 1); \
  124.          object->Release(); \
  125.          object = kODNULL;    \
  126.       }                    \
  127.    }while(0)
  128.  
  129. #endif // ! INCL_ODDTS
  130.  
  131. void ODAcquireObject(Environment* ev, ODRefCntObject* object);
  132.  
  133. void     ODSafeReleaseObject( ODRefCntObject* );   // Needs no ev, throws no exceptions
  134.  
  135. void     ODTransferReference( Environment*, ODRefCntObject *oldObj,
  136.                                     ODRefCntObject *newObj );
  137.  
  138. ODShape* ODCopyAndRelease( Environment*, ODShape* );
  139.  
  140. ODTransform*ODCopyAndRelease( Environment*, ODTransform* );
  141.  
  142. ODBoolean ODObjectsAreEqual(Environment* ev, ODObject* a, ODObject* b);
  143.  
  144. #endif //_ODUTILS_
  145.