libobjc/objc/message.h

   1 /* GNU Objective C Runtime messaging declarations
   2    Copyright (C) 1993, 1995, 1996, 2004, 2009,
   3    2010 Free Software Foundation, Inc.
   4
   5 This file is part of GCC.
   6
   7 GCC is free software; you can redistribute it and/or modify
   8 it under the terms of the GNU General Public License as published by
   9 the Free Software Foundation; either version 3, or (at your option)
  10 any later version.
  11
  12 GCC is distributed in the hope that it will be useful,
  13 but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 GNU General Public License for more details.
  16
  17 Under Section 7 of GPL version 3, you are granted additional
  18 permissions described in the GCC Runtime Library Exception, version
  19 3.1, as published by the Free Software Foundation.
  20
  21 You should have received a copy of the GNU General Public License and
  22 a copy of the GCC Runtime Library Exception along with this program;
  23 see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
  24 <http://www.gnu.org/licenses/>.  */
  25
  26 #ifndef __objc_message_INCLUDE_GNU
  27 #define __objc_message_INCLUDE_GNU
  28
  29 #include "objc.h"
  30 #include "objc-decls.h"
  31
  32 #ifdef __cplusplus
  33 extern "C" {
  34 #endif
  35
  36 /* This file includes declarations of the messaging functions and
  37    types.  */
  38
  39 /* Compatibility note: the messaging function is one area where the
  40    GNU runtime and the Apple/NeXT runtime differ significantly.  If
  41    you can, it is recommended that you use higher-level facilities
  42    (provided by a Foundation library such as GNUstep Base) to perform
  43    forwarding or other advanced messaging tricks.  */
  44
  45 /* This function returns the IMP (C function implementing a method) to
  46    use to invoke the method with selector 'op' of receiver 'receiver'.
  47
  48    This is the function used by the compiler when compiling method
  49    invocations with the GNU runtime.  For example, the method call
  50
  51      result = [receiver method];
  52
  53    is compiled by the compiler (with the GNU runtime) into the
  54    equivalent of:
  55
  56    {
  57      IMP function = objc_msg_lookup (receiver, @selector (method));
  58      result = function (receiver, @selector (method));
  59    }
  60
  61    so, a call to objc_msg_lookup() determines the IMP (the C function
  62    implementing the method) to call.  Then, the function is called.
  63    If the method takes or returns different arguments, the compiler
  64    will cast 'function' to the right type before invoking it, making
  65    sure arguments and return value are handled correctly.
  66
  67    objc_msg_lookup() must always return a valid function that can be
  68    called with the required method signature (otherwise the
  69    compiler-generated code shown above could segfault).  If 'receiver'
  70    is NULL, objc_msg_lookup() returns a C function that does nothing,
  71    ignores all its arguments, and returns NULL (see nil_method.c).  If
  72    'receiver' does not respond to the selector 'op', objc_msg_lookup()
  73    will try to call +resolveClassMethod: or resolveInstanceMethod: as
  74    appropriate, and if they return YES, it will try the lookup again
  75    (+resolveClassMethod: and +resolveInstanceMethod: can thus install
  76    dynamically methods as they are requested).  If
  77    +resolveClassMethod: or +resolveInstanceMethod: are either not
  78    available, or return NO, or return YES but 'receiver' still doesn't
  79    implement the 'selector' after calling them, the runtime returns a
  80    generic "forwarding" function that can be called with the required
  81    method signature and which can process the method invocation
  82    according to the forwarding API.  There are two runtime hooks that
  83    allow Foundation libraries (such as GNUstep-Base) to return their
  84    own forwarding function in preference to the runtime ones.  When
  85    that happens, the Foundation library effectively takes complete
  86    control of the forwarding process; any method invocation where the
  87    selector is not implemented by the receiver will end up calling a
  88    forwarding function chosen by the Foundation library.  */
  89 objc_EXPORT IMP objc_msg_lookup (id receiver, SEL op);
  90
  91 /* Structure used when a message is send to a class's super class.
  92    The compiler generates one of these structures and passes it to
  93    objc_msg_lookup_super() when a [super method] call is compiled.  */
  94 typedef struct objc_super
  95 {
  96   id    self;       /* Id of the object sending the message. */
  97
  98   /* The new version of the API will always use 'super_class'.  TODO:
  99      Use class only if objc-api.h is included, otherwise always use
 100      super_class.  */
 101 #ifdef __cplusplus
 102   Class super_class;
 103 #else
 104   Class class;        /* Object's super class. */
 105 #endif
 106 } Super, *Super_t;
 107
 108 /* This is used by the compiler instead of objc_msg_lookup () when
 109    compiling a call to 'super', such as [super method].  This requires
 110    sending a message to super->self, but looking up the method as if
 111    super->self was in class super->super_class.  */
 112 objc_EXPORT IMP objc_msg_lookup_super (Super_t super, SEL sel);
 113
 114 /* Hooks for method forwarding.  They make it easy to substitute the
 115    built-in forwarding with one based on a library, such as ffi, that
 116    implement closures, thereby avoiding gcc's __builtin_apply
 117    problems.  __objc_msg_forward2's result will be preferred over that
 118    of __objc_msg_forward if both are set and return non-NULL.
 119
 120    TODO: The API should define objc_set_msg_forward_handler () or
 121    similar instead of these hooks.  */
 122 objc_EXPORT IMP (*__objc_msg_forward)(SEL);
 123 objc_EXPORT IMP (*__objc_msg_forward2)(id, SEL);
 124
 125
 126 /* The following types and functions are provided only for
 127    backwards-compatibility and should not be used in new code.  They
 128    were deprecated in GCC 4.6 and will be removed in the next
 129    release.  */
 130 typedef void* retval_t;         /* return value */
 131 typedef void(*apply_t)(void);   /* function pointer */
 132 typedef union arglist {
 133   char *arg_ptr;
 134   char arg_regs[sizeof (char*)];
 135 } *arglist_t;                   /* argument frame */
 136
 137 objc_EXPORT retval_t objc_msg_sendv(id, SEL, arglist_t);
 138
 139 #ifdef __cplusplus
 140 }
 141 #endif
 142
 143 #endif /* not __objc_message_INCLUDE_GNU */