aarch64-linux-gnu-4.9/share/doc/gcc/Forwarding-hook.html - toolchains/linux-x86/gcc - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
 <html>
 <!-- Copyright (C) 1988-2015 Free Software Foundation, Inc.

 Permission is granted to copy, distribute and/or modify this document
 under the terms of the GNU Free Documentation License, Version 1.3 or
 any later version published by the Free Software Foundation; with the
 Invariant Sections being "Funding Free Software", the Front-Cover
 Texts being (a) (see below), and with the Back-Cover Texts being (b)
 (see below).  A copy of the license is included in the section entitled
 "GNU Free Documentation License".

 (a) The FSF's Front-Cover Text is:

 A GNU Manual

 (b) The FSF's Back-Cover Text is:

 You have freedom to copy and modify this GNU Manual, like GNU
      software.  Copies published by the Free Software Foundation raise
      funds for GNU development. -->
 <!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
 <head>
 <title>Using the GNU Compiler Collection (GCC): Forwarding hook</title>

 <meta name="description" content="Using the GNU Compiler Collection (GCC): Forwarding hook">
 <meta name="keywords" content="Using the GNU Compiler Collection (GCC): Forwarding hook">
 <meta name="resource-type" content="document">
 <meta name="distribution" content="global">
 <meta name="Generator" content="makeinfo">
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <link href="index.html#Top" rel="start" title="Top">
 <link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
 <link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
 <link href="Messaging-with-the-GNU-Objective_002dC-runtime.html#Messaging-with-the-GNU-Objective_002dC-runtime" rel="up" title="Messaging with the GNU Objective-C runtime">
 <link href="Compatibility.html#Compatibility" rel="next" title="Compatibility">
 <link href="Dynamically-registering-methods.html#Dynamically-registering-methods" rel="prev" title="Dynamically registering methods">
 <style type="text/css">
 <!--
 a.summary-letter {text-decoration: none}
 blockquote.smallquotation {font-size: smaller}
 div.display {margin-left: 3.2em}
 div.example {margin-left: 3.2em}
 div.indentedblock {margin-left: 3.2em}
 div.lisp {margin-left: 3.2em}
 div.smalldisplay {margin-left: 3.2em}
 div.smallexample {margin-left: 3.2em}
 div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
 div.smalllisp {margin-left: 3.2em}
 kbd {font-style:oblique}
 pre.display {font-family: inherit}
 pre.format {font-family: inherit}
 pre.menu-comment {font-family: serif}
 pre.menu-preformatted {font-family: serif}
 pre.smalldisplay {font-family: inherit; font-size: smaller}
 pre.smallexample {font-size: smaller}
 pre.smallformat {font-family: inherit; font-size: smaller}
 pre.smalllisp {font-size: smaller}
 span.nocodebreak {white-space:nowrap}
 span.nolinebreak {white-space:nowrap}
 span.roman {font-family:serif; font-weight:normal}
 span.sansserif {font-family:sans-serif; font-weight:normal}
 ul.no-bullet {list-style: none}
 -->
 </style>


 </head>

 <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
 <a name="Forwarding-hook"></a>
 <div class="header">
 <p>
 Previous: <a href="Dynamically-registering-methods.html#Dynamically-registering-methods" accesskey="p" rel="prev">Dynamically registering methods</a>, Up: <a href="Messaging-with-the-GNU-Objective_002dC-runtime.html#Messaging-with-the-GNU-Objective_002dC-runtime" accesskey="u" rel="up">Messaging with the GNU Objective-C runtime</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
 </div>
 <hr>
 <a name="Forwarding-hook-1"></a>
 <h4 class="subsection">8.10.2 Forwarding hook</h4>

 <p>The GNU Objective-C runtime provides a hook, called
 <code>__objc_msg_forward2</code>, which is called by
 <code>objc_msg_lookup()</code> when it can&rsquo;t find a method implementation in
 the runtime tables and after calling <code>+resolveInstanceMethod:</code>
 and <code>+resolveClassMethod:</code> has been attempted and did not succeed
 in dynamically registering the method.
 </p>
 <p>To configure the hook, you set the global variable
 <code>__objc_msg_forward2</code> to a function with the same argument and
 return types of <code>objc_msg_lookup()</code>.  When
 <code>objc_msg_lookup()</code> can not find a method implementation, it
 invokes the hook function you provided to get a method implementation
 to return.  So, in practice <code>__objc_msg_forward2</code> allows you to
 extend <code>objc_msg_lookup()</code> by adding some custom code that is
 called to do a further lookup when no standard method implementation
 can be found using the normal lookup.
 </p>
 <p>This hook is generally reserved for &ldquo;Foundation&rdquo; libraries such as
 GNUstep Base, which use it to implement their high-level method
 forwarding API, typically based around the <code>forwardInvocation:</code>
 method.  So, unless you are implementing your own &ldquo;Foundation&rdquo;
 library, you should not set this hook.
 </p>
 <p>In a typical forwarding implementation, the <code>__objc_msg_forward2</code>
 hook function determines the argument and return type of the method
 that is being looked up, and then creates a function that takes these
 arguments and has that return type, and returns it to the caller.
 Creating this function is non-trivial and is typically performed using
 a dedicated library such as <code>libffi</code>.
 </p>
 <p>The forwarding method implementation thus created is returned by
 <code>objc_msg_lookup()</code> and is executed as if it was a normal method
 implementation.  When the forwarding method implementation is called,
 it is usually expected to pack all arguments into some sort of object
 (typically, an <code>NSInvocation</code> in a &ldquo;Foundation&rdquo; library), and
 hand it over to the programmer (<code>forwardInvocation:</code>) who is then
 allowed to manipulate the method invocation using a high-level API
 provided by the &ldquo;Foundation&rdquo; library.  For example, the programmer
 may want to examine the method invocation arguments and name and
 potentially change them before forwarding the method invocation to one
 or more local objects (<code>performInvocation:</code>) or even to remote
 objects (by using Distributed Objects or some other mechanism).  When
 all this completes, the return value is passed back and must be
 returned correctly to the original caller.
 </p>
 <p>Note that the GNU Objective-C runtime currently provides no support
 for method forwarding or method invocations other than the
 <code>__objc_msg_forward2</code> hook.
 </p>
 <p>If the forwarding hook does not exist or returns <code>NULL</code>, the
 runtime currently attempts forwarding using an older, deprecated API,
 and if that fails, it aborts the program.  In future versions of the
 GNU Objective-C runtime, the runtime will immediately abort.
 </p>
 <hr>
 <div class="header">
 <p>
 Previous: <a href="Dynamically-registering-methods.html#Dynamically-registering-methods" accesskey="p" rel="prev">Dynamically registering methods</a>, Up: <a href="Messaging-with-the-GNU-Objective_002dC-runtime.html#Messaging-with-the-GNU-Objective_002dC-runtime" accesskey="u" rel="up">Messaging with the GNU Objective-C runtime</a> &nbsp; [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
 </div>


 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
	<html>
	<!-- Copyright (C) 1988-2015 Free Software Foundation, Inc.

	Permission is granted to copy, distribute and/or modify this document
	under the terms of the GNU Free Documentation License, Version 1.3 or
	any later version published by the Free Software Foundation; with the
	Invariant Sections being "Funding Free Software", the Front-Cover
	Texts being (a) (see below), and with the Back-Cover Texts being (b)
	(see below). A copy of the license is included in the section entitled
	"GNU Free Documentation License".

	(a) The FSF's Front-Cover Text is:

	A GNU Manual

	(b) The FSF's Back-Cover Text is:

	You have freedom to copy and modify this GNU Manual, like GNU
	software. Copies published by the Free Software Foundation raise
	funds for GNU development. -->
	<!-- Created by GNU Texinfo 5.2, http://www.gnu.org/software/texinfo/ -->
	<head>
	<title>Using the GNU Compiler Collection (GCC): Forwarding hook</title>

	<meta name="description" content="Using the GNU Compiler Collection (GCC): Forwarding hook">
	<meta name="keywords" content="Using the GNU Compiler Collection (GCC): Forwarding hook">
	<meta name="resource-type" content="document">
	<meta name="distribution" content="global">
	<meta name="Generator" content="makeinfo">
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<link href="index.html#Top" rel="start" title="Top">
	<link href="Option-Index.html#Option-Index" rel="index" title="Option Index">
	<link href="index.html#SEC_Contents" rel="contents" title="Table of Contents">
	<link href="Messaging-with-the-GNU-Objective_002dC-runtime.html#Messaging-with-the-GNU-Objective_002dC-runtime" rel="up" title="Messaging with the GNU Objective-C runtime">
	<link href="Compatibility.html#Compatibility" rel="next" title="Compatibility">
	<link href="Dynamically-registering-methods.html#Dynamically-registering-methods" rel="prev" title="Dynamically registering methods">
	<style type="text/css">
	<!--
	a.summary-letter {text-decoration: none}
	blockquote.smallquotation {font-size: smaller}
	div.display {margin-left: 3.2em}
	div.example {margin-left: 3.2em}
	div.indentedblock {margin-left: 3.2em}
	div.lisp {margin-left: 3.2em}
	div.smalldisplay {margin-left: 3.2em}
	div.smallexample {margin-left: 3.2em}
	div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
	div.smalllisp {margin-left: 3.2em}
	kbd {font-style:oblique}
	pre.display {font-family: inherit}
	pre.format {font-family: inherit}
	pre.menu-comment {font-family: serif}
	pre.menu-preformatted {font-family: serif}
	pre.smalldisplay {font-family: inherit; font-size: smaller}
	pre.smallexample {font-size: smaller}
	pre.smallformat {font-family: inherit; font-size: smaller}
	pre.smalllisp {font-size: smaller}
	span.nocodebreak {white-space:nowrap}
	span.nolinebreak {white-space:nowrap}
	span.roman {font-family:serif; font-weight:normal}
	span.sansserif {font-family:sans-serif; font-weight:normal}
	ul.no-bullet {list-style: none}
	-->
	</style>


	</head>

	<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
	<a name="Forwarding-hook"></a>
	<div class="header">
	<p>
	Previous: <a href="Dynamically-registering-methods.html#Dynamically-registering-methods" accesskey="p" rel="prev">Dynamically registering methods</a>, Up: <a href="Messaging-with-the-GNU-Objective_002dC-runtime.html#Messaging-with-the-GNU-Objective_002dC-runtime" accesskey="u" rel="up">Messaging with the GNU Objective-C runtime</a>   [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
	</div>
	<hr>
	<a name="Forwarding-hook-1"></a>
	<h4 class="subsection">8.10.2 Forwarding hook</h4>

	<p>The GNU Objective-C runtime provides a hook, called
	<code>__objc_msg_forward2</code>, which is called by
	<code>objc_msg_lookup()</code> when it can’t find a method implementation in
	the runtime tables and after calling <code>+resolveInstanceMethod:</code>
	and <code>+resolveClassMethod:</code> has been attempted and did not succeed
	in dynamically registering the method.
	</p>
	<p>To configure the hook, you set the global variable
	<code>__objc_msg_forward2</code> to a function with the same argument and
	return types of <code>objc_msg_lookup()</code>. When
	<code>objc_msg_lookup()</code> can not find a method implementation, it
	invokes the hook function you provided to get a method implementation
	to return. So, in practice <code>__objc_msg_forward2</code> allows you to
	extend <code>objc_msg_lookup()</code> by adding some custom code that is
	called to do a further lookup when no standard method implementation
	can be found using the normal lookup.
	</p>
	<p>This hook is generally reserved for “Foundation” libraries such as
	GNUstep Base, which use it to implement their high-level method
	forwarding API, typically based around the <code>forwardInvocation:</code>
	method. So, unless you are implementing your own “Foundation”
	library, you should not set this hook.
	</p>
	<p>In a typical forwarding implementation, the <code>__objc_msg_forward2</code>
	hook function determines the argument and return type of the method
	that is being looked up, and then creates a function that takes these
	arguments and has that return type, and returns it to the caller.
	Creating this function is non-trivial and is typically performed using
	a dedicated library such as <code>libffi</code>.
	</p>
	<p>The forwarding method implementation thus created is returned by
	<code>objc_msg_lookup()</code> and is executed as if it was a normal method
	implementation. When the forwarding method implementation is called,
	it is usually expected to pack all arguments into some sort of object
	(typically, an <code>NSInvocation</code> in a “Foundation” library), and
	hand it over to the programmer (<code>forwardInvocation:</code>) who is then
	allowed to manipulate the method invocation using a high-level API
	provided by the “Foundation” library. For example, the programmer
	may want to examine the method invocation arguments and name and
	potentially change them before forwarding the method invocation to one
	or more local objects (<code>performInvocation:</code>) or even to remote
	objects (by using Distributed Objects or some other mechanism). When
	all this completes, the return value is passed back and must be
	returned correctly to the original caller.
	</p>
	<p>Note that the GNU Objective-C runtime currently provides no support
	for method forwarding or method invocations other than the
	<code>__objc_msg_forward2</code> hook.
	</p>
	<p>If the forwarding hook does not exist or returns <code>NULL</code>, the
	runtime currently attempts forwarding using an older, deprecated API,
	and if that fails, it aborts the program. In future versions of the
	GNU Objective-C runtime, the runtime will immediately abort.
	</p>
	<hr>
	<div class="header">
	<p>
	Previous: <a href="Dynamically-registering-methods.html#Dynamically-registering-methods" accesskey="p" rel="prev">Dynamically registering methods</a>, Up: <a href="Messaging-with-the-GNU-Objective_002dC-runtime.html#Messaging-with-the-GNU-Objective_002dC-runtime" accesskey="u" rel="up">Messaging with the GNU Objective-C runtime</a>   [<a href="index.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>][<a href="Option-Index.html#Option-Index" title="Index" rel="index">Index</a>]</p>
	</div>



	</body>
	</html>