include/wx/mac/corefoundation/cfref.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/mac/corefoundation/cfref.h
   3 // Purpose:     wxCFRef template class
   4 // Author:      David Elliott <dfe@cox.net>
   5 // Modified by: Stefan Csomor
   6 // Created:     2007/05/10
   7 // RCS-ID:      $Id$
   8 // Copyright:   (c) 2007 David Elliott <dfe@cox.net>, Stefan Csomor
   9 // Licence:     wxWindows licence
  10 // Notes:       See http://developer.apple.com/documentation/CoreFoundation/Conceptual/CFMemoryMgmt/index.html
  11 /////////////////////////////////////////////////////////////////////////////
  12 /*! @header     wx/mac/corefoundation/cfref.h
  13     @abstract   wxCFRef template class
  14     @discussion FIXME: Convert doc tags to something less buggy with C++
  15 */
  16
  17 #ifndef _WX_MAC_COREFOUNDATION_CFREF_H__
  18 #define _WX_MAC_COREFOUNDATION_CFREF_H__
  19
  20 // #include <CoreFoundation/CFBase.h>
  21 /* Don't include CFBase.h such that this header can be included from public
  22  * headers with minimal namespace pollution.
  23  * Note that Darwin CF uses extern for CF_EXPORT.  If we need this on Win32
  24  * or non-Darwin Mac OS we'll need to define the appropriate __declspec.
  25  */
  26 extern "C" {
  27 typedef const void *CFTypeRef;
  28 extern /* CF_EXPORT */
  29 CFTypeRef CFRetain(CFTypeRef cf);
  30 extern /* CF_EXPORT */
  31 void CFRelease(CFTypeRef cf);
  32 } // extern "C"
  33
  34
  35 /*! @function   wxCFRelease
  36     @abstract   A CFRelease variant that checks for NULL before releasing.
  37     @discussion The parameter is template not for type safety but to ensure the argument
  38                 is a raw pointer and not a ref holder of any type.
  39 */
  40 template <class Type>
  41 inline void wxCFRelease(Type *r)
  42 {
  43     if ( r != NULL )
  44         ::CFRelease((CFTypeRef)r);
  45 }
  46
  47 /*! @function   wxCFRetain
  48     @abstract   A typesafe CFRetain variant that checks for NULL.
  49 */
  50 template <class Type>
  51 inline Type* wxCFRetain(Type *r)
  52 {
  53     // NOTE(DE): Setting r to the result of CFRetain improves efficiency on both x86 and PPC
  54     // Casting r to CFTypeRef ensures we are calling the real C version defined in CFBase.h
  55     // and not any possibly templated/overloaded CFRetain.
  56     if ( r != NULL )
  57         r = (Type*)::CFRetain((CFTypeRef)r);
  58     return r;
  59 }
  60
  61 template <class refType>
  62 class wxCFRef;
  63
  64 /*! @class wxCFWeakRef
  65     @templatefield  refType     The CF reference type (e.g. CFStringRef, CFRunLoopRef, etc.)
  66                                 It should already be a pointer.  This is different from
  67                                 shared_ptr where the template parameter is the pointee type.
  68     @discussion Wraps a raw pointer without any retain or release.
  69                 Provides a way to get what amounts to a raw pointer from a wxCFRef without
  70                 using a raw pointer.  Unlike a raw pointer, constructing a wxCFRef from this
  71                 class will cause it to be retained because it is assumed that a wxCFWeakRef
  72                 does not own its pointer.
  73 */
  74 template <class refType>
  75 class wxCFWeakRef
  76 {
  77     template <class refTypeA, class otherRefType>
  78     friend wxCFWeakRef<refTypeA> static_cfref_cast(const wxCFRef<otherRefType> &otherRef);
  79 public:
  80     /*! @method     wxCFWeakRef
  81         @abstract   Creates a NULL reference
  82     */
  83     wxCFWeakRef()
  84     :   m_ptr(NULL)
  85     {}
  86
  87     // Default copy constructor is fine.
  88     // Default destructor is fine but we'll set NULL to avoid bugs
  89     ~wxCFWeakRef()
  90     {   m_ptr = NULL; }
  91
  92     // Do not implement a raw-pointer constructor.
  93
  94     /*! @method     wxCFWeakRef
  95         @abstract   Copies another ref holder where its type can be converted to ours
  96         @templatefield otherRefType     Any type held by another wxCFWeakRef.
  97         @param otherRef The other weak ref holder to copy.
  98         @discussion This is merely a copy or implicit cast.
  99     */
 100     template <class otherRefType>
 101     wxCFWeakRef(const wxCFWeakRef<otherRefType>& otherRef)
 102     :   m_ptr(otherRef.get()) // Implicit conversion from otherRefType to refType should occur
 103     {}
 104
 105     /*! @method     wxCFWeakRef
 106         @abstract   Copies a strong ref holder where its type can be converted to ours
 107         @templatefield otherRefType     Any type held by a wxCFRef.
 108         @param otherRef The strong ref holder to copy.
 109         @discussion This ref is merely a pointer copy, the strong ref still holds the pointer.
 110     */
 111     template <class otherRefType>
 112     wxCFWeakRef(const wxCFRef<otherRefType>& otherRef)
 113     :   m_ptr(otherRef.get()) // Implicit conversion from otherRefType to refType should occur
 114     {}
 115
 116     /*! @method     get
 117         @abstract   Explicit conversion to the underlying pointer type
 118         @discussion Allows the caller to explicitly get the underlying pointer.
 119     */
 120     refType get() const
 121     {   return m_ptr; }
 122
 123     /*! @method     operator refType
 124         @abstract   Implicit conversion to the underlying pointer type
 125         @discussion Allows the ref to be used in CF function calls.
 126     */
 127     operator refType() const
 128     {   return m_ptr; }
 129
 130 protected:
 131     /*! @method     wxCFWeakRef
 132         @abstract   Constructs a weak reference to the raw pointer
 133         @templatefield otherType    Any type.
 134         @param p        The raw pointer to assume ownership of.  May be NULL.
 135         @discussion This method is private so that the friend static_cfref_cast can use it
 136     */
 137     template <class otherType>
 138     explicit wxCFWeakRef(otherType *p)
 139     :   m_ptr(p) // Implicit conversion from otherType* to refType should occur.
 140     {}
 141
 142     /*! @var m_ptr      The raw pointer.
 143     */
 144     refType m_ptr;
 145 };
 146
 147 /*! @class wxCFRef
 148     @templatefield  refType     The CF reference type (e.g. CFStringRef, CFRunLoopRef, etc.)
 149                                 It should already be a pointer.  This is different from
 150                                 shared_ptr where the template parameter is the pointee type.
 151     @discussion Properly retains/releases reference to CoreFoundation objects
 152 */
 153 template <class refType>
 154 class wxCFRef
 155 {
 156 public:
 157     /*! @method     wxCFRef
 158         @abstract   Creates a NULL reference
 159     */
 160     wxCFRef()
 161     :   m_ptr(NULL)
 162     {}
 163
 164     /*! @method     wxCFRef
 165         @abstract   Assumes ownership of p and creates a reference to it.
 166         @templatefield otherType    Any type.
 167         @param p        The raw pointer to assume ownership of.  May be NULL.
 168         @discussion Like shared_ptr, it is assumed that the caller has a strong reference to p and intends
 169                     to transfer ownership of that reference to this ref holder.  If the object comes from
 170                     a Create or Copy method then this is the correct behavior.  If the object comes from
 171                     a Get method then you must CFRetain it yourself before passing it to this constructor.
 172                     A handy way to do this is to use the non-member wxCFRefFromGet factory funcion.
 173                     This method is templated and takes an otherType *p.  This prevents implicit conversion
 174                     using an operator refType() in a different ref-holding class type.
 175     */
 176     template <class otherType>
 177     explicit wxCFRef(otherType *p)
 178     :   m_ptr(p) // Implicit conversion from otherType* to refType should occur.
 179     {}
 180
 181     /*! @method     wxCFRef
 182         @abstract   Copies a ref holder of the same type
 183         @param otherRef The other ref holder to copy.
 184         @discussion Ownership will be shared by the original ref and the newly created ref. That is,
 185                     the object will be explicitly retained by this new ref.
 186     */
 187     wxCFRef(const wxCFRef& otherRef)
 188     :   m_ptr(wxCFRetain(otherRef.m_ptr))
 189     {}
 190
 191     /*! @method     wxCFRef
 192         @abstract   Copies a ref holder where its type can be converted to ours
 193         @templatefield otherRefType     Any type held by another wxCFRef.
 194         @param otherRef The other ref holder to copy.
 195         @discussion Ownership will be shared by the original ref and the newly created ref. That is,
 196                     the object will be explicitly retained by this new ref.
 197     */
 198     template <class otherRefType>
 199     wxCFRef(const wxCFRef<otherRefType>& otherRef)
 200     :   m_ptr(wxCFRetain(otherRef.get())) // Implicit conversion from otherRefType to refType should occur
 201     {}
 202
 203     /*! @method     wxCFRef
 204         @abstract   Copies a weak ref holder where its type can be converted to ours
 205         @templatefield otherRefType     Any type held by a wxCFWeakRef.
 206         @param otherRef The weak ref holder to copy.
 207         @discussion Ownership will be taken by this newly created ref. That is,
 208                     the object will be explicitly retained by this new ref.
 209                     Ownership is most likely shared with some other ref as well.
 210     */
 211     template <class otherRefType>
 212     wxCFRef(const wxCFWeakRef<otherRefType>& otherRef)
 213     :   m_ptr(wxCFRetain(otherRef.get())) // Implicit conversion from otherRefType to refType should occur
 214     {}
 215
 216     /*! @method     ~wxCFRef
 217         @abstract   Releases (potentially shared) ownership of the ref.
 218         @discussion A ref holder instance is always assumed to have ownership so ownership is always
 219                     released (CFRelease called) upon destruction.
 220     */
 221     ~wxCFRef()
 222     {   reset(); }
 223
 224     /*! @method     operator=
 225         @abstract   Assigns the other ref's pointer to us when the otherRef is the same type.
 226         @param otherRef The other ref holder to copy.
 227         @discussion The incoming pointer is retained, the original pointer is released, and this object
 228                     is made to point to the new pointer.
 229     */
 230     wxCFRef& operator=(const wxCFRef& otherRef)
 231     {
 232         wxCFRetain(otherRef.m_ptr);
 233         wxCFRelease(m_ptr);
 234         m_ptr = otherRef.m_ptr;
 235         return *this;
 236     }
 237
 238     /*! @method     operator=
 239         @abstract   Assigns the other ref's pointer to us when the other ref can be converted to our type.
 240         @templatefield otherRefType     Any type held by another wxCFRef
 241         @param otherRef The other ref holder to copy.
 242         @discussion The incoming pointer is retained, the original pointer is released, and this object
 243                     is made to point to the new pointer.
 244     */
 245     template <class otherRefType>
 246     wxCFRef& operator=(const wxCFRef<otherRefType>& otherRef)
 247     {
 248         wxCFRetain(otherRef.get());
 249         wxCFRelease(m_ptr);
 250         m_ptr = otherRef.get(); // Implicit conversion from otherRefType to refType should occur
 251         return *this;
 252     }
 253
 254     /*! @method     get
 255         @abstract   Explicit conversion to the underlying pointer type
 256         @discussion Allows the caller to explicitly get the underlying pointer.
 257     */
 258     refType get() const
 259     {   return m_ptr; }
 260
 261     /*! @method     operator refType
 262         @abstract   Implicit conversion to the underlying pointer type
 263         @discussion Allows the ref to be used in CF function calls.
 264     */
 265     operator refType() const
 266     {   return m_ptr; }
 267
 268 #if 0
 269     <   // HeaderDoc is retarded and thinks the GT from operator-> is part of a template param.
 270         // So give it that < outside of a comment to fake it out. (if 0 is not a comment to HeaderDoc)
 271 #endif
 272
 273     /*! @method     operator-&gt;
 274         @abstract   Implicit conversion to the underlying pointer type
 275         @discussion This is nearly useless for CF types which are nearly always opaque
 276     */
 277     refType operator-> () const
 278     {   return m_ptr; }
 279
 280     /*! @method     reset
 281         @abstract   Nullifies the reference
 282         @discussion Releases ownership (calls CFRelease) before nullifying the pointer.
 283     */
 284     void reset()
 285     {
 286         wxCFRelease(m_ptr);
 287         m_ptr = NULL;
 288     }
 289
 290     /*! @method     reset
 291         @abstract   Sets this to a new reference
 292         @templatefield otherType    Any type.
 293         @param p        The raw pointer to assume ownership of
 294         @discussion The existing reference is released (like destruction).  It is assumed that the caller
 295                     has a strong reference to the new p and intends to transfer ownership of that reference
 296                     to this ref holder.  Take care to call CFRetain if you received the object from a Get method.
 297                     This method is templated and takes an otherType *p.  This prevents implicit conversion
 298                     using an operator refType() in a different ref-holding class type.
 299     */
 300     template <class otherType>
 301     void reset(otherType* p)
 302     {
 303         wxCFRelease(m_ptr);
 304         m_ptr = p; // Automatic conversion should occur
 305     }
 306 protected:
 307     /*! @var m_ptr      The raw pointer.
 308     */
 309     refType m_ptr;
 310 };
 311
 312 /*! @function   wxCFRefFromGet
 313     @abstract   Factory function to create wxCFRef from a raw pointer obtained from a Get-rule function
 314     @param  p           The pointer to retain and create a wxCFRef from.  May be NULL.
 315     @discussion Unlike the wxCFRef raw pointer constructor, this function explicitly retains its
 316                 argument.  This can be used for functions such as CFDictionaryGetValue() or
 317                 CFAttributedStringGetString() which return a temporary reference (Get-rule functions).
 318                 FIXME: Anybody got a better name?
 319 */
 320 template <typename Type>
 321 inline wxCFRef<Type*> wxCFRefFromGet(Type *p)
 322 {
 323     return wxCFRef<Type*>(wxCFRetain(p));
 324 }
 325
 326 /*! @function   static_cfref_cast
 327     @abstract   Works like static_cast but with a wxCFRef as the argument.
 328     @param  refType     Template parameter.  The destination raw pointer type
 329     @param  otherRef    Normal parameter.  The source wxCFRef<> object.
 330     @discussion This is intended to be a clever way to make static_cast work while allowing
 331                 the return value to be converted to either a strong ref or a raw pointer
 332                 while ensuring that the retain count is updated appropriately.
 333
 334                 This is modeled after shared_ptr's static_pointer_cast.  Just as wxCFRef is
 335                 parameterized on a pointer to an opaque type so is this class.  Note that
 336                 this differs from shared_ptr which is parameterized on the pointee type.
 337
 338                 FIXME: Anybody got a better name?
 339 */
 340 template <class refType, class otherRefType>
 341 inline wxCFWeakRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef);
 342
 343 template <class refType, class otherRefType>
 344 inline wxCFWeakRef<refType> static_cfref_cast(const wxCFRef<otherRefType> &otherRef)
 345 {
 346     return wxCFWeakRef<refType>(static_cast<refType>(otherRef.get()));
 347 }
 348
 349 /*! @function   CFRelease
 350     @abstract   Overloads CFRelease so that the user is warned of bad behavior.
 351     @discussion It is rarely appropriate to retain or release a wxCFRef.  If one absolutely
 352                 must do it he can explicitly get() the raw pointer
 353                 Normally, this function is unimplemented resulting in a linker error if used.
 354 */
 355 template <class T>
 356 inline void CFRelease(const wxCFRef<T*> & cfref) DEPRECATED_ATTRIBUTE;
 357
 358 /*! @function   CFRetain
 359     @abstract   Overloads CFRetain so that the user is warned of bad behavior.
 360     @discussion It is rarely appropriate to retain or release a wxCFRef.  If one absolutely
 361                 must do it he can explicitly get() the raw pointer
 362                 Normally, this function is unimplemented resulting in a linker error if used.
 363 */
 364 template <class T>
 365 inline void CFRetain(const wxCFRef<T*>& cfref) DEPRECATED_ATTRIBUTE;
 366
 367 // Change the 0 to a 1 if you want the functions to work (no link errors)
 368 // Neither function will cause retain/release side-effects if implemented.
 369 #if 0
 370 template <class T>
 371 void CFRelease(const wxCFRef<T*> & cfref)
 372 {
 373     CFRelease(cfref.get());
 374 }
 375
 376 template <class T>
 377 void CFRetain(const wxCFRef<T*> & cfref)
 378 {
 379     CFRetain(cfref.get());
 380 }
 381 #endif
 382
 383 #endif //ndef _WX_MAC_COREFOUNDATION_CFREF_H__
 384