base/foundation_utils_mac.h

   1 // Copyright (c) 2008 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef BASE_FOUNDATION_UTILS_MAC_H_
   6 #define BASE_FOUNDATION_UTILS_MAC_H_
   7 #pragma once
   8
   9 #include <CoreFoundation/CoreFoundation.h>
  10 #import <Foundation/Foundation.h>
  11
  12 // CFTypeRefToNSObjectAutorelease transfers ownership of a Core Foundation
  13 // object (one derived from CFTypeRef) to the Foundation memory management
  14 // system.  In a traditional managed-memory environment, cf_object is
  15 // autoreleased and returned as an NSObject.  In a garbage-collected
  16 // environment, cf_object is marked as eligible for garbage collection.
  17 //
  18 // This function should only be used to convert a concrete CFTypeRef type to
  19 // its equivalent "toll-free bridged" NSObject subclass, for example,
  20 // converting a CFStringRef to NSString.
  21 //
  22 // By calling this function, callers relinquish any ownership claim to
  23 // cf_object.  In a managed-memory environment, the object's ownership will be
  24 // managed by the innermost NSAutoreleasePool, so after this function returns,
  25 // callers should not assume that cf_object is valid any longer than the
  26 // returned NSObject.
  27 static inline id CFTypeRefToNSObjectAutorelease(CFTypeRef cf_object) {
  28   // When GC is on, NSMakeCollectable marks cf_object for GC and autorelease
  29   // is a no-op.
  30   //
  31   // In the traditional GC-less environment, NSMakeCollectable is a no-op,
  32   // and cf_object is autoreleased, balancing out the caller's ownership claim.
  33   //
  34   // NSMakeCollectable returns nil when used on a NULL object.
  35   return [NSMakeCollectable(cf_object) autorelease];
  36 }
  37
  38 #endif  // BASE_FOUNDATION_UTILS_MAC_H_