include/wx/cocoa/ObjcRef.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/cocoa/ObjcRef.h
   3 // Purpose:     wxObjcAutoRef template class
   4 // Author:      David Elliott
   5 // Modified by:
   6 // Created:     2004/03/28
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2004 David Elliott <dfe@cox.net>
   9 // Licence:     wxWindows licence
  10 /////////////////////////////////////////////////////////////////////////////
  11
  12 #ifndef _WX_COCOA_OBJCREF_H__
  13 #define _WX_COCOA_OBJCREF_H__
  14
  15 // Reuse wxCFRef-related code (e.g. wxCFRetain/wxCFRelease)
  16 #include "wx/mac/corefoundation/cfref.h"
  17
  18 /*
  19 wxObjcAutoRefFromAlloc: construct a reference to an object that was
  20 [NSObject -alloc]'ed and thus does not need a retain
  21 wxObjcAutoRef: construct a reference to an object that was
  22 either autoreleased or is retained by something else.
  23 */
  24
  25 struct objc_object;
  26
  27 // We must do any calls to Objective-C from an Objective-C++ source file
  28 class wxObjcAutoRefBase
  29 {
  30 protected:
  31     /*! @function   ObjcRetain
  32         @abstract   Simply does [p retain].
  33      */
  34     static struct objc_object* ObjcRetain(struct objc_object*);
  35
  36     /*! @function   ObjcRelease
  37         @abstract   Simply does [p release].
  38      */
  39     static void ObjcRelease(struct objc_object*);
  40 };
  41
  42 /*! @class      wxObjcAutoRefFromAlloc
  43     @templatefield  T       The type of _pointer_ (e.g. NSString*, NSRunLoop*)
  44     @abstract   Pointer-holder for Objective-C objects
  45     @discussion
  46     When constructing this object from a raw pointer, the pointer is assumed to have
  47     come from an alloc-style method.  That is, once you construct this object from
  48     the pointer you must not balance your alloc with a call to release.
  49
  50     This class has been carefully designed to work with both the traditional Retain/Release
  51     and the new Garbage Collected modes.  In RR-mode it will prevent the object from being
  52     released by managing the reference count using the retain/release semantics.  In GC-mode
  53     it will use a method (currently CFRetain/CFRelease) to ensure the object will never be
  54     finalized until this object is destroyed.
  55  */
  56
  57 template <class T>
  58 class wxObjcAutoRefFromAlloc: wxObjcAutoRefBase
  59 {
  60 public:
  61     wxObjcAutoRefFromAlloc(T p = 0)
  62     :   m_ptr(p)
  63     // NOTE: this is from alloc.  Do NOT retain
  64     {
  65         //  CFRetain
  66         //      GC:     Object is strongly retained and prevented from being collected
  67         //      non-GC: Simply realizes it's an Objective-C object and calls [p retain]
  68         wxCFRetain(p);
  69         //  ObjcRelease (e.g. [p release])
  70         //      GC:     Objective-C retain/release mean nothing in GC mode
  71         //      non-GC: This is a normal release call, balancing the retain
  72         ObjcRelease(static_cast<T>(p));
  73         //  The overall result:
  74         //      GC:     Object is strongly retained
  75         //      non-GC: Retain count is the same as it was (retain then release)
  76     }
  77     wxObjcAutoRefFromAlloc(const wxObjcAutoRefFromAlloc& otherRef)
  78     :   m_ptr(otherRef.m_ptr)
  79     {   wxCFRetain(m_ptr); }
  80     ~wxObjcAutoRefFromAlloc()
  81     {   wxCFRelease(m_ptr); }
  82     wxObjcAutoRefFromAlloc& operator=(const wxObjcAutoRefFromAlloc& otherRef)
  83     {   wxCFRetain(otherRef.m_ptr);
  84         wxCFRelease(m_ptr);
  85         m_ptr = otherRef.m_ptr;
  86         return *this;
  87     }
  88     operator T() const
  89     {   return static_cast<T>(m_ptr); }
  90     T operator->() const
  91     {   return static_cast<T>(m_ptr); }
  92 protected:
  93     /*! @field      m_ptr       The pointer to the Objective-C object
  94         @discussion
  95         The pointer to the Objective-C object is typed as void* to avoid compiler-generated write
  96         barriers as would be used for implicitly __strong object pointers and to avoid the similar
  97         read barriers as would be used for an explicitly __weak object pointer.  The write barriers
  98         are unsuitable because they assume the pointer (e.g. this object) is located in the heap
  99         which we can't guarantee and in fact most often we are used as a global.  We therefore
 100         use the CFRetain/CFRelease functions which work regardless of our memory location.
 101      */
 102     void *m_ptr;
 103 };
 104
 105 /*!
 106     @class      wxObjcAutoRef
 107     @description
 108     A pointer holder that does retain its argument.
 109     NOTE: It is suggest that you instead use wxObjcAutoRefFromAlloc<T> foo([aRawPointer retain])
 110  */
 111 template <class T>
 112 class wxObjcAutoRef: public wxObjcAutoRefFromAlloc<T>
 113 {
 114 public:
 115     /*! @method     wxObjcAutoRef
 116         @description
 117         Uses the underlying wxObjcAutoRefFromAlloc and simply does a typical [p retain] such that
 118         in RR-mode the object is in effectively the same retain-count state as it would have been
 119         coming straight from an alloc method.
 120      */
 121     wxObjcAutoRef(T p = 0)
 122     :   wxObjcAutoRefFromAlloc<T>(p)
 123     {   // NOTE: ObjcRetain is correct because in GC-mode it balances ObjcRelease in our superclass constructor
 124         // In RR mode it does retain and the superclass does retain/release thus resulting in an overall retain.
 125         ObjcRetain(static_cast<T>(wxObjcAutoRefFromAlloc<T>::m_ptr));
 126     }
 127     ~wxObjcAutoRef() {}
 128     wxObjcAutoRef(const wxObjcAutoRef& otherRef)
 129     :   wxObjcAutoRefFromAlloc<T>(otherRef)
 130     {}
 131     wxObjcAutoRef(const wxObjcAutoRefFromAlloc<T>& otherRef)
 132     :   wxObjcAutoRefFromAlloc<T>(otherRef)
 133     {}
 134     wxObjcAutoRef& operator=(const wxObjcAutoRef& otherRef)
 135     {   return wxObjcAutoRefFromAlloc<T>::operator=(otherRef); }
 136 };
 137
 138 #endif //ndef _WX_COCOA_OBJCREF_H__