1<html lang="en"> 2<head> 3<title>Forwarding hook - Using the GNU Compiler Collection (GCC)</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Using the GNU Compiler Collection (GCC)"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Messaging-with-the-GNU-Objective_002dC-runtime.html#Messaging-with-the-GNU-Objective_002dC-runtime" title="Messaging with the GNU Objective-C runtime"> 9<link rel="prev" href="Dynamically-registering-methods.html#Dynamically-registering-methods" title="Dynamically registering methods"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12Copyright (C) 1988, 1989, 1992, 1993, 1994, 1995, 1996, 1997, 131998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 142010 Free Software Foundation, Inc. 15 16Permission is granted to copy, distribute and/or modify this document 17under the terms of the GNU Free Documentation License, Version 1.3 or 18any later version published by the Free Software Foundation; with the 19Invariant Sections being ``Funding Free Software'', the Front-Cover 20Texts being (a) (see below), and with the Back-Cover Texts being (b) 21(see below). A copy of the license is included in the section entitled 22``GNU Free Documentation License''. 23 24(a) The FSF's Front-Cover Text is: 25 26 A GNU Manual 27 28(b) The FSF's Back-Cover Text is: 29 30 You have freedom to copy and modify this GNU Manual, like GNU 31 software. Copies published by the Free Software Foundation raise 32 funds for GNU development.--> 33<meta http-equiv="Content-Style-Type" content="text/css"> 34<style type="text/css"><!-- 35 pre.display { font-family:inherit } 36 pre.format { font-family:inherit } 37 pre.smalldisplay { font-family:inherit; font-size:smaller } 38 pre.smallformat { font-family:inherit; font-size:smaller } 39 pre.smallexample { font-size:smaller } 40 pre.smalllisp { font-size:smaller } 41 span.sc { font-variant:small-caps } 42 span.roman { font-family:serif; font-weight:normal; } 43 span.sansserif { font-family:sans-serif; font-weight:normal; } 44--></style> 45<link rel="stylesheet" type="text/css" href="../cs.css"> 46</head> 47<body> 48<div class="node"> 49<a name="Forwarding-hook"></a> 50<p> 51Previous: <a rel="previous" accesskey="p" href="Dynamically-registering-methods.html#Dynamically-registering-methods">Dynamically registering methods</a>, 52Up: <a rel="up" accesskey="u" href="Messaging-with-the-GNU-Objective_002dC-runtime.html#Messaging-with-the-GNU-Objective_002dC-runtime">Messaging with the GNU Objective-C runtime</a> 53<hr> 54</div> 55 56<h4 class="subsection">8.10.2 Forwarding hook</h4> 57 58<p>The GNU Objective-C runtime provides a hook, called 59<code>__objc_msg_forward2</code>, which is called by 60<code>objc_msg_lookup()</code> when it can't find a method implementation in 61the runtime tables and after calling <code>+resolveInstanceMethod:</code> 62and <code>+resolveClassMethod:</code> has been attempted and did not succeed 63in dynamically registering the method. 64 65 <p>To configure the hook, you set the global variable 66<code>__objc_msg_foward2</code> to a function with the same argument and 67return types of <code>objc_msg_lookup()</code>. When 68<code>objc_msg_lookup()</code> can not find a method implementation, it 69invokes the hook function you provided to get a method implementation 70to return. So, in practice <code>__objc_msg_forward2</code> allows you to 71extend <code>objc_msg_lookup()</code> by adding some custom code that is 72called to do a further lookup when no standard method implementation 73can be found using the normal lookup. 74 75 <p>This hook is generally reserved for “Foundation” libraries such as 76GNUstep Base, which use it to implement their high-level method 77forwarding API, typically based around the <code>forwardInvocation:</code> 78method. So, unless you are implementing your own “Foundation” 79library, you should not set this hook. 80 81 <p>In a typical forwarding implementation, the <code>__objc_msg_forward2</code> 82hook function determines the argument and return type of the method 83that is being looked up, and then creates a function that takes these 84arguments and has that return type, and returns it to the caller. 85Creating this function is non-trivial and is typically performed using 86a dedicated library such as <code>libffi</code>. 87 88 <p>The forwarding method implementation thus created is returned by 89<code>objc_msg_lookup()</code> and is executed as if it was a normal method 90implementation. When the forwarding method implementation is called, 91it is usually expected to pack all arguments into some sort of object 92(typically, an <code>NSInvocation</code> in a “Foundation” library), and 93hand it over to the programmer (<code>forwardInvocation:</code>) who is then 94allowed to manipulate the method invocation using a high-level API 95provided by the “Foundation” library. For example, the programmer 96may want to examine the method invocation arguments and name and 97potentially change them before forwarding the method invocation to one 98or more local objects (<code>performInvocation:</code>) or even to remote 99objects (by using Distributed Objects or some other mechanism). When 100all this completes, the return value is passed back and must be 101returned correctly to the original caller. 102 103 <p>Note that the GNU Objective-C runtime currently provides no support 104for method forwarding or method invocations other than the 105<code>__objc_msg_forward2</code> hook. 106 107 <p>If the forwarding hook does not exist or returns <code>NULL</code>, the 108runtime currently attempts forwarding using an older, deprecated API, 109and if that fails, it aborts the program. In future versions of the 110GNU Objective-C runtime, the runtime will immediately abort. 111 112<!-- Copyright (C) 2002, 2004 Free Software Foundation, Inc. --> 113<!-- This is part of the GCC manual. --> 114<!-- For copying conditions, see the file gcc.texi. --> 115 </body></html> 116 117