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