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