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 OBJC_EXPORT double
 202 objc_msgSend_fpret(id _Nullable self, SEL _Nonnull op, ...)
 203     OBJC_AVAILABLE(10.4, 2.0, 9.0, 1.0, 2.0);
 204
 205 /* Use objc_msgSendSuper() for fp-returning messages to super. */
 206 /* See also objc_msgSendv_fpret() below. */
 207
 208 # elif defined(__x86_64__)
 209 /**
 210  * Sends a message with a floating-point return value to an instance of a class.
 211  *
 212  * @see objc_msgSend
 213  */
 214 OBJC_EXPORT long double
 215 objc_msgSend_fpret(id _Nullable self, SEL _Nonnull op, ...)
 216     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 217
 218 #  if __STDC_VERSION__ >= 199901L
 219 OBJC_EXPORT _Complex long double
 220 objc_msgSend_fp2ret(id _Nullable self, SEL _Nonnull op, ...)
 221     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 222 #  else
 223 OBJC_EXPORT void objc_msgSend_fp2ret(id _Nullable self, SEL _Nonnull op, ...)
 224     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 225 #  endif
 226
 227 /* Use objc_msgSendSuper() for fp-returning messages to super. */
 228 /* See also objc_msgSendv_fpret() below. */
 229
 230 # endif
 231
 232 // OBJC_OLD_DISPATCH_PROTOTYPES
 233 #endif
 234
 235
 236 /* Direct Method Invocation Primitives
 237  * Use these functions to call the implementation of a given Method.
 238  * This is faster than calling method_getImplementation() and method_getName().
 239  *
 240  * The receiver must not be nil.
 241  *
 242  * These functions must be cast to an appropriate function pointer type
 243  * before being called.
 244  */
 245 #if !OBJC_OLD_DISPATCH_PROTOTYPES
 246 OBJC_EXPORT void
 247 method_invoke(void /* id receiver, Method m, ... */ )
 248     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 249
 250 OBJC_EXPORT void
 251 method_invoke_stret(void /* id receiver, Method m, ... */ )
 252     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0)
 253     OBJC_ARM64_UNAVAILABLE;
 254 #else
 255 OBJC_EXPORT id _Nullable
 256 method_invoke(id _Nullable receiver, Method _Nonnull m, ...)
 257     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0);
 258
 259 OBJC_EXPORT void
 260 method_invoke_stret(id _Nullable receiver, Method _Nonnull m, ...)
 261     OBJC_AVAILABLE(10.5, 2.0, 9.0, 1.0, 2.0)
 262     OBJC_ARM64_UNAVAILABLE;
 263 #endif
 264
 265
 266 /* Message Forwarding Primitives
 267  * Use these functions to forward a message as if the receiver did not
 268  * respond to it.
 269  *
 270  * The receiver must not be nil.
 271  *
 272  * class_getMethodImplementation() may return (IMP)_objc_msgForward.
 273  * class_getMethodImplementation_stret() may return (IMP)_objc_msgForward_stret
 274  *
 275  * These functions must be cast to an appropriate function pointer type
 276  * before being called.
 277  *
 278  * Before Mac OS X 10.6, _objc_msgForward must not be called directly
 279  * but may be compared to other IMP values.
 280  */
 281 #if !OBJC_OLD_DISPATCH_PROTOTYPES
 282 OBJC_EXPORT void
 283 _objc_msgForward(void /* id receiver, SEL sel, ... */ )
 284     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 285
 286 OBJC_EXPORT void
 287 _objc_msgForward_stret(void /* id receiver, SEL sel, ... */ )
 288     OBJC_AVAILABLE(10.6, 3.0, 9.0, 1.0, 2.0)
 289     OBJC_ARM64_UNAVAILABLE;
 290 #else
 291 OBJC_EXPORT id _Nullable
 292 _objc_msgForward(id _Nonnull receiver, SEL _Nonnull sel, ...)
 293     OBJC_AVAILABLE(10.0, 2.0, 9.0, 1.0, 2.0);
 294
 295 OBJC_EXPORT void
 296 _objc_msgForward_stret(id _Nonnull receiver, SEL _Nonnull sel, ...)
 297     OBJC_AVAILABLE(10.6, 3.0, 9.0, 1.0, 2.0)
 298     OBJC_ARM64_UNAVAILABLE;
 299 #endif
 300
 301
 302 /* Variable-argument Messaging Primitives
 303  *
 304  * Use these functions to call methods with a list of arguments, such
 305  * as the one passed to forward:: .
 306  *
 307  * The contents of the argument list are architecture-specific.
 308  * Consult your local function call ABI documentation for details.
 309  *
 310  * These functions must be cast to an appropriate function pointer type
 311  * before being called, except for objc_msgSendv_stret() which must not
 312  * be cast to a struct-returning type.
 313  */
 314
 315 typedef void* marg_list;
 316
 317 OBJC_EXPORT id _Nullable
 318 objc_msgSendv(id _Nullable self, SEL _Nonnull op, size_t arg_size,
 319               marg_list _Nonnull arg_frame)
 320     OBJC2_UNAVAILABLE;
 321
 322 OBJC_EXPORT void
 323 objc_msgSendv_stret(void * _Nonnull stretAddr, id _Nullable self,
 324                     SEL _Nonnull op, size_t arg_size,
 325                     marg_list _Nullable arg_frame)
 326     OBJC2_UNAVAILABLE;
 327 /* Note that objc_msgSendv_stret() does not return a structure type,
 328  * and should not be cast to do so. This is unlike objc_msgSend_stret()
 329  * and objc_msgSendSuper_stret().
 330  */
 331 #if defined(__i386__)
 332 OBJC_EXPORT double
 333 objc_msgSendv_fpret(id _Nullable self, SEL _Nonnull op,
 334                     unsigned arg_size, marg_list _Nullable arg_frame)
 335     OBJC2_UNAVAILABLE;
 336 #endif
 337
 338
 339 /* The following marg_list macros are of marginal utility. They
 340  * are included for compatibility with the old objc-class.h header. */
 341
 342 #if !__OBJC2__
 343
 344 #define marg_prearg_size        0
 345
 346 #define marg_malloc(margs, method) \
 347         do { \
 348                 margs = (marg_list *)malloc (marg_prearg_size + ((7 + method_getSizeOfArguments(method)) & ~7)); \
 349         } while (0)
 350
 351 #define marg_free(margs) \
 352         do { \
 353                 free(margs); \
 354         } while (0)
 355
 356 #define marg_adjustedOffset(method, offset) \
 357         (marg_prearg_size + offset)
 358
 359 #define marg_getRef(margs, offset, type) \
 360         ( (type *)((char *)margs + marg_adjustedOffset(method,offset) ) )
 361
 362 #define marg_getValue(margs, offset, type) \
 363         ( *marg_getRef(margs, offset, type) )
 364
 365 #define marg_setValue(margs, offset, type, value) \
 366         ( marg_getValue(margs, offset, type) = (value) )
 367
 368 #endif
 369
 370 #endif