runtime/message.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 #ifndef _OBJC_MESSAGE_H
  25 #define _OBJC_MESSAGE_H
  26
  27 #include <objc/objc.h>
  28 #include <objc/runtime.h>
  29
  30 #ifndef OBJC_SUPER
  31 #define OBJC_SUPER
  32
  33 /// Specifies the superclass of an instance.
  34 struct objc_super {
  35     /// Specifies an instance of a class.
  36     __unsafe_unretained _Nonnull id receiver;
  37
  38     /// Specifies the particular superclass of the instance to message.
  39 #if !defined(__cplusplus)  &&  !__OBJC2__
  40     /* For compatibility with old objc-runtime.h header */
  41     __unsafe_unretained _Nonnull Class class;
  42 #else
  43     __unsafe_unretained _Nonnull Class super_class;
  44 #endif
  45     /* super_class is the first class to search */
  46 };
  47 #endif
  48
  49
  50 /* Basic Messaging Primitives
  51  *
  52  * On some architectures, use objc_msgSend_stret for some struct return types.
  53  * On some architectures, use objc_msgSend_fpret for some float return types.
  54  * On some architectures, use objc_msgSend_fp2ret for some float return types.
  55  *
  56  * These functions must be cast to an appropriate function pointer type
  57  * before being called.
  58  */
  59 #if !OBJC_OLD_DISPATCH_PROTOTYPES
  60 #pragma clang diagnostic push
  61 #pragma clang diagnostic ignored "-Wincompatible-library-redeclaration"
  62 OBJC_EXPORT void
  63 objc_msgSend(void /* id self, SEL op, ... */ )
  64     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
  65
  66 OBJC_EXPORT void
  67 objc_msgSendSuper(void /* struct objc_super *super, SEL op, ... */ )
  68     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
  69 #pragma clang diagnostic pop
  70 #else
  71 /**
  72  * Sends a message with a simple return value to an instance of a class.
  73  *
  74  * @param self A pointer to the instance of the class that is to receive the message.
  75  * @param op The selector of the method that handles the message.
  76  * @param ...
  77  *   A variable argument list containing the arguments to the method.
  78  *
  79  * @return The return value of the method.
  80  *
  81  * @note When it encounters a method call, the compiler generates a call to one of the
  82  *  functions \c objc_msgSend, \c objc_msgSend_stret, \c objc_msgSendSuper, or \c objc_msgSendSuper_stret.
  83  *  Messages sent to an object’s superclass (using the \c super keyword) are sent using \c objc_msgSendSuper;
  84  *  other messages are sent using \c objc_msgSend. Methods that have data structures as return values
  85  *  are sent using \c objc_msgSendSuper_stret and \c objc_msgSend_stret.
  86  */
  87 OBJC_EXPORT id _Nullable
  88 objc_msgSend(id _Nullable self, SEL _Nonnull op, ...)
  89     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
  90 /**
  91  * Sends a message with a simple return value to the superclass of an instance of a class.
  92  *
  93  * @param super A pointer to an \c objc_super data structure. Pass values identifying the
  94  *  context the message was sent to, including the instance of the class that is to receive the
  95  *  message and the superclass at which to start searching for the method implementation.
  96  * @param op A pointer of type SEL. Pass the selector of the method that will handle the message.
  97  * @param ...
  98  *   A variable argument list containing the arguments to the method.
  99  *
 100  * @return The return value of the method identified by \e op.
 101  *
 102  * @see objc_msgSend
 103  */
 104 OBJC_EXPORT id _Nullable
 105 objc_msgSendSuper(struct objc_super * _Nonnull super, SEL _Nonnull op, ...)
 106     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 107 #endif
 108
 109
 110 /* Struct-returning Messaging Primitives
 111  *
 112  * Use these functions to call methods that return structs on the stack.
 113  * On some architectures, some structures are returned in registers.
 114  * Consult your local function call ABI documentation for details.
 115  *
 116  * These functions must be cast to an appropriate function pointer type
 117  * before being called.
 118  */
 119 #if !OBJC_OLD_DISPATCH_PROTOTYPES
 120 #pragma clang diagnostic push
 121 #pragma clang diagnostic ignored "-Wincompatible-library-redeclaration"
 122 OBJC_EXPORT void
 123 objc_msgSend_stret(void /* id self, SEL op, ... */ )
 124     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0)
 125     OBJC_ARM64_UNAVAILABLE;
 126
 127 OBJC_EXPORT void
 128 objc_msgSendSuper_stret(void /* struct objc_super *super, SEL op, ... */ )
 129     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0)
 130     OBJC_ARM64_UNAVAILABLE;
 131 #pragma clang diagnostic pop
 132 #else
 133 /**
 134  * Sends a message with a data-structure return value to an instance of a class.
 135  *
 136  * @see objc_msgSend
 137  */
 138 OBJC_EXPORT void
 139 objc_msgSend_stret(id _Nullable self, SEL _Nonnull op, ...)
 140     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0)
 141     OBJC_ARM64_UNAVAILABLE;
 142
 143 /**
 144  * Sends a message with a data-structure return value to the superclass of an instance of a class.
 145  *
 146  * @see objc_msgSendSuper
 147  */
 148 OBJC_EXPORT void
 149 objc_msgSendSuper_stret(struct objc_super * _Nonnull super,
 150                         SEL _Nonnull op, ...)
 151     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0)
 152     OBJC_ARM64_UNAVAILABLE;
 153 #endif
 154
 155
 156 /* Floating-point-returning Messaging Primitives
 157  *
 158  * Use these functions to call methods that return floating-point values
 159  * on the stack.
 160  * Consult your local function call ABI documentation for details.
 161  *
 162  * arm:    objc_msgSend_fpret not used
 163  * i386:   objc_msgSend_fpret used for `float`, `double`, `long double`.
 164  * x86-64: objc_msgSend_fpret used for `long double`.
 165  *
 166  * arm:    objc_msgSend_fp2ret not used
 167  * i386:   objc_msgSend_fp2ret not used
 168  * x86-64: objc_msgSend_fp2ret used for `_Complex long double`.
 169  *
 170  * These functions must be cast to an appropriate function pointer type
 171  * before being called.
 172  */
 173 #if !OBJC_OLD_DISPATCH_PROTOTYPES
 174 #pragma clang diagnostic push
 175 #pragma clang diagnostic ignored "-Wincompatible-library-redeclaration"
 176
 177 # if defined(__i386__)
 178
 179 OBJC_EXPORT void
 180 objc_msgSend_fpret(void /* id self, SEL op, ... */ )
 181     OBJC_AVAILABLE(10.4, 2.0, 9.0, 1.0, 2.0);
 182
 183 # elif defined(__x86_64__)
 184
 185 OBJC_EXPORT void
 186 objc_msgSend_fpret(void /* id self, SEL op, ... */ )
 187     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 188
 189 OBJC_EXPORT void
 190 objc_msgSend_fp2ret(void /* id self, SEL op, ... */ )
 191     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 192
 193 #pragma clang diagnostic pop
 194 # endif
 195
 196 // !OBJC_OLD_DISPATCH_PROTOTYPES
 197 #else
 198 // OBJC_OLD_DISPATCH_PROTOTYPES
 199 # if defined(__i386__)
 200
 201 /**
 202  * Sends a message with a floating-point return value to an instance of a class.
 203  *
 204  * @see objc_msgSend
 205  * @note On the i386 platform, the ABI for functions returning a floating-point value is
 206  *  incompatible with that for functions returning an integral type. On the i386 platform, therefore,
 207  *  you must use \c objc_msgSend_fpret for functions returning non-integral type. For \c float or
 208  *  \c long \c double return types, cast the function to an appropriate function pointer type first.
 209  */
 210 #pragma clang diagnostic push
 211 #pragma clang diagnostic ignored "-Wincompatible-library-redeclaration"
 212 OBJC_EXPORT double
 213 objc_msgSend_fpret(id _Nullable self, SEL _Nonnull op, ...)
 214     OBJC_AVAILABLE(10.4, 2.0, 9.0, 1.0, 2.0);
 215 #pragma clang diagnostic pop
 216
 217 /* Use objc_msgSendSuper() for fp-returning messages to super. */
 218 /* See also objc_msgSendv_fpret() below. */
 219
 220 # elif defined(__x86_64__)
 221 /**
 222  * Sends a message with a floating-point return value to an instance of a class.
 223  *
 224  * @see objc_msgSend
 225  */
 226 OBJC_EXPORT long double
 227 objc_msgSend_fpret(id _Nullable self, SEL _Nonnull op, ...)
 228     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 229
 230 #  if __STDC_VERSION__ >= 199901L
 231 OBJC_EXPORT _Complex long double
 232 objc_msgSend_fp2ret(id _Nullable self, SEL _Nonnull op, ...)
 233     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 234 #  else
 235 OBJC_EXPORT void objc_msgSend_fp2ret(id _Nullable self, SEL _Nonnull op, ...)
 236     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 237 #  endif
 238
 239 /* Use objc_msgSendSuper() for fp-returning messages to super. */
 240 /* See also objc_msgSendv_fpret() below. */
 241
 242 # endif
 243
 244 // OBJC_OLD_DISPATCH_PROTOTYPES
 245 #endif
 246
 247
 248 /* Direct Method Invocation Primitives
 249  * Use these functions to call the implementation of a given Method.
 250  * This is faster than calling method_getImplementation() and method_getName().
 251  *
 252  * The receiver must not be nil.
 253  *
 254  * These functions must be cast to an appropriate function pointer type
 255  * before being called.
 256  */
 257 #if !OBJC_OLD_DISPATCH_PROTOTYPES
 258 #pragma clang diagnostic push
 259 #pragma clang diagnostic ignored "-Wincompatible-library-redeclaration"
 260 OBJC_EXPORT void
 261 method_invoke(void /* id receiver, Method m, ... */ )
 262     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 263
 264 OBJC_EXPORT void
 265 method_invoke_stret(void /* id receiver, Method m, ... */ )
 266     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0)
 267     OBJC_ARM64_UNAVAILABLE;
 268 #pragma clang diagnostic pop
 269 #else
 270 OBJC_EXPORT id _Nullable
 271 method_invoke(id _Nullable receiver, Method _Nonnull m, ...)
 272     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 273
 274 OBJC_EXPORT void
 275 method_invoke_stret(id _Nullable receiver, Method _Nonnull m, ...)
 276     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0)
 277     OBJC_ARM64_UNAVAILABLE;
 278 #endif
 279
 280
 281 /* Message Forwarding Primitives
 282  * Use these functions to forward a message as if the receiver did not
 283  * respond to it.
 284  *
 285  * The receiver must not be nil.
 286  *
 287  * class_getMethodImplementation() may return (IMP)_objc_msgForward.
 288  * class_getMethodImplementation_stret() may return (IMP)_objc_msgForward_stret
 289  *
 290  * These functions must be cast to an appropriate function pointer type
 291  * before being called.
 292  *
 293  * Before Mac OS X 10.6, _objc_msgForward must not be called directly
 294  * but may be compared to other IMP values.
 295  */
 296 #if !OBJC_OLD_DISPATCH_PROTOTYPES
 297 #pragma clang diagnostic push
 298 #pragma clang diagnostic ignored "-Wincompatible-library-redeclaration"
 299 OBJC_EXPORT void
 300 _objc_msgForward(void /* id receiver, SEL sel, ... */ )
 301     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 302
 303 OBJC_EXPORT void
 304 _objc_msgForward_stret(void /* id receiver, SEL sel, ... */ )
 305     OBJC_AVAILABLE(10.6, 3.0, 9.0, 1.0, 2.0)
 306     OBJC_ARM64_UNAVAILABLE;
 307 #pragma clang diagnostic pop
 308 #else
 309 OBJC_EXPORT id _Nullable
 310 _objc_msgForward(id _Nonnull receiver, SEL _Nonnull sel, ...)
 311     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 312
 313 OBJC_EXPORT void
 314 _objc_msgForward_stret(id _Nonnull receiver, SEL _Nonnull sel, ...)
 315     OBJC_AVAILABLE(10.6, 3.0, 9.0, 1.0, 2.0)
 316     OBJC_ARM64_UNAVAILABLE;
 317 #endif
 318
 319
 320 /* Variable-argument Messaging Primitives
 321  *
 322  * Use these functions to call methods with a list of arguments, such
 323  * as the one passed to forward:: .
 324  *
 325  * The contents of the argument list are architecture-specific.
 326  * Consult your local function call ABI documentation for details.
 327  *
 328  * These functions must be cast to an appropriate function pointer type
 329  * before being called, except for objc_msgSendv_stret() which must not
 330  * be cast to a struct-returning type.
 331  */
 332
 333 typedef void* marg_list;
 334
 335 OBJC_EXPORT id _Nullable
 336 objc_msgSendv(id _Nullable self, SEL _Nonnull op, size_t arg_size,
 337               marg_list _Nonnull arg_frame)
 338     OBJC2_UNAVAILABLE;
 339
 340 OBJC_EXPORT void
 341 objc_msgSendv_stret(void * _Nonnull stretAddr, id _Nullable self,
 342                     SEL _Nonnull op, size_t arg_size,
 343                     marg_list _Nullable arg_frame)
 344     OBJC2_UNAVAILABLE;
 345 /* Note that objc_msgSendv_stret() does not return a structure type,
 346  * and should not be cast to do so. This is unlike objc_msgSend_stret()
 347  * and objc_msgSendSuper_stret().
 348  */
 349 #if defined(__i386__)
 350 OBJC_EXPORT double
 351 objc_msgSendv_fpret(id _Nullable self, SEL _Nonnull op,
 352                     unsigned arg_size, marg_list _Nullable arg_frame)
 353     OBJC2_UNAVAILABLE;
 354 #endif
 355
 356
 357 /* The following marg_list macros are of marginal utility. They
 358  * are included for compatibility with the old objc-class.h header. */
 359
 360 #if !__OBJC2__
 361
 362 #define marg_prearg_size        0
 363
 364 #define marg_malloc(margs, method) \
 365         do { \
 366                 margs = (marg_list *)malloc (marg_prearg_size + ((7 + method_getSizeOfArguments(method)) & ~7)); \
 367         } while (0)
 368
 369 #define marg_free(margs) \
 370         do { \
 371                 free(margs); \
 372         } while (0)
 373
 374 #define marg_adjustedOffset(method, offset) \
 375         (marg_prearg_size + offset)
 376
 377 #define marg_getRef(margs, offset, type) \
 378         ( (type *)((char *)margs + marg_adjustedOffset(method,offset) ) )
 379
 380 #define marg_getValue(margs, offset, type) \
 381         ( *marg_getRef(margs, offset, type) )
 382
 383 #define marg_setValue(margs, offset, type, value) \
 384         ( marg_getValue(margs, offset, type) = (value) )
 385
 386 #endif
 387
 388 #endif