docs/LanguageExtensions.html - platform/external/clang - Gitiles

 <html>
 <head>
 <title>Clang Language Extensions</title>
 <link type="text/css" rel="stylesheet" href="../menu.css" />
 <link type="text/css" rel="stylesheet" href="../content.css" />
 <style type="text/css">
 td {
 	vertical-align: top;
 }
 </style>
 </head>
 <body>

 <!--#include virtual="../menu.html.incl"-->

 <div id="content">

 <h1>Clang Language Extensions</h1>

 <ul>
 <li><a href="#intro">Introduction</a></li>
 <li><a href="#vectors">Vectors and Extended Vectors</a></li>
 <li><a href="#blocks">Blocks</a></li>
 <li><a href="#overloading-in-c">Function Overloading in C</a></li>
 <li><a href="#builtins">Builtin Functions</a>
   <ul>
   <li><a href="#__builtin_overload">__builtin_overload</a></li>
   <li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
   </ul>
 </li>
 </ul>


 <!-- ======================================================================= -->
 <h2 id="intro">Introduction</h2>
 <!-- ======================================================================= -->

 <p>This document describes the language extensions provided by Clang.  In
 addition to the langauge extensions listed here, Clang aims to support a broad
 range of GCC extensions.  Please see the <a
 href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
 more information on these extensions.</p>

 <!-- ======================================================================= -->
 <h2 id="vectors">Vectors and Extended Vectors</h2>
 <!-- ======================================================================= -->

 <p>Supports the GCC vector extensions, plus some stuff like V[1].  ext_vector
 with V.xyzw syntax and other tidbits.  See also <a
 href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>

 <!-- ======================================================================= -->
 <h2 id="blocks">Blocks</h2>
 <!-- ======================================================================= -->

 <p>The idea, syntax, and semantics.</p>

 <!-- ======================================================================= -->
 <h2 id="overloading-in-c">Function Overloading in C</h2>
 <!-- ======================================================================= -->

 <p>Clang provides support for C++ function overloading in C. Function overloading in C is introduced using the <tt>overloadable</tt> attribute. For example, one might provide several overloaded versions of a <tt>tgsin</tt> function that invokes the appropriate standard function computing the sine of a value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt> precision:</p>

 <blockquote>
 <pre>
 #include &lt;math.h&gt;
 float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
 double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
 long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
 </pre>
 </blockquote>

 <p>Given these declarations, one can call <tt>tgsin</tt> with a
 <tt>float</tt> value to receive a <tt>float</tt> result, with a
 <tt>double</tt> to receive a <tt>double</tt> result, etc. Function
 overloading in C follows the rules of C++ function overloading to pick
 the best overload given the call arguments, with a few C-specific
 semantics:</p>
 <ul>
   <li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
   double</tt> is ranked as a floating-point promotion (per C99) rather
   than as a floating-point conversion (as in C++).</li>

   <li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
   <tt>U*</tt> is considered a pointer conversion (with conversion
   rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>

   <li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
   is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
   conversion is given "conversion" rank.</li>
 </ul>

 <p>The declaration of <tt>overloadable</tt> functions is restricted to
 function declarations and definitions. Most importantly, if any
 function with a given name is given the <tt>overloadable</tt>
 attribute, then all function declarations and definitions with that
 name (and in that scope) must have the <tt>overloadable</tt>
 attribute. This rule even applies to redeclarations of functions whose original declaration had the <tt>overloadable</tt> attribute, e.g.,</p>

 <blockquote>
 <pre>
 int f(int) __attribute__((overloadable));
 float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>

 int g(int) __attribute__((overloadable));
 int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
 </pre>
 </blockquote>

 <p>Functions declared with the <tt>overloadable</tt> attribute have
 their names mangled according to the same rules as C++ function
 names. For example, the three <tt>tgsin</tt> functions in our
 motivating example get the mangled names <tt>_Z5tgsinf</tt>,
 <tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
 caveats to this use of name mangling:</p>

 <ul>

   <li>Future versions of Clang may change the name mangling of
   functions overloaded in C, so you should not depend on an specific
   mangling. To be completely safe, we strongly urge the use of
   <tt>static inline</tt> with <tt>overloadable</tt> functions.</li>

   <li>The <tt>overloadable</tt> attribute has almost no meaning when
   used in C++, because names will already be mangled and functions are
   already overloadable. However, when an <tt>overloadable</tt>
   function occurs within an <tt>extern "C"</tt> linkage specification,
   it's name <i>will</i> be mangled in the same way as it would in
   C.</li>
 </ul>

 <!-- ======================================================================= -->
 <h2 id="builtins">Builtin Functions</h2>
 <!-- ======================================================================= -->

 <p>Clang supports a number of builtin library functions with the same syntax as
 GCC, including things like <tt>__builtin_nan</tt>,
 <tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
 <tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc.  In
 addition to the GCC builtins, Clang supports a number of builtins that GCC does
 not, which are listed here.</p>

 <p>Please note that Clang does not and will not support all of the GCC builtins
 for vector operations.  Instead of using builtins, you should use the functions
 defined in target-specific header files like <tt>&lt;xmmintrin.h&gt;</tt>, which
 define portable wrappers for these.  Many of the Clang versions of these
 functions are implemented directly in terms of <a href="#vectors">extended
 vector support</a> instead of builtins, in order to reduce the number of
 builtins that we need to implement.</p>


 <!-- ======================================================================= -->
 <h3 id="__builtin_overload">__builtin_overload</h3>
 <!-- ======================================================================= -->

 <p><tt>__builtin_overload</tt> is used to implement type-generic "overloaded"
 functions in C.  This builtin is used to implement the <tt>&lt;tgmath.h&gt;</tt>
 header file, but is intended to be usable for a broad variety of other similar
 situations, like the <tt>&lt;altivec.h&gt;</tt> header.
 <b>In the future, we intend to eliminate <tt>__builtin_overload</tt> in favor of <a href="#overloading-in-c">function overloading in C</a>, which provides a better solution for type-generic "overloaded" functions.</b>
 </p>

 <p><b>Syntax:</b></p>

 <pre>
 __builtin_overload(FnNameStr, PromotionRuleStr, NumArgs, arg1, arg2, ...
                    overloadcandidate1, overloadcandidate2, ...)
 </pre>

 <p><b>Examples:</b></p>

 <pre>
 #define sin(x) \
   (__builtin_overload("sin", "tgmath", 1, x, sinf, sin, sinl,
                       csinf, csin, csinl)(x))
 #define fma(x,y,z) \
   (__builtin_overload("fma", "tgmath", 3, x, y, z, fmaf, fma, fmal)(x,y,z))
 #define ldexp(x, y) \
   (__builtin_overload("ldexp", "tgmath1", 2, x, 0, ldexpf, ldexp, ldexpl)(x,y))
 </pre>

 <p><b>Description:</b></p>

 <p>The first argument to __builtin_overload is a string that is the name of the
 "function" being implemented.  This is used to produce diagnostics that make
 sense to the user.  For example, if you accidentally pass a pointer argument to
 "sin" in GCC, it emits 6 errors about incompatible types.  This name allows
 Clang to diagnose the error in a way the user can understand.
 </p>

 <p>The second argument is a string that indicates a set of promotion rules to
 apply to the arguments before prototype matching occurs.  The currently
 supported rules are:</p>

 <dl>
   <dt>tgmath</dt>
   <dd>Follow the rules of C99 7.22 to determine a single common type, and use it
       for every argument.</dd>
   <dt>tgmath1</dt>
   <dd>Follow the rules of C99 7.22 to determine a single common type of just the
       first argument (e.g. treat ints as doubles).</dd>
 </dl>

 <p>The third argument is an integer that specifies the arity of the function
    being overloaded.  After this are N expression arguments which are promoted
    according to the rules specified by the promotion rule string.</p>

 <p>The final arguments are functions or function pointers with different
    signatures.  __builtin_overload will match and evaluate to the first function
    pointer whose signature is compatible and does not cause value truncation of
    any arguments to the function.</p>


 <!-- ======================================================================= -->
 <h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
 <!-- ======================================================================= -->

 <p>todo describe me.</p>


 </div>
 </body>
 </html>
	<html>
	<head>
	<title>Clang Language Extensions</title>
	<link type="text/css" rel="stylesheet" href="../menu.css" />
	<link type="text/css" rel="stylesheet" href="../content.css" />
	<style type="text/css">
	td {
	vertical-align: top;
	}
	</style>
	</head>
	<body>

	<!--#include virtual="../menu.html.incl"-->

	<div id="content">

	<h1>Clang Language Extensions</h1>

	<ul>
	<li><a href="#intro">Introduction</a></li>
	<li><a href="#vectors">Vectors and Extended Vectors</a></li>
	<li><a href="#blocks">Blocks</a></li>
	<li><a href="#overloading-in-c">Function Overloading in C</a></li>
	<li><a href="#builtins">Builtin Functions</a>
	<ul>
	<li><a href="#__builtin_overload">__builtin_overload</a></li>
	<li><a href="#__builtin_shufflevector">__builtin_shufflevector</a></li>
	</ul>
	</li>
	</ul>


	<!-- ======================================================================= -->
	<h2 id="intro">Introduction</h2>
	<!-- ======================================================================= -->

	<p>This document describes the language extensions provided by Clang. In
	addition to the langauge extensions listed here, Clang aims to support a broad
	range of GCC extensions. Please see the <a
	href="http://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html">GCC manual</a> for
	more information on these extensions.</p>

	<!-- ======================================================================= -->
	<h2 id="vectors">Vectors and Extended Vectors</h2>
	<!-- ======================================================================= -->

	<p>Supports the GCC vector extensions, plus some stuff like V[1]. ext_vector
	with V.xyzw syntax and other tidbits. See also <a
	href="#__builtin_shufflevector">__builtin_shufflevector</a>.</p>

	<!-- ======================================================================= -->
	<h2 id="blocks">Blocks</h2>
	<!-- ======================================================================= -->

	<p>The idea, syntax, and semantics.</p>

	<!-- ======================================================================= -->
	<h2 id="overloading-in-c">Function Overloading in C</h2>
	<!-- ======================================================================= -->

	<p>Clang provides support for C++ function overloading in C. Function overloading in C is introduced using the <tt>overloadable</tt> attribute. For example, one might provide several overloaded versions of a <tt>tgsin</tt> function that invokes the appropriate standard function computing the sine of a value with <tt>float</tt>, <tt>double</tt>, or <tt>long double</tt> precision:</p>

	<blockquote>
	<pre>
	#include <math.h>
	float <b>__attribute__((overloadable))</b> tgsin(float x) { return sinf(x); }
	double <b>__attribute__((overloadable))</b> tgsin(double x) { return sin(x); }
	long double <b>__attribute__((overloadable))</b> tgsin(long double x) { return sinl(x); }
	</pre>
	</blockquote>

	<p>Given these declarations, one can call <tt>tgsin</tt> with a
	<tt>float</tt> value to receive a <tt>float</tt> result, with a
	<tt>double</tt> to receive a <tt>double</tt> result, etc. Function
	overloading in C follows the rules of C++ function overloading to pick
	the best overload given the call arguments, with a few C-specific
	semantics:</p>
	<ul>
	<li>Conversion from <tt>float</tt> or <tt>double</tt> to <tt>long
	double</tt> is ranked as a floating-point promotion (per C99) rather
	than as a floating-point conversion (as in C++).</li>

	<li>A conversion from a pointer of type <tt>T*</tt> to a pointer of type
	<tt>U*</tt> is considered a pointer conversion (with conversion
	rank) if <tt>T</tt> and <tt>U</tt> are compatible types.</li>

	<li>A conversion from type <tt>T</tt> to a value of type <tt>U</tt>
	is permitted if <tt>T</tt> and <tt>U</tt> are compatible types. This
	conversion is given "conversion" rank.</li>
	</ul>

	<p>The declaration of <tt>overloadable</tt> functions is restricted to
	function declarations and definitions. Most importantly, if any
	function with a given name is given the <tt>overloadable</tt>
	attribute, then all function declarations and definitions with that
	name (and in that scope) must have the <tt>overloadable</tt>
	attribute. This rule even applies to redeclarations of functions whose original declaration had the <tt>overloadable</tt> attribute, e.g.,</p>

	<blockquote>
	<pre>
	int f(int) __attribute__((overloadable));
	float f(float); <i>// error: declaration of "f" must have the "overloadable" attribute</i>

	int g(int) __attribute__((overloadable));
	int g(int) { } <i>// error: redeclaration of "g" must also have the "overloadable" attribute</i>
	</pre>
	</blockquote>

	<p>Functions declared with the <tt>overloadable</tt> attribute have
	their names mangled according to the same rules as C++ function
	names. For example, the three <tt>tgsin</tt> functions in our
	motivating example get the mangled names <tt>_Z5tgsinf</tt>,
	<tt>_Z5tgsind</tt>, and <tt>Z5tgsine</tt>, respectively. There are two
	caveats to this use of name mangling:</p>

	<ul>

	<li>Future versions of Clang may change the name mangling of
	functions overloaded in C, so you should not depend on an specific
	mangling. To be completely safe, we strongly urge the use of
	<tt>static inline</tt> with <tt>overloadable</tt> functions.</li>

	<li>The <tt>overloadable</tt> attribute has almost no meaning when
	used in C++, because names will already be mangled and functions are
	already overloadable. However, when an <tt>overloadable</tt>
	function occurs within an <tt>extern "C"</tt> linkage specification,
	it's name <i>will</i> be mangled in the same way as it would in
	C.</li>
	</ul>

	<!-- ======================================================================= -->
	<h2 id="builtins">Builtin Functions</h2>
	<!-- ======================================================================= -->

	<p>Clang supports a number of builtin library functions with the same syntax as
	GCC, including things like <tt>__builtin_nan</tt>,
	<tt>__builtin_constant_p</tt>, <tt>__builtin_choose_expr</tt>,
	<tt>__builtin_types_compatible_p</tt>, <tt>__sync_fetch_and_add</tt>, etc. In
	addition to the GCC builtins, Clang supports a number of builtins that GCC does
	not, which are listed here.</p>

	<p>Please note that Clang does not and will not support all of the GCC builtins
	for vector operations. Instead of using builtins, you should use the functions
	defined in target-specific header files like <tt><xmmintrin.h></tt>, which
	define portable wrappers for these. Many of the Clang versions of these
	functions are implemented directly in terms of <a href="#vectors">extended
	vector support</a> instead of builtins, in order to reduce the number of
	builtins that we need to implement.</p>


	<!-- ======================================================================= -->
	<h3 id="__builtin_overload">__builtin_overload</h3>
	<!-- ======================================================================= -->

	<p><tt>__builtin_overload</tt> is used to implement type-generic "overloaded"
	functions in C. This builtin is used to implement the <tt><tgmath.h></tt>
	header file, but is intended to be usable for a broad variety of other similar
	situations, like the <tt><altivec.h></tt> header.
	<b>In the future, we intend to eliminate <tt>__builtin_overload</tt> in favor of <a href="#overloading-in-c">function overloading in C</a>, which provides a better solution for type-generic "overloaded" functions.</b>
	</p>

	<p><b>Syntax:</b></p>

	<pre>
	__builtin_overload(FnNameStr, PromotionRuleStr, NumArgs, arg1, arg2, ...
	overloadcandidate1, overloadcandidate2, ...)
	</pre>

	<p><b>Examples:</b></p>

	<pre>
	#define sin(x) \
	(__builtin_overload("sin", "tgmath", 1, x, sinf, sin, sinl,
	csinf, csin, csinl)(x))
	#define fma(x,y,z) \
	(__builtin_overload("fma", "tgmath", 3, x, y, z, fmaf, fma, fmal)(x,y,z))
	#define ldexp(x, y) \
	(__builtin_overload("ldexp", "tgmath1", 2, x, 0, ldexpf, ldexp, ldexpl)(x,y))
	</pre>

	<p><b>Description:</b></p>

	<p>The first argument to __builtin_overload is a string that is the name of the
	"function" being implemented. This is used to produce diagnostics that make
	sense to the user. For example, if you accidentally pass a pointer argument to
	"sin" in GCC, it emits 6 errors about incompatible types. This name allows
	Clang to diagnose the error in a way the user can understand.
	</p>

	<p>The second argument is a string that indicates a set of promotion rules to
	apply to the arguments before prototype matching occurs. The currently
	supported rules are:</p>

	<dl>
	<dt>tgmath</dt>
	<dd>Follow the rules of C99 7.22 to determine a single common type, and use it
	for every argument.</dd>
	<dt>tgmath1</dt>
	<dd>Follow the rules of C99 7.22 to determine a single common type of just the
	first argument (e.g. treat ints as doubles).</dd>
	</dl>

	<p>The third argument is an integer that specifies the arity of the function
	being overloaded. After this are N expression arguments which are promoted
	according to the rules specified by the promotion rule string.</p>

	<p>The final arguments are functions or function pointers with different
	signatures. __builtin_overload will match and evaluate to the first function
	pointer whose signature is compatible and does not cause value truncation of
	any arguments to the function.</p>


	<!-- ======================================================================= -->
	<h3 id="__builtin_shufflevector">__builtin_shufflevector</h3>
	<!-- ======================================================================= -->

	<p>todo describe me.</p>


	</div>
	</body>
	</html>