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.
27static 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_
39