runtime/objc.h

   1 /*
   2  * Copyright (c) 1999-2007 Apple Inc.  All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23 /*
  24  *      objc.h
  25  *      Copyright 1988-1996, NeXT Software, Inc.
  26  */
  27
  28 #ifndef _OBJC_OBJC_H_
  29 #define _OBJC_OBJC_H_
  30
  31 #include <sys/types.h>      // for __DARWIN_NULL
  32 #include <Availability.h>
  33 #include <objc/objc-api.h>
  34 #include <stdbool.h>
  35
  36 #if !OBJC_TYPES_DEFINED
  37 /// An opaque type that represents an Objective-C class.
  38 typedef struct objc_class *Class;
  39
  40 /// Represents an instance of a class.
  41 struct objc_object {
  42     Class _Nonnull isa  OBJC_ISA_AVAILABILITY;
  43 };
  44
  45 /// A pointer to an instance of a class.
  46 typedef struct objc_object *id;
  47 #endif
  48
  49 /// An opaque type that represents a method selector.
  50 typedef struct objc_selector *SEL;
  51
  52 /// A pointer to the function of a method implementation.
  53 #if !OBJC_OLD_DISPATCH_PROTOTYPES
  54 typedef void (*IMP)(void /* id, SEL, ... */ );
  55 #else
  56 typedef id _Nullable (*IMP)(id _Nonnull, SEL _Nonnull, ...);
  57 #endif
  58
  59 /// Type to represent a boolean value.
  60
  61 #if defined(__OBJC_BOOL_IS_BOOL)
  62     // Honor __OBJC_BOOL_IS_BOOL when available.
  63 #   if __OBJC_BOOL_IS_BOOL
  64 #       define OBJC_BOOL_IS_BOOL 1
  65 #   else
  66 #       define OBJC_BOOL_IS_BOOL 0
  67 #   endif
  68 #else
  69     // __OBJC_BOOL_IS_BOOL not set.
  70 #   if TARGET_OS_OSX || TARGET_OS_MACCATALYST || ((TARGET_OS_IOS || TARGET_OS_BRIDGE) && !__LP64__ && !__ARM_ARCH_7K)
  71 #      define OBJC_BOOL_IS_BOOL 0
  72 #   else
  73 #      define OBJC_BOOL_IS_BOOL 1
  74 #   endif
  75 #endif
  76
  77 #if OBJC_BOOL_IS_BOOL
  78     typedef bool BOOL;
  79 #else
  80 #   define OBJC_BOOL_IS_CHAR 1
  81     typedef signed char BOOL;
  82     // BOOL is explicitly signed so @encode(BOOL) == "c" rather than "C"
  83     // even if -funsigned-char is used.
  84 #endif
  85
  86 #define OBJC_BOOL_DEFINED
  87
  88 #if __has_feature(objc_bool)
  89 #define YES __objc_yes
  90 #define NO  __objc_no
  91 #else
  92 #define YES ((BOOL)1)
  93 #define NO  ((BOOL)0)
  94 #endif
  95
  96 #ifndef Nil
  97 # if __has_feature(cxx_nullptr)
  98 #   define Nil nullptr
  99 # else
 100 #   define Nil __DARWIN_NULL
 101 # endif
 102 #endif
 103
 104 #ifndef nil
 105 # if __has_feature(cxx_nullptr)
 106 #   define nil nullptr
 107 # else
 108 #   define nil __DARWIN_NULL
 109 # endif
 110 #endif
 111
 112 #ifndef __strong
 113 # if !__has_feature(objc_arc)
 114 #   define __strong /* empty */
 115 # endif
 116 #endif
 117
 118 #ifndef __unsafe_unretained
 119 # if !__has_feature(objc_arc)
 120 #   define __unsafe_unretained /* empty */
 121 # endif
 122 #endif
 123
 124 #ifndef __autoreleasing
 125 # if !__has_feature(objc_arc)
 126 #   define __autoreleasing /* empty */
 127 # endif
 128 #endif
 129
 130
 131 /**
 132  * Returns the name of the method specified by a given selector.
 133  *
 134  * @param sel A pointer of type \c SEL. Pass the selector whose name you wish to determine.
 135  *
 136  * @return A C string indicating the name of the selector.
 137  */
 138 OBJC_EXPORT const char * _Nonnull sel_getName(SEL _Nonnull sel)
 139     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 140
 141 /**
 142  * Registers a method with the Objective-C runtime system, maps the method
 143  * name to a selector, and returns the selector value.
 144  *
 145  * @param str A pointer to a C string. Pass the name of the method you wish to register.
 146  *
 147  * @return A pointer of type SEL specifying the selector for the named method.
 148  *
 149  * @note You must register a method name with the Objective-C runtime system to obtain the
 150  *  method’s selector before you can add the method to a class definition. If the method name
 151  *  has already been registered, this function simply returns the selector.
 152  */
 153 OBJC_EXPORT SEL _Nonnull sel_registerName(const char * _Nonnull str)
 154     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 155
 156 /**
 157  * Returns the class name of a given object.
 158  *
 159  * @param obj An Objective-C object.
 160  *
 161  * @return The name of the class of which \e obj is an instance.
 162  */
 163 OBJC_EXPORT const char * _Nonnull object_getClassName(id _Nullable obj)
 164     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 165
 166 /**
 167  * Returns a pointer to any extra bytes allocated with an instance given object.
 168  *
 169  * @param obj An Objective-C object.
 170  *
 171  * @return A pointer to any extra bytes allocated with \e obj. If \e obj was
 172  *   not allocated with any extra bytes, then dereferencing the returned pointer is undefined.
 173  *
 174  * @note This function returns a pointer to any extra bytes allocated with the instance
 175  *  (as specified by \c class_createInstance with extraBytes>0). This memory follows the
 176  *  object's ordinary ivars, but may not be adjacent to the last ivar.
 177  * @note The returned pointer is guaranteed to be pointer-size aligned, even if the area following
 178  *  the object's last ivar is less aligned than that. Alignment greater than pointer-size is never
 179  *  guaranteed, even if the area following the object's last ivar is more aligned than that.
 180  * @note In a garbage-collected environment, the memory is scanned conservatively.
 181  */
 182 OBJC_EXPORT void * _Nullable object_getIndexedIvars(id _Nullable obj)
 183     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 184
 185 /**
 186  * Identifies a selector as being valid or invalid.
 187  *
 188  * @param sel The selector you want to identify.
 189  *
 190  * @return YES if selector is valid and has a function implementation, NO otherwise.
 191  *
 192  * @warning On some platforms, an invalid reference (to invalid memory addresses) can cause
 193  *  a crash.
 194  */
 195 OBJC_EXPORT BOOL sel_isMapped(SEL _Nonnull sel)
 196     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 197
 198 /**
 199  * Registers a method name with the Objective-C runtime system.
 200  *
 201  * @param str A pointer to a C string. Pass the name of the method you wish to register.
 202  *
 203  * @return A pointer of type SEL specifying the selector for the named method.
 204  *
 205  * @note The implementation of this method is identical to the implementation of \c sel_registerName.
 206  * @note Prior to OS X version 10.0, this method tried to find the selector mapped to the given name
 207  *  and returned \c NULL if the selector was not found. This was changed for safety, because it was
 208  *  observed that many of the callers of this function did not check the return value for \c NULL.
 209  */
 210 OBJC_EXPORT SEL _Nonnull sel_getUid(const char * _Nonnull str)
 211     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 212
 213 typedef const void* objc_objectptr_t;
 214
 215
 216 // Obsolete ARC conversions.
 217
 218 OBJC_EXPORT id _Nullable objc_retainedObject(objc_objectptr_t _Nullable obj)
 219 #if !OBJC_DECLARE_SYMBOLS
 220     OBJC_UNAVAILABLE("use CFBridgingRelease() or a (__bridge_transfer id) cast instead")
 221 #endif
 222     ;
 223 OBJC_EXPORT id _Nullable objc_unretainedObject(objc_objectptr_t _Nullable obj)
 224 #if !OBJC_DECLARE_SYMBOLS
 225     OBJC_UNAVAILABLE("use a (__bridge id) cast instead")
 226 #endif
 227     ;
 228 OBJC_EXPORT objc_objectptr_t _Nullable objc_unretainedPointer(id _Nullable obj)
 229 #if !OBJC_DECLARE_SYMBOLS
 230     OBJC_UNAVAILABLE("use a __bridge cast instead")
 231 #endif
 232     ;
 233
 234
 235 #if !__OBJC2__
 236
 237 // The following declarations are provided here for source compatibility.
 238
 239 #if defined(__LP64__)
 240     typedef long arith_t;
 241     typedef unsigned long uarith_t;
 242 #   define ARITH_SHIFT 32
 243 #else
 244     typedef int arith_t;
 245     typedef unsigned uarith_t;
 246 #   define ARITH_SHIFT 16
 247 #endif
 248
 249 typedef char *STR;
 250
 251 #define ISSELECTOR(sel) sel_isMapped(sel)
 252 #define SELNAME(sel)    sel_getName(sel)
 253 #define SELUID(str)     sel_getUid(str)
 254 #define NAMEOF(obj)     object_getClassName(obj)
 255 #define IV(obj)         object_getIndexedIvars(obj)
 256
 257 #endif
 258
 259 #endif  /* _OBJC_OBJC_H_ */