From ecd5156dd539efc9e8e7c1a14c6d54d842079bdf Mon Sep 17 00:00:00 2001 From: David Malcolm Date: Thu, 28 Sep 2017 17:12:19 +0000 Subject: [PATCH] jit: document function pointers gcc/jit/ChangeLog: * docs/topics/expressions.rst (Function calls): Add link to gcc_jit_context_new_function_ptr_type. (Function pointers): Convert to cross-references to function-pointers.rst, moving material there. * docs/topics/function-pointers.rst: New page. * docs/topics/index.rst: Add function-pointers.rst. * docs/topics/types.rst (Function pointer types): New section. * docs/_build/texinfo/libgccjit.texi: Regenerate. From-SVN: r253257 --- gcc/jit/ChangeLog | 11 + gcc/jit/docs/_build/texinfo/libgccjit.texi | 1041 +++++++++++--------- gcc/jit/docs/topics/expressions.rst | 21 +- gcc/jit/docs/topics/function-pointers.rst | 80 ++ gcc/jit/docs/topics/index.rst | 1 + gcc/jit/docs/topics/types.rst | 6 + 6 files changed, 677 insertions(+), 483 deletions(-) create mode 100644 gcc/jit/docs/topics/function-pointers.rst diff --git a/gcc/jit/ChangeLog b/gcc/jit/ChangeLog index b5e2ed7868f..aabcefa7c68 100644 --- a/gcc/jit/ChangeLog +++ b/gcc/jit/ChangeLog @@ -1,3 +1,14 @@ +2017-09-28 David Malcolm + + * docs/topics/expressions.rst (Function calls): Add link to + gcc_jit_context_new_function_ptr_type. + (Function pointers): Convert to cross-references to + function-pointers.rst, moving material there. + * docs/topics/function-pointers.rst: New page. + * docs/topics/index.rst: Add function-pointers.rst. + * docs/topics/types.rst (Function pointer types): New section. + * docs/_build/texinfo/libgccjit.texi: Regenerate. + 2017-09-28 David Malcolm * jit-recording.c diff --git a/gcc/jit/docs/_build/texinfo/libgccjit.texi b/gcc/jit/docs/_build/texinfo/libgccjit.texi index 0398b16bf50..1d21e81b9ab 100644 --- a/gcc/jit/docs/_build/texinfo/libgccjit.texi +++ b/gcc/jit/docs/_build/texinfo/libgccjit.texi @@ -19,7 +19,7 @@ @copying @quotation -libgccjit 8.0.0 (experimental 20170927), September 27, 2017 +libgccjit 8.0.0 (experimental 20170928), September 28, 2017 David Malcolm @@ -166,6 +166,7 @@ Topic Reference * Types:: * Expressions:: * Creating and using functions:: +* Function pointers: Function pointers<2>. * Source Locations:: * Compiling a context:: * ABI and API compatibility:: @@ -192,6 +193,7 @@ Types * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile. * Vector types:: * Structures and unions:: +* Function pointer types:: Expressions @@ -337,7 +339,7 @@ Rvalues * Binary Operations: Binary Operations<2>. * Comparisons: Comparisons<2>. * Function calls: Function calls<2>. -* Function pointers: Function pointers<2>. +* Function pointers: Function pointers<3>. * Type-coercion: Type-coercion<2>. Lvalues @@ -4864,6 +4866,7 @@ and to a dynamic library. See the documentation of * Types:: * Expressions:: * Creating and using functions:: +* Function pointers: Function pointers<2>. * Source Locations:: * Compiling a context:: * ABI and API compatibility:: @@ -4890,6 +4893,7 @@ Types * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile. * Vector types:: * Structures and unions:: +* Function pointer types:: Expressions @@ -5804,6 +5808,7 @@ by creating structures (see below). * Pointers@comma{} const@comma{} and volatile: Pointers const and volatile. * Vector types:: * Structures and unions:: +* Function pointer types:: @end menu @@ -6128,7 +6133,7 @@ for its presence using @noindent @end deffn -@node Structures and unions,,Vector types,Types +@node Structures and unions,Function pointer types,Vector types,Types @anchor{topics/types structures-and-unions}@anchor{85} @subsection Structures and unions @@ -6357,6 +6362,14 @@ create_code (gcc_jit_context *ctxt, void *user_data) @noindent @end deffn +@node Function pointer types,,Structures and unions,Types +@anchor{topics/types function-pointer-types}@anchor{8f} +@subsection Function pointer types + + +Function pointer types can be created using +@pxref{90,,gcc_jit_context_new_function_ptr_type()}. + @c Copyright (C) 2014-2017 Free Software Foundation, Inc. @c Originally contributed by David Malcolm @c @@ -6375,7 +6388,7 @@ create_code (gcc_jit_context *ctxt, void *user_data) @c . @node Expressions,Creating and using functions,Types,Topic Reference -@anchor{topics/expressions expressions}@anchor{8f}@anchor{topics/expressions doc}@anchor{90} +@anchor{topics/expressions expressions}@anchor{91}@anchor{topics/expressions doc}@anchor{92} @section Expressions @@ -6402,7 +6415,7 @@ Lvalues @node Rvalues,Lvalues,,Expressions -@anchor{topics/expressions rvalues}@anchor{91} +@anchor{topics/expressions rvalues}@anchor{93} @subsection Rvalues @@ -6456,7 +6469,7 @@ Every rvalue has an associated type, and the API will check to ensure that types match up correctly (otherwise the context will emit an error). @geindex gcc_jit_rvalue_get_type (C function) -@anchor{topics/expressions gcc_jit_rvalue_get_type}@anchor{92} +@anchor{topics/expressions gcc_jit_rvalue_get_type}@anchor{94} @deffn {C Function} gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue@w{ }*rvalue) Get the type of this rvalue. @@ -6481,7 +6494,7 @@ Upcast the given rvalue to be an object. @end menu @node Simple expressions,Unary Operations,,Rvalues -@anchor{topics/expressions simple-expressions}@anchor{93} +@anchor{topics/expressions simple-expressions}@anchor{95} @subsubsection Simple expressions @@ -6494,7 +6507,7 @@ the given constant @code{int} value. @end deffn @geindex gcc_jit_context_new_rvalue_from_long (C function) -@anchor{topics/expressions gcc_jit_context_new_rvalue_from_long}@anchor{94} +@anchor{topics/expressions gcc_jit_context_new_rvalue_from_long}@anchor{96} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_long (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type, long@w{ }value) Given a numeric type (integer or floating point), build an rvalue for @@ -6538,14 +6551,14 @@ the given constant @code{double} value. @end deffn @geindex gcc_jit_context_new_rvalue_from_ptr (C function) -@anchor{topics/expressions gcc_jit_context_new_rvalue_from_ptr}@anchor{95} +@anchor{topics/expressions gcc_jit_context_new_rvalue_from_ptr}@anchor{97} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*pointer_type, void@w{ }*value) Given a pointer type, build an rvalue for the given address. @end deffn @geindex gcc_jit_context_null (C function) -@anchor{topics/expressions gcc_jit_context_null}@anchor{96} +@anchor{topics/expressions gcc_jit_context_null}@anchor{98} @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*pointer_type) Given a pointer type, build an rvalue for @code{NULL}. Essentially this @@ -6559,7 +6572,7 @@ gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL) @end deffn @geindex gcc_jit_context_new_string_literal (C function) -@anchor{topics/expressions gcc_jit_context_new_string_literal}@anchor{97} +@anchor{topics/expressions gcc_jit_context_new_string_literal}@anchor{99} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_string_literal (gcc_jit_context@w{ }*ctxt, const char@w{ }*value) Generate an rvalue for the given NIL-terminated string, of type @@ -6571,19 +6584,19 @@ buffer. @end deffn @node Unary Operations,Binary Operations,Simple expressions,Rvalues -@anchor{topics/expressions unary-operations}@anchor{98} +@anchor{topics/expressions unary-operations}@anchor{9a} @subsubsection Unary Operations @geindex gcc_jit_context_new_unary_op (C function) -@anchor{topics/expressions gcc_jit_context_new_unary_op}@anchor{99} +@anchor{topics/expressions gcc_jit_context_new_unary_op}@anchor{9b} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_unary_op (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_unary_op@w{ }op, gcc_jit_type@w{ }*result_type, gcc_jit_rvalue@w{ }*rvalue) Build a unary operation out of an input rvalue. @end deffn @geindex gcc_jit_unary_op (C type) -@anchor{topics/expressions gcc_jit_unary_op}@anchor{9a} +@anchor{topics/expressions gcc_jit_unary_op}@anchor{9c} @deffn {C Type} enum gcc_jit_unary_op @end deffn @@ -6601,7 +6614,7 @@ C equivalent @item -@pxref{9b,,GCC_JIT_UNARY_OP_MINUS} +@pxref{9d,,GCC_JIT_UNARY_OP_MINUS} @tab @@ -6609,7 +6622,7 @@ C equivalent @item -@pxref{9c,,GCC_JIT_UNARY_OP_BITWISE_NEGATE} +@pxref{9e,,GCC_JIT_UNARY_OP_BITWISE_NEGATE} @tab @@ -6617,7 +6630,7 @@ C equivalent @item -@pxref{9d,,GCC_JIT_UNARY_OP_LOGICAL_NEGATE} +@pxref{9f,,GCC_JIT_UNARY_OP_LOGICAL_NEGATE} @tab @@ -6625,7 +6638,7 @@ C equivalent @item -@pxref{9e,,GCC_JIT_UNARY_OP_ABS} +@pxref{a0,,GCC_JIT_UNARY_OP_ABS} @tab @@ -6635,7 +6648,7 @@ C equivalent @geindex GCC_JIT_UNARY_OP_MINUS (C macro) -@anchor{topics/expressions GCC_JIT_UNARY_OP_MINUS}@anchor{9b} +@anchor{topics/expressions GCC_JIT_UNARY_OP_MINUS}@anchor{9d} @deffn {C Macro} GCC_JIT_UNARY_OP_MINUS Negate an arithmetic value; analogous to: @@ -6650,7 +6663,7 @@ in C. @end deffn @geindex GCC_JIT_UNARY_OP_BITWISE_NEGATE (C macro) -@anchor{topics/expressions GCC_JIT_UNARY_OP_BITWISE_NEGATE}@anchor{9c} +@anchor{topics/expressions GCC_JIT_UNARY_OP_BITWISE_NEGATE}@anchor{9e} @deffn {C Macro} GCC_JIT_UNARY_OP_BITWISE_NEGATE Bitwise negation of an integer value (one's complement); analogous @@ -6666,7 +6679,7 @@ in C. @end deffn @geindex GCC_JIT_UNARY_OP_LOGICAL_NEGATE (C macro) -@anchor{topics/expressions GCC_JIT_UNARY_OP_LOGICAL_NEGATE}@anchor{9d} +@anchor{topics/expressions GCC_JIT_UNARY_OP_LOGICAL_NEGATE}@anchor{9f} @deffn {C Macro} GCC_JIT_UNARY_OP_LOGICAL_NEGATE Logical negation of an arithmetic or pointer value; analogous to: @@ -6681,7 +6694,7 @@ in C. @end deffn @geindex GCC_JIT_UNARY_OP_ABS (C macro) -@anchor{topics/expressions GCC_JIT_UNARY_OP_ABS}@anchor{9e} +@anchor{topics/expressions GCC_JIT_UNARY_OP_ABS}@anchor{a0} @deffn {C Macro} GCC_JIT_UNARY_OP_ABS Absolute value of an arithmetic expression; analogous to: @@ -6696,7 +6709,7 @@ in C. @end deffn @node Binary Operations,Comparisons,Unary Operations,Rvalues -@anchor{topics/expressions binary-operations}@anchor{9f} +@anchor{topics/expressions binary-operations}@anchor{a1} @subsubsection Binary Operations @@ -6708,7 +6721,7 @@ Build a binary operation out of two constituent rvalues. @end deffn @geindex gcc_jit_binary_op (C type) -@anchor{topics/expressions gcc_jit_binary_op}@anchor{a0} +@anchor{topics/expressions gcc_jit_binary_op}@anchor{a2} @deffn {C Type} enum gcc_jit_binary_op @end deffn @@ -6726,7 +6739,7 @@ C equivalent @item -@pxref{a1,,GCC_JIT_BINARY_OP_PLUS} +@pxref{a3,,GCC_JIT_BINARY_OP_PLUS} @tab @@ -6734,7 +6747,7 @@ C equivalent @item -@pxref{a2,,GCC_JIT_BINARY_OP_MINUS} +@pxref{a4,,GCC_JIT_BINARY_OP_MINUS} @tab @@ -6742,7 +6755,7 @@ C equivalent @item -@pxref{a3,,GCC_JIT_BINARY_OP_MULT} +@pxref{a5,,GCC_JIT_BINARY_OP_MULT} @tab @@ -6750,7 +6763,7 @@ C equivalent @item -@pxref{a4,,GCC_JIT_BINARY_OP_DIVIDE} +@pxref{a6,,GCC_JIT_BINARY_OP_DIVIDE} @tab @@ -6758,7 +6771,7 @@ C equivalent @item -@pxref{a5,,GCC_JIT_BINARY_OP_MODULO} +@pxref{a7,,GCC_JIT_BINARY_OP_MODULO} @tab @@ -6766,7 +6779,7 @@ C equivalent @item -@pxref{a6,,GCC_JIT_BINARY_OP_BITWISE_AND} +@pxref{a8,,GCC_JIT_BINARY_OP_BITWISE_AND} @tab @@ -6774,7 +6787,7 @@ C equivalent @item -@pxref{a7,,GCC_JIT_BINARY_OP_BITWISE_XOR} +@pxref{a9,,GCC_JIT_BINARY_OP_BITWISE_XOR} @tab @@ -6782,7 +6795,7 @@ C equivalent @item -@pxref{a8,,GCC_JIT_BINARY_OP_BITWISE_OR} +@pxref{aa,,GCC_JIT_BINARY_OP_BITWISE_OR} @tab @@ -6790,7 +6803,7 @@ C equivalent @item -@pxref{a9,,GCC_JIT_BINARY_OP_LOGICAL_AND} +@pxref{ab,,GCC_JIT_BINARY_OP_LOGICAL_AND} @tab @@ -6798,7 +6811,7 @@ C equivalent @item -@pxref{aa,,GCC_JIT_BINARY_OP_LOGICAL_OR} +@pxref{ac,,GCC_JIT_BINARY_OP_LOGICAL_OR} @tab @@ -6806,7 +6819,7 @@ C equivalent @item -@pxref{ab,,GCC_JIT_BINARY_OP_LSHIFT} +@pxref{ad,,GCC_JIT_BINARY_OP_LSHIFT} @tab @@ -6814,7 +6827,7 @@ C equivalent @item -@pxref{ac,,GCC_JIT_BINARY_OP_RSHIFT} +@pxref{ae,,GCC_JIT_BINARY_OP_RSHIFT} @tab @@ -6824,7 +6837,7 @@ C equivalent @geindex GCC_JIT_BINARY_OP_PLUS (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_PLUS}@anchor{a1} +@anchor{topics/expressions GCC_JIT_BINARY_OP_PLUS}@anchor{a3} @deffn {C Macro} GCC_JIT_BINARY_OP_PLUS Addition of arithmetic values; analogous to: @@ -6837,11 +6850,11 @@ Addition of arithmetic values; analogous to: in C. -For pointer addition, use @pxref{ad,,gcc_jit_context_new_array_access()}. +For pointer addition, use @pxref{af,,gcc_jit_context_new_array_access()}. @end deffn @geindex GCC_JIT_BINARY_OP_MINUS (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_MINUS}@anchor{a2} +@anchor{topics/expressions GCC_JIT_BINARY_OP_MINUS}@anchor{a4} @deffn {C Macro} GCC_JIT_BINARY_OP_MINUS Subtraction of arithmetic values; analogous to: @@ -6856,7 +6869,7 @@ in C. @end deffn @geindex GCC_JIT_BINARY_OP_MULT (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_MULT}@anchor{a3} +@anchor{topics/expressions GCC_JIT_BINARY_OP_MULT}@anchor{a5} @deffn {C Macro} GCC_JIT_BINARY_OP_MULT Multiplication of a pair of arithmetic values; analogous to: @@ -6871,7 +6884,7 @@ in C. @end deffn @geindex GCC_JIT_BINARY_OP_DIVIDE (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_DIVIDE}@anchor{a4} +@anchor{topics/expressions GCC_JIT_BINARY_OP_DIVIDE}@anchor{a6} @deffn {C Macro} GCC_JIT_BINARY_OP_DIVIDE Quotient of division of arithmetic values; analogous to: @@ -6890,7 +6903,7 @@ a floating-point result type indicates floating-point division. @end deffn @geindex GCC_JIT_BINARY_OP_MODULO (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_MODULO}@anchor{a5} +@anchor{topics/expressions GCC_JIT_BINARY_OP_MODULO}@anchor{a7} @deffn {C Macro} GCC_JIT_BINARY_OP_MODULO Remainder of division of arithmetic values; analogous to: @@ -6905,7 +6918,7 @@ in C. @end deffn @geindex GCC_JIT_BINARY_OP_BITWISE_AND (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_AND}@anchor{a6} +@anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_AND}@anchor{a8} @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_AND Bitwise AND; analogous to: @@ -6920,7 +6933,7 @@ in C. @end deffn @geindex GCC_JIT_BINARY_OP_BITWISE_XOR (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_XOR}@anchor{a7} +@anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_XOR}@anchor{a9} @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_XOR Bitwise exclusive OR; analogous to: @@ -6935,7 +6948,7 @@ in C. @end deffn @geindex GCC_JIT_BINARY_OP_BITWISE_OR (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_OR}@anchor{a8} +@anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_OR}@anchor{aa} @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_OR Bitwise inclusive OR; analogous to: @@ -6950,7 +6963,7 @@ in C. @end deffn @geindex GCC_JIT_BINARY_OP_LOGICAL_AND (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_AND}@anchor{a9} +@anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_AND}@anchor{ab} @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_AND Logical AND; analogous to: @@ -6965,7 +6978,7 @@ in C. @end deffn @geindex GCC_JIT_BINARY_OP_LOGICAL_OR (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_OR}@anchor{aa} +@anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_OR}@anchor{ac} @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_OR Logical OR; analogous to: @@ -6980,7 +6993,7 @@ in C. @end deffn @geindex GCC_JIT_BINARY_OP_LSHIFT (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_LSHIFT}@anchor{ab} +@anchor{topics/expressions GCC_JIT_BINARY_OP_LSHIFT}@anchor{ad} @deffn {C Macro} GCC_JIT_BINARY_OP_LSHIFT Left shift; analogous to: @@ -6995,7 +7008,7 @@ in C. @end deffn @geindex GCC_JIT_BINARY_OP_RSHIFT (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_RSHIFT}@anchor{ac} +@anchor{topics/expressions GCC_JIT_BINARY_OP_RSHIFT}@anchor{ae} @deffn {C Macro} GCC_JIT_BINARY_OP_RSHIFT Right shift; analogous to: @@ -7010,7 +7023,7 @@ in C. @end deffn @node Comparisons,Function calls,Binary Operations,Rvalues -@anchor{topics/expressions comparisons}@anchor{ae} +@anchor{topics/expressions comparisons}@anchor{b0} @subsubsection Comparisons @@ -7022,7 +7035,7 @@ Build a boolean rvalue out of the comparison of two other rvalues. @end deffn @geindex gcc_jit_comparison (C type) -@anchor{topics/expressions gcc_jit_comparison}@anchor{af} +@anchor{topics/expressions gcc_jit_comparison}@anchor{b1} @deffn {C Type} enum gcc_jit_comparison @end deffn @@ -7088,12 +7101,12 @@ C equivalent @node Function calls,Function pointers,Comparisons,Rvalues -@anchor{topics/expressions function-calls}@anchor{b0} +@anchor{topics/expressions function-calls}@anchor{b2} @subsubsection Function calls @geindex gcc_jit_context_new_call (C function) -@anchor{topics/expressions gcc_jit_context_new_call}@anchor{b1} +@anchor{topics/expressions gcc_jit_context_new_call}@anchor{b3} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_call (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_function@w{ }*func, int@w{ }numargs, gcc_jit_rvalue@w{ }**args) Given a function and the given table of argument rvalues, construct a @@ -7101,7 +7114,7 @@ call to the function, with the result as an rvalue. @cartouche @quotation Note -@pxref{b1,,gcc_jit_context_new_call()} merely builds a +@pxref{b3,,gcc_jit_context_new_call()} merely builds a @pxref{13,,gcc_jit_rvalue} i.e. an expression that can be evaluated, perhaps as part of a more complicated expression. The call @emph{won't} happen unless you add a statement to a function @@ -7109,7 +7122,7 @@ that evaluates the expression. For example, if you want to call a function and discard the result (or to call a function with @code{void} return type), use -@pxref{b2,,gcc_jit_block_add_eval()}: +@pxref{b4,,gcc_jit_block_add_eval()}: @example /* Add "(void)printf (arg0, arg1);". */ @@ -7128,27 +7141,28 @@ gcc_jit_block_add_eval ( @end deffn @geindex gcc_jit_context_new_call_through_ptr (C function) -@anchor{topics/expressions gcc_jit_context_new_call_through_ptr}@anchor{b3} +@anchor{topics/expressions gcc_jit_context_new_call_through_ptr}@anchor{b5} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_call_through_ptr (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*fn_ptr, int@w{ }numargs, gcc_jit_rvalue@w{ }**args) -Given an rvalue of function pointer type, and the given table of +Given an rvalue of function pointer type (e.g. from +@pxref{90,,gcc_jit_context_new_function_ptr_type()}), and the given table of argument rvalues, construct a call to the function pointer, with the result as an rvalue. @cartouche @quotation Note -The same caveat as for @pxref{b1,,gcc_jit_context_new_call()} applies. +The same caveat as for @pxref{b3,,gcc_jit_context_new_call()} applies. @end quotation @end cartouche @end deffn @geindex gcc_jit_rvalue_set_bool_require_tail_call (C function) -@anchor{topics/expressions gcc_jit_rvalue_set_bool_require_tail_call}@anchor{b4} +@anchor{topics/expressions gcc_jit_rvalue_set_bool_require_tail_call}@anchor{b6} @deffn {C Function} void gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue@w{ }*call, int@w{ }require_tail_call) Given an @pxref{13,,gcc_jit_rvalue *} for a call created through -@pxref{b1,,gcc_jit_context_new_call()} or -@pxref{b3,,gcc_jit_context_new_call_through_ptr()}, mark/clear the +@pxref{b3,,gcc_jit_context_new_call()} or +@pxref{b5,,gcc_jit_context_new_call_through_ptr()}, mark/clear the call as needing tail-call optimization. The optimizer will attempt to optimize the call into a jump instruction; if it is unable to do do, an error will be emitted. @@ -7160,7 +7174,7 @@ languages), in which every function "returns" by calling a guaranteed to be implemented as a jump, otherwise the program could consume an arbitrary amount of stack space as it executed. -This entrypoint was added in @pxref{b5,,LIBGCCJIT_ABI_6}; you can test for +This entrypoint was added in @pxref{b7,,LIBGCCJIT_ABI_6}; you can test for its presence using @example @@ -7171,34 +7185,36 @@ its presence using @end deffn @node Function pointers,Type-coercion,Function calls,Rvalues -@anchor{topics/expressions function-pointers}@anchor{b6} +@anchor{topics/expressions function-pointers}@anchor{b8} @subsubsection Function pointers -@geindex gcc_jit_function_get_address (C function) -@anchor{topics/expressions gcc_jit_function_get_address}@anchor{b7} -@deffn {C Function} gcc_jit_rvalue * gcc_jit_function_get_address (gcc_jit_function@w{ }*fn, gcc_jit_location@w{ }*loc) +Function pointers can be obtained: -Get the address of a function as an rvalue, of function pointer -type. +@quotation -This entrypoint was added in @pxref{b8,,LIBGCCJIT_ABI_9}; you can test -for its presence using -@example -#ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address -@end example +@itemize * -@noindent -@end deffn +@item +from a @pxref{29,,gcc_jit_function} using +@pxref{b9,,gcc_jit_function_get_address()}, or + +@item +from an existing function using +@pxref{97,,gcc_jit_context_new_rvalue_from_ptr()}, +using a function pointer type obtained using +@pxref{90,,gcc_jit_context_new_function_ptr_type()}. +@end itemize +@end quotation @node Type-coercion,,Function pointers,Rvalues -@anchor{topics/expressions type-coercion}@anchor{b9} +@anchor{topics/expressions type-coercion}@anchor{ba} @subsubsection Type-coercion @geindex gcc_jit_context_new_cast (C function) -@anchor{topics/expressions gcc_jit_context_new_cast}@anchor{ba} +@anchor{topics/expressions gcc_jit_context_new_cast}@anchor{bb} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_cast (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*rvalue, gcc_jit_type@w{ }*type) Given an rvalue of T, construct another rvalue of another type. @@ -7223,7 +7239,7 @@ P* <-> Q*, for pointer types P and Q @end deffn @node Lvalues,Working with pointers structs and unions,Rvalues,Expressions -@anchor{topics/expressions lvalues}@anchor{bb} +@anchor{topics/expressions lvalues}@anchor{bc} @subsection Lvalues @@ -7237,21 +7253,21 @@ a storage area (such as a variable). It is also usable as an rvalue, where the rvalue is computed by reading from the storage area. @geindex gcc_jit_lvalue_as_object (C function) -@anchor{topics/expressions gcc_jit_lvalue_as_object}@anchor{bc} +@anchor{topics/expressions gcc_jit_lvalue_as_object}@anchor{bd} @deffn {C Function} gcc_jit_object * gcc_jit_lvalue_as_object (gcc_jit_lvalue@w{ }*lvalue) Upcast an lvalue to be an object. @end deffn @geindex gcc_jit_lvalue_as_rvalue (C function) -@anchor{topics/expressions gcc_jit_lvalue_as_rvalue}@anchor{bd} +@anchor{topics/expressions gcc_jit_lvalue_as_rvalue}@anchor{be} @deffn {C Function} gcc_jit_rvalue * gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue@w{ }*lvalue) Upcast an lvalue to be an rvalue. @end deffn @geindex gcc_jit_lvalue_get_address (C function) -@anchor{topics/expressions gcc_jit_lvalue_get_address}@anchor{be} +@anchor{topics/expressions gcc_jit_lvalue_get_address}@anchor{bf} @deffn {C Function} gcc_jit_rvalue * gcc_jit_lvalue_get_address (gcc_jit_lvalue@w{ }*lvalue, gcc_jit_location@w{ }*loc) Take the address of an lvalue; analogous to: @@ -7271,12 +7287,12 @@ in C. @end menu @node Global variables,,,Lvalues -@anchor{topics/expressions global-variables}@anchor{bf} +@anchor{topics/expressions global-variables}@anchor{c0} @subsubsection Global variables @geindex gcc_jit_context_new_global (C function) -@anchor{topics/expressions gcc_jit_context_new_global}@anchor{c0} +@anchor{topics/expressions gcc_jit_context_new_global}@anchor{c1} @deffn {C Function} gcc_jit_lvalue * gcc_jit_context_new_global (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_global_kind@w{ }kind, gcc_jit_type@w{ }*type, const char@w{ }*name) Add a new global variable of the given type and name to the context. @@ -7289,22 +7305,22 @@ The "kind" parameter determines the visibility of the "global" outside of the @pxref{16,,gcc_jit_result}: @geindex gcc_jit_global_kind (C type) -@anchor{topics/expressions gcc_jit_global_kind}@anchor{c1} +@anchor{topics/expressions gcc_jit_global_kind}@anchor{c2} @deffn {C Type} enum gcc_jit_global_kind @end deffn @geindex GCC_JIT_GLOBAL_EXPORTED (C macro) -@anchor{topics/expressions GCC_JIT_GLOBAL_EXPORTED}@anchor{c2} +@anchor{topics/expressions GCC_JIT_GLOBAL_EXPORTED}@anchor{c3} @deffn {C Macro} GCC_JIT_GLOBAL_EXPORTED Global is defined by the client code and is visible by name outside of this JIT context via -@pxref{c3,,gcc_jit_result_get_global()} (and this value is required for +@pxref{c4,,gcc_jit_result_get_global()} (and this value is required for the global to be accessible via that entrypoint). @end deffn @geindex GCC_JIT_GLOBAL_INTERNAL (C macro) -@anchor{topics/expressions GCC_JIT_GLOBAL_INTERNAL}@anchor{c4} +@anchor{topics/expressions GCC_JIT_GLOBAL_INTERNAL}@anchor{c5} @deffn {C Macro} GCC_JIT_GLOBAL_INTERNAL Global is defined by the client code, but is invisible @@ -7314,7 +7330,7 @@ context and within child contexts. @end deffn @geindex GCC_JIT_GLOBAL_IMPORTED (C macro) -@anchor{topics/expressions GCC_JIT_GLOBAL_IMPORTED}@anchor{c5} +@anchor{topics/expressions GCC_JIT_GLOBAL_IMPORTED}@anchor{c6} @deffn {C Macro} GCC_JIT_GLOBAL_IMPORTED Global is not defined by the client code; we're merely @@ -7324,12 +7340,12 @@ header file. @end deffn @node Working with pointers structs and unions,,Lvalues,Expressions -@anchor{topics/expressions working-with-pointers-structs-and-unions}@anchor{c6} +@anchor{topics/expressions working-with-pointers-structs-and-unions}@anchor{c7} @subsection Working with pointers, structs and unions @geindex gcc_jit_rvalue_dereference (C function) -@anchor{topics/expressions gcc_jit_rvalue_dereference}@anchor{c7} +@anchor{topics/expressions gcc_jit_rvalue_dereference}@anchor{c8} @deffn {C Function} gcc_jit_lvalue * gcc_jit_rvalue_dereference (gcc_jit_rvalue@w{ }*rvalue, gcc_jit_location@w{ }*loc) Given an rvalue of pointer type @code{T *}, dereferencing the pointer, @@ -7347,7 +7363,7 @@ in C. Field access is provided separately for both lvalues and rvalues. @geindex gcc_jit_lvalue_access_field (C function) -@anchor{topics/expressions gcc_jit_lvalue_access_field}@anchor{c8} +@anchor{topics/expressions gcc_jit_lvalue_access_field}@anchor{c9} @deffn {C Function} gcc_jit_lvalue * gcc_jit_lvalue_access_field (gcc_jit_lvalue@w{ }*struct_, gcc_jit_location@w{ }*loc, gcc_jit_field@w{ }*field) Given an lvalue of struct or union type, access the given field, @@ -7363,7 +7379,7 @@ in C. @end deffn @geindex gcc_jit_rvalue_access_field (C function) -@anchor{topics/expressions gcc_jit_rvalue_access_field}@anchor{c9} +@anchor{topics/expressions gcc_jit_rvalue_access_field}@anchor{ca} @deffn {C Function} gcc_jit_rvalue * gcc_jit_rvalue_access_field (gcc_jit_rvalue@w{ }*struct_, gcc_jit_location@w{ }*loc, gcc_jit_field@w{ }*field) Given an rvalue of struct or union type, access the given field @@ -7379,7 +7395,7 @@ in C. @end deffn @geindex gcc_jit_rvalue_dereference_field (C function) -@anchor{topics/expressions gcc_jit_rvalue_dereference_field}@anchor{ca} +@anchor{topics/expressions gcc_jit_rvalue_dereference_field}@anchor{cb} @deffn {C Function} gcc_jit_lvalue * gcc_jit_rvalue_dereference_field (gcc_jit_rvalue@w{ }*ptr, gcc_jit_location@w{ }*loc, gcc_jit_field@w{ }*field) Given an rvalue of pointer type @code{T *} where T is of struct or union @@ -7395,7 +7411,7 @@ in C, itself equivalent to @code{(*EXPR).FIELD}. @end deffn @geindex gcc_jit_context_new_array_access (C function) -@anchor{topics/expressions gcc_jit_context_new_array_access}@anchor{ad} +@anchor{topics/expressions gcc_jit_context_new_array_access}@anchor{af} @deffn {C Function} gcc_jit_lvalue * gcc_jit_context_new_array_access (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*ptr, gcc_jit_rvalue@w{ }*index) Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at @@ -7429,8 +7445,8 @@ in C (or, indeed, to @code{PTR + INDEX}). @c along with this program. If not, see @c . -@node Creating and using functions,Source Locations,Expressions,Topic Reference -@anchor{topics/functions doc}@anchor{cb}@anchor{topics/functions creating-and-using-functions}@anchor{cc} +@node Creating and using functions,Function pointers<2>,Expressions,Topic Reference +@anchor{topics/functions doc}@anchor{cc}@anchor{topics/functions creating-and-using-functions}@anchor{cd} @section Creating and using functions @@ -7443,7 +7459,7 @@ in C (or, indeed, to @code{PTR + INDEX}). @end menu @node Params,Functions,,Creating and using functions -@anchor{topics/functions params}@anchor{cd} +@anchor{topics/functions params}@anchor{ce} @subsection Params @@ -7470,28 +7486,28 @@ Parameters are lvalues, and thus are also rvalues (and objects), so the following upcasts are available: @geindex gcc_jit_param_as_lvalue (C function) -@anchor{topics/functions gcc_jit_param_as_lvalue}@anchor{ce} +@anchor{topics/functions gcc_jit_param_as_lvalue}@anchor{cf} @deffn {C Function} gcc_jit_lvalue * gcc_jit_param_as_lvalue (gcc_jit_param@w{ }*param) Upcasting from param to lvalue. @end deffn @geindex gcc_jit_param_as_rvalue (C function) -@anchor{topics/functions gcc_jit_param_as_rvalue}@anchor{cf} +@anchor{topics/functions gcc_jit_param_as_rvalue}@anchor{d0} @deffn {C Function} gcc_jit_rvalue * gcc_jit_param_as_rvalue (gcc_jit_param@w{ }*param) Upcasting from param to rvalue. @end deffn @geindex gcc_jit_param_as_object (C function) -@anchor{topics/functions gcc_jit_param_as_object}@anchor{d0} +@anchor{topics/functions gcc_jit_param_as_object}@anchor{d1} @deffn {C Function} gcc_jit_object * gcc_jit_param_as_object (gcc_jit_param@w{ }*param) Upcasting from param to object. @end deffn @node Functions,Blocks,Params,Creating and using functions -@anchor{topics/functions functions}@anchor{d1} +@anchor{topics/functions functions}@anchor{d2} @subsection Functions @@ -7510,7 +7526,7 @@ creating ourselves, or one that we're referencing. Create a gcc_jit_function with the given name and parameters. @geindex gcc_jit_function_kind (C type) -@anchor{topics/functions gcc_jit_function_kind}@anchor{d2} +@anchor{topics/functions gcc_jit_function_kind}@anchor{d3} @deffn {C Type} enum gcc_jit_function_kind @end deffn @@ -7520,7 +7536,7 @@ values: @quotation @geindex GCC_JIT_FUNCTION_EXPORTED (C macro) -@anchor{topics/functions GCC_JIT_FUNCTION_EXPORTED}@anchor{d3} +@anchor{topics/functions GCC_JIT_FUNCTION_EXPORTED}@anchor{d4} @deffn {C Macro} GCC_JIT_FUNCTION_EXPORTED Function is defined by the client code and visible @@ -7532,7 +7548,7 @@ for this function from a @pxref{16,,gcc_jit_result} via @end deffn @geindex GCC_JIT_FUNCTION_INTERNAL (C macro) -@anchor{topics/functions GCC_JIT_FUNCTION_INTERNAL}@anchor{d4} +@anchor{topics/functions GCC_JIT_FUNCTION_INTERNAL}@anchor{d5} @deffn {C Macro} GCC_JIT_FUNCTION_INTERNAL Function is defined by the client code, but is invisible @@ -7540,7 +7556,7 @@ outside of the JIT. Analogous to a "static" function. @end deffn @geindex GCC_JIT_FUNCTION_IMPORTED (C macro) -@anchor{topics/functions GCC_JIT_FUNCTION_IMPORTED}@anchor{d5} +@anchor{topics/functions GCC_JIT_FUNCTION_IMPORTED}@anchor{d6} @deffn {C Macro} GCC_JIT_FUNCTION_IMPORTED Function is not defined by the client code; we're merely @@ -7549,7 +7565,7 @@ header file. @end deffn @geindex GCC_JIT_FUNCTION_ALWAYS_INLINE (C macro) -@anchor{topics/functions GCC_JIT_FUNCTION_ALWAYS_INLINE}@anchor{d6} +@anchor{topics/functions GCC_JIT_FUNCTION_ALWAYS_INLINE}@anchor{d7} @deffn {C Macro} GCC_JIT_FUNCTION_ALWAYS_INLINE Function is only ever inlined into other functions, and is @@ -7570,19 +7586,19 @@ buffer. @end deffn @geindex gcc_jit_context_get_builtin_function (C function) -@anchor{topics/functions gcc_jit_context_get_builtin_function}@anchor{d7} +@anchor{topics/functions gcc_jit_context_get_builtin_function}@anchor{d8} @deffn {C Function} gcc_jit_function *gcc_jit_context_get_builtin_function (gcc_jit_context@w{ }*ctxt, const char@w{ }*name) @end deffn @geindex gcc_jit_function_as_object (C function) -@anchor{topics/functions gcc_jit_function_as_object}@anchor{d8} +@anchor{topics/functions gcc_jit_function_as_object}@anchor{d9} @deffn {C Function} gcc_jit_object * gcc_jit_function_as_object (gcc_jit_function@w{ }*func) Upcasting from function to object. @end deffn @geindex gcc_jit_function_get_param (C function) -@anchor{topics/functions gcc_jit_function_get_param}@anchor{d9} +@anchor{topics/functions gcc_jit_function_get_param}@anchor{da} @deffn {C Function} gcc_jit_param * gcc_jit_function_get_param (gcc_jit_function@w{ }*func, int@w{ }index) Get the param of the given index (0-based). @@ -7608,7 +7624,7 @@ buffer. @end deffn @node Blocks,Statements,Functions,Creating and using functions -@anchor{topics/functions blocks}@anchor{da} +@anchor{topics/functions blocks}@anchor{db} @subsection Blocks @@ -7632,7 +7648,7 @@ one function. @end deffn @geindex gcc_jit_function_new_block (C function) -@anchor{topics/functions gcc_jit_function_new_block}@anchor{db} +@anchor{topics/functions gcc_jit_function_new_block}@anchor{dc} @deffn {C Function} gcc_jit_block * gcc_jit_function_new_block (gcc_jit_function@w{ }*func, const char@w{ }*name) Create a basic block of the given name. The name may be NULL, but @@ -7654,26 +7670,26 @@ for (pc = 0; pc < fn->fn_num_ops; pc++) @end deffn @geindex gcc_jit_block_as_object (C function) -@anchor{topics/functions gcc_jit_block_as_object}@anchor{dc} +@anchor{topics/functions gcc_jit_block_as_object}@anchor{dd} @deffn {C Function} gcc_jit_object * gcc_jit_block_as_object (gcc_jit_block@w{ }*block) Upcast from block to object. @end deffn @geindex gcc_jit_block_get_function (C function) -@anchor{topics/functions gcc_jit_block_get_function}@anchor{dd} +@anchor{topics/functions gcc_jit_block_get_function}@anchor{de} @deffn {C Function} gcc_jit_function * gcc_jit_block_get_function (gcc_jit_block@w{ }*block) Which function is this block within? @end deffn @node Statements,,Blocks,Creating and using functions -@anchor{topics/functions statements}@anchor{de} +@anchor{topics/functions statements}@anchor{df} @subsection Statements @geindex gcc_jit_block_add_eval (C function) -@anchor{topics/functions gcc_jit_block_add_eval}@anchor{b2} +@anchor{topics/functions gcc_jit_block_add_eval}@anchor{b4} @deffn {C Function} void gcc_jit_block_add_eval (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*rvalue) Add evaluation of an rvalue, discarding the result @@ -7782,7 +7798,7 @@ block, boolval, on_true, and on_false must be non-NULL. @end deffn @geindex gcc_jit_block_end_with_jump (C function) -@anchor{topics/functions gcc_jit_block_end_with_jump}@anchor{df} +@anchor{topics/functions gcc_jit_block_end_with_jump}@anchor{e0} @deffn {C Function} void gcc_jit_block_end_with_jump (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_block@w{ }*target) Terminate a block by adding a jump to the given target block. @@ -7797,7 +7813,7 @@ goto target; @end deffn @geindex gcc_jit_block_end_with_return (C function) -@anchor{topics/functions gcc_jit_block_end_with_return}@anchor{e0} +@anchor{topics/functions gcc_jit_block_end_with_return}@anchor{e1} @deffn {C Function} void gcc_jit_block_end_with_return (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*rvalue) Terminate a block by adding evaluation of an rvalue, returning the value. @@ -7812,7 +7828,7 @@ return expression; @end deffn @geindex gcc_jit_block_end_with_void_return (C function) -@anchor{topics/functions gcc_jit_block_end_with_void_return}@anchor{e1} +@anchor{topics/functions gcc_jit_block_end_with_void_return}@anchor{e2} @deffn {C Function} void gcc_jit_block_end_with_void_return (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc) Terminate a block by adding a valueless return, for use within a function @@ -7828,7 +7844,7 @@ return; @end deffn @geindex gcc_jit_block_end_with_switch (C function) -@anchor{topics/functions gcc_jit_block_end_with_switch}@anchor{e2} +@anchor{topics/functions gcc_jit_block_end_with_switch}@anchor{e3} @deffn {C Function} void gcc_jit_block_end_with_switch (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*expr, gcc_jit_block@w{ }*default_block, int@w{ }num_cases, gcc_jit_case@w{ }**cases) Terminate a block by adding evalation of an rvalue, then performing @@ -7876,17 +7892,17 @@ The API entrypoints relating to switch statements and cases: @itemize * @item -@pxref{e2,,gcc_jit_block_end_with_switch()} +@pxref{e3,,gcc_jit_block_end_with_switch()} @item -@pxref{e3,,gcc_jit_case_as_object()} +@pxref{e4,,gcc_jit_case_as_object()} @item -@pxref{e4,,gcc_jit_context_new_case()} +@pxref{e5,,gcc_jit_context_new_case()} @end itemize @end quotation -were added in @pxref{e5,,LIBGCCJIT_ABI_3}; you can test for their presence +were added in @pxref{e6,,LIBGCCJIT_ABI_3}; you can test for their presence using @example @@ -7896,20 +7912,20 @@ using @noindent @geindex gcc_jit_case (C type) -@anchor{topics/functions gcc_jit_case}@anchor{e6} +@anchor{topics/functions gcc_jit_case}@anchor{e7} @deffn {C Type} gcc_jit_case @end deffn A @cite{gcc_jit_case} represents a case within a switch statement, and is created within a particular @pxref{8,,gcc_jit_context} using -@pxref{e4,,gcc_jit_context_new_case()}. +@pxref{e5,,gcc_jit_context_new_case()}. Each case expresses a multivalued range of integer values. You can express single-valued cases by passing in the same value for both @cite{min_value} and @cite{max_value}. @geindex gcc_jit_context_new_case (C function) -@anchor{topics/functions gcc_jit_context_new_case}@anchor{e4} +@anchor{topics/functions gcc_jit_context_new_case}@anchor{e5} @deffn {C Function} gcc_jit_case * gcc_jit_context_new_case (gcc_jit_context@w{ }*ctxt, gcc_jit_rvalue@w{ }*min_value, gcc_jit_rvalue@w{ }*max_value, gcc_jit_block@w{ }*dest_block) Create a new gcc_jit_case instance for use in a switch statement. @@ -7921,7 +7937,7 @@ statement. @end deffn @geindex gcc_jit_case_as_object (C function) -@anchor{topics/functions gcc_jit_case_as_object}@anchor{e3} +@anchor{topics/functions gcc_jit_case_as_object}@anchor{e4} @deffn {C Function} gcc_jit_object * gcc_jit_case_as_object (gcc_jit_case@w{ }*case_) Upcast from a case to an object. @@ -8038,6 +8054,89 @@ create_code (gcc_jit_context *ctxt, void *user_data) @end quotation @end deffn +@c Copyright (C) 2017 Free Software Foundation, Inc. +@c Originally contributed by David Malcolm +@c +@c This is free software: you can redistribute it and/or modify it +@c under the terms of the GNU General Public License as published by +@c the Free Software Foundation, either version 3 of the License, or +@c (at your option) any later version. +@c +@c This program is distributed in the hope that it will be useful, but +@c WITHOUT ANY WARRANTY; without even the implied warranty of +@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +@c General Public License for more details. +@c +@c You should have received a copy of the GNU General Public License +@c along with this program. If not, see +@c . + +@node Function pointers<2>,Source Locations,Creating and using functions,Topic Reference +@anchor{topics/function-pointers doc}@anchor{e8}@anchor{topics/function-pointers function-pointers}@anchor{e9} +@section Function pointers + + +You can generate calls that use a function pointer via +@pxref{b5,,gcc_jit_context_new_call_through_ptr()}. + +To do requires a @pxref{13,,gcc_jit_rvalue} of the correct function pointer type. + +Function pointers for a @pxref{29,,gcc_jit_function} can be obtained +via @pxref{b9,,gcc_jit_function_get_address()}. + +@geindex gcc_jit_function_get_address (C function) +@anchor{topics/function-pointers gcc_jit_function_get_address}@anchor{b9} +@deffn {C Function} gcc_jit_rvalue * gcc_jit_function_get_address (gcc_jit_function@w{ }*fn, gcc_jit_location@w{ }*loc) + +Get the address of a function as an rvalue, of function pointer +type. + +This entrypoint was added in @pxref{ea,,LIBGCCJIT_ABI_9}; you can test +for its presence using + +@example +#ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address +@end example + +@noindent +@end deffn + +Alternatively, given an existing function, you can obtain a pointer +to it in @pxref{13,,gcc_jit_rvalue} form using +@pxref{97,,gcc_jit_context_new_rvalue_from_ptr()}, using a function pointer +type obtained using @pxref{90,,gcc_jit_context_new_function_ptr_type()}. + +Here's an example of creating a function pointer type corresponding to C's +@code{void (*) (int, int, int)}: + +@example +gcc_jit_type *void_type = + gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_VOID); +gcc_jit_type *int_type = + gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT); + +/* Build the function ptr type. */ +gcc_jit_type *param_types[3]; +param_types[0] = int_type; +param_types[1] = int_type; +param_types[2] = int_type; + +gcc_jit_type *fn_ptr_type = + gcc_jit_context_new_function_ptr_type (ctxt, NULL, + void_type, + 3, param_types, 0); +@end example + +@noindent + +@geindex gcc_jit_context_new_function_ptr_type (C function) +@anchor{topics/function-pointers gcc_jit_context_new_function_ptr_type}@anchor{90} +@deffn {C Function} gcc_jit_type * gcc_jit_context_new_function_ptr_type (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*return_type, int@w{ }num_params, gcc_jit_type@w{ }**param_types, int@w{ }is_variadic) + +Generate a @pxref{a,,gcc_jit_type} for a function pointer with the +given return type and parameters. +@end deffn + @c Copyright (C) 2014-2017 Free Software Foundation, Inc. @c Originally contributed by David Malcolm @c @@ -8055,8 +8154,8 @@ create_code (gcc_jit_context *ctxt, void *user_data) @c along with this program. If not, see @c . -@node Source Locations,Compiling a context,Creating and using functions,Topic Reference -@anchor{topics/locations source-locations}@anchor{e7}@anchor{topics/locations doc}@anchor{e8} +@node Source Locations,Compiling a context,Function pointers<2>,Topic Reference +@anchor{topics/locations source-locations}@anchor{eb}@anchor{topics/locations doc}@anchor{ec} @section Source Locations @@ -8106,7 +8205,7 @@ on-stack buffer. @end menu @node Faking it,,,Source Locations -@anchor{topics/locations faking-it}@anchor{e9} +@anchor{topics/locations faking-it}@anchor{ed} @subsection Faking it @@ -8144,7 +8243,7 @@ file, giving you @emph{something} you can step through in the debugger. @c . @node Compiling a context,ABI and API compatibility,Source Locations,Topic Reference -@anchor{topics/compilation compiling-a-context}@anchor{ea}@anchor{topics/compilation doc}@anchor{eb} +@anchor{topics/compilation compiling-a-context}@anchor{ee}@anchor{topics/compilation doc}@anchor{ef} @section Compiling a context @@ -8163,7 +8262,7 @@ prevent any future compilation of that context. @end menu @node In-memory compilation,Ahead-of-time compilation,,Compiling a context -@anchor{topics/compilation in-memory-compilation}@anchor{ec} +@anchor{topics/compilation in-memory-compilation}@anchor{f0} @subsection In-memory compilation @@ -8198,7 +8297,7 @@ Functions are looked up by name. For this to succeed, a function with a name matching @cite{funcname} must have been created on @cite{result}'s context (or a parent context) via a call to @pxref{11,,gcc_jit_context_new_function()} with @cite{kind} -@pxref{d3,,GCC_JIT_FUNCTION_EXPORTED}: +@pxref{d4,,GCC_JIT_FUNCTION_EXPORTED}: @example gcc_jit_context_new_function (ctxt, @@ -8228,7 +8327,7 @@ to a segmentation fault. @end deffn @geindex gcc_jit_result_get_global (C function) -@anchor{topics/compilation gcc_jit_result_get_global}@anchor{c3} +@anchor{topics/compilation gcc_jit_result_get_global}@anchor{c4} @deffn {C Function} void * gcc_jit_result_get_global (gcc_jit_result@w{ }*result, const char@w{ }*name) Locate a given global within the built machine code. @@ -8236,8 +8335,8 @@ Locate a given global within the built machine code. Globals are looked up by name. For this to succeed, a global with a name matching @cite{name} must have been created on @cite{result}'s context (or a parent context) via a call to -@pxref{c0,,gcc_jit_context_new_global()} with @cite{kind} -@pxref{c2,,GCC_JIT_GLOBAL_EXPORTED}. +@pxref{c1,,gcc_jit_context_new_global()} with @cite{kind} +@pxref{c3,,GCC_JIT_GLOBAL_EXPORTED}. If the global is found, the result will need to be cast to a pointer of the correct type before it can be called. @@ -8285,11 +8384,11 @@ Once we're done with the code, this unloads the built .so file. This cleans up the result; after calling this, it's no longer valid to use the result, or any code or globals that were obtained by calling @pxref{17,,gcc_jit_result_get_code()} or -@pxref{c3,,gcc_jit_result_get_global()} on it. +@pxref{c4,,gcc_jit_result_get_global()} on it. @end deffn @node Ahead-of-time compilation,,In-memory compilation,Compiling a context -@anchor{topics/compilation ahead-of-time-compilation}@anchor{ed} +@anchor{topics/compilation ahead-of-time-compilation}@anchor{f1} @subsection Ahead-of-time compilation @@ -8318,7 +8417,7 @@ suffix of the output file when determining what to do. @end cartouche @geindex gcc_jit_output_kind (C type) -@anchor{topics/compilation gcc_jit_output_kind}@anchor{ee} +@anchor{topics/compilation gcc_jit_output_kind}@anchor{f2} @deffn {C Type} enum gcc_jit_output_kind @end deffn @@ -8336,7 +8435,7 @@ Typical suffix @item -@pxref{ef,,GCC_JIT_OUTPUT_KIND_ASSEMBLER} +@pxref{f3,,GCC_JIT_OUTPUT_KIND_ASSEMBLER} @tab @@ -8344,7 +8443,7 @@ Typical suffix @item -@pxref{f0,,GCC_JIT_OUTPUT_KIND_OBJECT_FILE} +@pxref{f4,,GCC_JIT_OUTPUT_KIND_OBJECT_FILE} @tab @@ -8352,7 +8451,7 @@ Typical suffix @item -@pxref{f1,,GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY} +@pxref{f5,,GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY} @tab @@ -8360,7 +8459,7 @@ Typical suffix @item -@pxref{f2,,GCC_JIT_OUTPUT_KIND_EXECUTABLE} +@pxref{f6,,GCC_JIT_OUTPUT_KIND_EXECUTABLE} @tab @@ -8370,21 +8469,21 @@ None, or .exe @geindex GCC_JIT_OUTPUT_KIND_ASSEMBLER (C macro) -@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_ASSEMBLER}@anchor{ef} +@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_ASSEMBLER}@anchor{f3} @deffn {C Macro} GCC_JIT_OUTPUT_KIND_ASSEMBLER Compile the context to an assembler file. @end deffn @geindex GCC_JIT_OUTPUT_KIND_OBJECT_FILE (C macro) -@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_OBJECT_FILE}@anchor{f0} +@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_OBJECT_FILE}@anchor{f4} @deffn {C Macro} GCC_JIT_OUTPUT_KIND_OBJECT_FILE Compile the context to an object file. @end deffn @geindex GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY (C macro) -@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY}@anchor{f1} +@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY}@anchor{f5} @deffn {C Macro} GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY Compile the context to a dynamic library. @@ -8394,7 +8493,7 @@ against. @end deffn @geindex GCC_JIT_OUTPUT_KIND_EXECUTABLE (C macro) -@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_EXECUTABLE}@anchor{f2} +@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_EXECUTABLE}@anchor{f6} @deffn {C Macro} GCC_JIT_OUTPUT_KIND_EXECUTABLE Compile the context to an executable. @@ -8421,7 +8520,7 @@ against. @c . @node ABI and API compatibility,Performance,Compiling a context,Topic Reference -@anchor{topics/compatibility abi-and-api-compatibility}@anchor{f3}@anchor{topics/compatibility doc}@anchor{f4} +@anchor{topics/compatibility abi-and-api-compatibility}@anchor{f7}@anchor{topics/compatibility doc}@anchor{f8} @section ABI and API compatibility @@ -8494,7 +8593,7 @@ ABI symbol tags @node ABI symbol tags,,,ABI and API compatibility -@anchor{topics/compatibility abi-symbol-tags}@anchor{f5} +@anchor{topics/compatibility abi-symbol-tags}@anchor{f9} @subsection ABI symbol tags @@ -8517,7 +8616,7 @@ Newer releases use the following tags. @end menu @node LIBGCCJIT_ABI_0,LIBGCCJIT_ABI_1,,ABI symbol tags -@anchor{topics/compatibility libgccjit-abi-0}@anchor{f6}@anchor{topics/compatibility id1}@anchor{f7} +@anchor{topics/compatibility libgccjit-abi-0}@anchor{fa}@anchor{topics/compatibility id1}@anchor{fb} @subsubsection @code{LIBGCCJIT_ABI_0} @@ -8529,7 +8628,7 @@ continue to work, with this being handled transparently by the linker (see this post@footnote{https://gcc.gnu.org/ml/gcc-patches/2015-06/msg02126.html}) @node LIBGCCJIT_ABI_1,LIBGCCJIT_ABI_2,LIBGCCJIT_ABI_0,ABI symbol tags -@anchor{topics/compatibility libgccjit-abi-1}@anchor{73}@anchor{topics/compatibility id2}@anchor{f8} +@anchor{topics/compatibility libgccjit-abi-1}@anchor{73}@anchor{topics/compatibility id2}@anchor{fc} @subsubsection @code{LIBGCCJIT_ABI_1} @@ -8537,7 +8636,7 @@ continue to work, with this being handled transparently by the linker @pxref{72,,gcc_jit_context_add_command_line_option()} @node LIBGCCJIT_ABI_2,LIBGCCJIT_ABI_3,LIBGCCJIT_ABI_1,ABI symbol tags -@anchor{topics/compatibility libgccjit-abi-2}@anchor{6c}@anchor{topics/compatibility id3}@anchor{f9} +@anchor{topics/compatibility libgccjit-abi-2}@anchor{6c}@anchor{topics/compatibility id3}@anchor{fd} @subsubsection @code{LIBGCCJIT_ABI_2} @@ -8545,7 +8644,7 @@ continue to work, with this being handled transparently by the linker @pxref{6b,,gcc_jit_context_set_bool_allow_unreachable_blocks()} @node LIBGCCJIT_ABI_3,LIBGCCJIT_ABI_4,LIBGCCJIT_ABI_2,ABI symbol tags -@anchor{topics/compatibility libgccjit-abi-3}@anchor{e5}@anchor{topics/compatibility id4}@anchor{fa} +@anchor{topics/compatibility libgccjit-abi-3}@anchor{e6}@anchor{topics/compatibility id4}@anchor{fe} @subsubsection @code{LIBGCCJIT_ABI_3} @@ -8558,18 +8657,18 @@ entrypoints: @itemize * @item -@pxref{e2,,gcc_jit_block_end_with_switch()} +@pxref{e3,,gcc_jit_block_end_with_switch()} @item -@pxref{e3,,gcc_jit_case_as_object()} +@pxref{e4,,gcc_jit_case_as_object()} @item -@pxref{e4,,gcc_jit_context_new_case()} +@pxref{e5,,gcc_jit_context_new_case()} @end itemize @end quotation @node LIBGCCJIT_ABI_4,LIBGCCJIT_ABI_5,LIBGCCJIT_ABI_3,ABI symbol tags -@anchor{topics/compatibility id5}@anchor{fb}@anchor{topics/compatibility libgccjit-abi-4}@anchor{fc} +@anchor{topics/compatibility id5}@anchor{ff}@anchor{topics/compatibility libgccjit-abi-4}@anchor{100} @subsubsection @code{LIBGCCJIT_ABI_4} @@ -8582,30 +8681,30 @@ entrypoints: @itemize * @item -@pxref{fd,,gcc_jit_context_get_timer()} +@pxref{101,,gcc_jit_context_get_timer()} @item -@pxref{fe,,gcc_jit_context_set_timer()} +@pxref{102,,gcc_jit_context_set_timer()} @item -@pxref{ff,,gcc_jit_timer_new()} +@pxref{103,,gcc_jit_timer_new()} @item -@pxref{100,,gcc_jit_timer_release()} +@pxref{104,,gcc_jit_timer_release()} @item -@pxref{101,,gcc_jit_timer_push()} +@pxref{105,,gcc_jit_timer_push()} @item -@pxref{102,,gcc_jit_timer_pop()} +@pxref{106,,gcc_jit_timer_pop()} @item -@pxref{103,,gcc_jit_timer_print()} +@pxref{107,,gcc_jit_timer_print()} @end itemize @end quotation @node LIBGCCJIT_ABI_5,LIBGCCJIT_ABI_6,LIBGCCJIT_ABI_4,ABI symbol tags -@anchor{topics/compatibility id6}@anchor{104}@anchor{topics/compatibility libgccjit-abi-5}@anchor{6e} +@anchor{topics/compatibility id6}@anchor{108}@anchor{topics/compatibility libgccjit-abi-5}@anchor{6e} @subsubsection @code{LIBGCCJIT_ABI_5} @@ -8613,15 +8712,15 @@ entrypoints: @pxref{6d,,gcc_jit_context_set_bool_use_external_driver()} @node LIBGCCJIT_ABI_6,LIBGCCJIT_ABI_7,LIBGCCJIT_ABI_5,ABI symbol tags -@anchor{topics/compatibility id7}@anchor{105}@anchor{topics/compatibility libgccjit-abi-6}@anchor{b5} +@anchor{topics/compatibility id7}@anchor{109}@anchor{topics/compatibility libgccjit-abi-6}@anchor{b7} @subsubsection @code{LIBGCCJIT_ABI_6} @code{LIBGCCJIT_ABI_6} covers the addition of -@pxref{b4,,gcc_jit_rvalue_set_bool_require_tail_call()} +@pxref{b6,,gcc_jit_rvalue_set_bool_require_tail_call()} @node LIBGCCJIT_ABI_7,LIBGCCJIT_ABI_8,LIBGCCJIT_ABI_6,ABI symbol tags -@anchor{topics/compatibility libgccjit-abi-7}@anchor{81}@anchor{topics/compatibility id8}@anchor{106} +@anchor{topics/compatibility libgccjit-abi-7}@anchor{81}@anchor{topics/compatibility id8}@anchor{10a} @subsubsection @code{LIBGCCJIT_ABI_7} @@ -8629,7 +8728,7 @@ entrypoints: @pxref{80,,gcc_jit_type_get_aligned()} @node LIBGCCJIT_ABI_8,LIBGCCJIT_ABI_9,LIBGCCJIT_ABI_7,ABI symbol tags -@anchor{topics/compatibility libgccjit-abi-8}@anchor{84}@anchor{topics/compatibility id9}@anchor{107} +@anchor{topics/compatibility libgccjit-abi-8}@anchor{84}@anchor{topics/compatibility id9}@anchor{10b} @subsubsection @code{LIBGCCJIT_ABI_8} @@ -8637,12 +8736,12 @@ entrypoints: @pxref{83,,gcc_jit_type_get_vector()} @node LIBGCCJIT_ABI_9,,LIBGCCJIT_ABI_8,ABI symbol tags -@anchor{topics/compatibility id10}@anchor{108}@anchor{topics/compatibility libgccjit-abi-9}@anchor{b8} +@anchor{topics/compatibility id10}@anchor{10c}@anchor{topics/compatibility libgccjit-abi-9}@anchor{ea} @subsubsection @code{LIBGCCJIT_ABI_9} @code{LIBGCCJIT_ABI_9} covers the addition of -@pxref{b7,,gcc_jit_function_get_address()} +@pxref{b9,,gcc_jit_function_get_address()} @c Copyright (C) 2015-2017 Free Software Foundation, Inc. @c Originally contributed by David Malcolm @@ -8662,7 +8761,7 @@ entrypoints: @c . @node Performance,,ABI and API compatibility,Topic Reference -@anchor{topics/performance performance}@anchor{109}@anchor{topics/performance doc}@anchor{10a} +@anchor{topics/performance performance}@anchor{10d}@anchor{topics/performance doc}@anchor{10e} @section Performance @@ -8672,14 +8771,14 @@ entrypoints: @end menu @node The timing API,,,Performance -@anchor{topics/performance the-timing-api}@anchor{10b} +@anchor{topics/performance the-timing-api}@anchor{10f} @subsection The timing API As of GCC 6, libgccjit exposes a timing API, for printing reports on how long was spent in different parts of code. -You can create a @pxref{10c,,gcc_jit_timer} instance, which will +You can create a @pxref{110,,gcc_jit_timer} instance, which will measure time spent since its creation. The timer maintains a stack of "timer items": as control flow moves through your code, you can push and pop named items relating to your code onto the stack, and the timer @@ -8781,7 +8880,7 @@ Client items: The exact format is intended to be human-readable, and is subject to change. @geindex LIBGCCJIT_HAVE_TIMING_API (C macro) -@anchor{topics/performance LIBGCCJIT_HAVE_TIMING_API}@anchor{10d} +@anchor{topics/performance LIBGCCJIT_HAVE_TIMING_API}@anchor{111} @deffn {C Macro} LIBGCCJIT_HAVE_TIMING_API The timer API was added to libgccjit in GCC 6. @@ -8800,15 +8899,15 @@ gcc_jit_context_set_timer (ctxt, t); @end deffn @geindex gcc_jit_timer (C type) -@anchor{topics/performance gcc_jit_timer}@anchor{10c} +@anchor{topics/performance gcc_jit_timer}@anchor{110} @deffn {C Type} gcc_jit_timer @end deffn @geindex gcc_jit_timer_new (C function) -@anchor{topics/performance gcc_jit_timer_new}@anchor{ff} +@anchor{topics/performance gcc_jit_timer_new}@anchor{103} @deffn {C Function} gcc_jit_timer * gcc_jit_timer_new (void) -Create a @pxref{10c,,gcc_jit_timer} instance, and start timing: +Create a @pxref{110,,gcc_jit_timer} instance, and start timing: @example gcc_jit_timer *t = gcc_jit_timer_new (); @@ -8816,7 +8915,7 @@ gcc_jit_timer *t = gcc_jit_timer_new (); @noindent -This API entrypoint was added in @pxref{fc,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @pxref{100,,LIBGCCJIT_ABI_4}; you can test for its presence using @example @@ -8827,10 +8926,10 @@ for its presence using @end deffn @geindex gcc_jit_timer_release (C function) -@anchor{topics/performance gcc_jit_timer_release}@anchor{100} +@anchor{topics/performance gcc_jit_timer_release}@anchor{104} @deffn {C Function} void gcc_jit_timer_release (gcc_jit_timer@w{ }*timer) -Release a @pxref{10c,,gcc_jit_timer} instance: +Release a @pxref{110,,gcc_jit_timer} instance: @example gcc_jit_timer_release (t); @@ -8840,7 +8939,7 @@ gcc_jit_timer_release (t); This should be called exactly once on a timer. -This API entrypoint was added in @pxref{fc,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @pxref{100,,LIBGCCJIT_ABI_4}; you can test for its presence using @example @@ -8851,10 +8950,10 @@ for its presence using @end deffn @geindex gcc_jit_context_set_timer (C function) -@anchor{topics/performance gcc_jit_context_set_timer}@anchor{fe} +@anchor{topics/performance gcc_jit_context_set_timer}@anchor{102} @deffn {C Function} void gcc_jit_context_set_timer (gcc_jit_context@w{ }*ctxt, gcc_jit_timer@w{ }*timer) -Associate a @pxref{10c,,gcc_jit_timer} instance with a context: +Associate a @pxref{110,,gcc_jit_timer} instance with a context: @example gcc_jit_context_set_timer (ctxt, t); @@ -8869,7 +8968,7 @@ Timers have no locking, so if you have a multithreaded program, you must provide your own locks if more than one thread could be working with the same timer via timer-associated contexts. -This API entrypoint was added in @pxref{fc,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @pxref{100,,LIBGCCJIT_ABI_4}; you can test for its presence using @example @@ -8880,12 +8979,12 @@ for its presence using @end deffn @geindex gcc_jit_context_get_timer (C function) -@anchor{topics/performance gcc_jit_context_get_timer}@anchor{fd} +@anchor{topics/performance gcc_jit_context_get_timer}@anchor{101} @deffn {C Function} gcc_jit_timer *gcc_jit_context_get_timer (gcc_jit_context@w{ }*ctxt) Get the timer associated with a context (if any). -This API entrypoint was added in @pxref{fc,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @pxref{100,,LIBGCCJIT_ABI_4}; you can test for its presence using @example @@ -8896,7 +8995,7 @@ for its presence using @end deffn @geindex gcc_jit_timer_push (C function) -@anchor{topics/performance gcc_jit_timer_push}@anchor{101} +@anchor{topics/performance gcc_jit_timer_push}@anchor{105} @deffn {C Function} void gcc_jit_timer_push (gcc_jit_timer@w{ }*timer, const char@w{ }*item_name) Push the given item onto the timer's stack: @@ -8909,7 +9008,7 @@ gcc_jit_timer_pop (t, "running code"); @noindent -This API entrypoint was added in @pxref{fc,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @pxref{100,,LIBGCCJIT_ABI_4}; you can test for its presence using @example @@ -8920,7 +9019,7 @@ for its presence using @end deffn @geindex gcc_jit_timer_pop (C function) -@anchor{topics/performance gcc_jit_timer_pop}@anchor{102} +@anchor{topics/performance gcc_jit_timer_pop}@anchor{106} @deffn {C Function} void gcc_jit_timer_pop (gcc_jit_timer@w{ }*timer, const char@w{ }*item_name) Pop the top item from the timer's stack. @@ -8928,7 +9027,7 @@ Pop the top item from the timer's stack. If "item_name" is provided, it must match that of the top item. Alternatively, @code{NULL} can be passed in, to suppress checking. -This API entrypoint was added in @pxref{fc,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @pxref{100,,LIBGCCJIT_ABI_4}; you can test for its presence using @example @@ -8939,13 +9038,13 @@ for its presence using @end deffn @geindex gcc_jit_timer_print (C function) -@anchor{topics/performance gcc_jit_timer_print}@anchor{103} +@anchor{topics/performance gcc_jit_timer_print}@anchor{107} @deffn {C Function} void gcc_jit_timer_print (gcc_jit_timer@w{ }*timer, FILE@w{ }*f_out) Print timing information to the given stream about activity since the timer was started. -This API entrypoint was added in @pxref{fc,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @pxref{100,,LIBGCCJIT_ABI_4}; you can test for its presence using @example @@ -8973,7 +9072,7 @@ for its presence using @c . @node C++ bindings for libgccjit,Internals,Topic Reference,Top -@anchor{cp/index c-bindings-for-libgccjit}@anchor{10e}@anchor{cp/index doc}@anchor{10f} +@anchor{cp/index c-bindings-for-libgccjit}@anchor{112}@anchor{cp/index doc}@anchor{113} @chapter C++ bindings for libgccjit @@ -9096,7 +9195,7 @@ Rvalues * Binary Operations: Binary Operations<2>. * Comparisons: Comparisons<2>. * Function calls: Function calls<2>. -* Function pointers: Function pointers<2>. +* Function pointers: Function pointers<3>. * Type-coercion: Type-coercion<2>. Lvalues @@ -9123,7 +9222,7 @@ Compiling a context @node Tutorial<2>,Topic Reference<2>,,C++ bindings for libgccjit -@anchor{cp/intro/index doc}@anchor{110}@anchor{cp/intro/index tutorial}@anchor{111} +@anchor{cp/intro/index doc}@anchor{114}@anchor{cp/intro/index tutorial}@anchor{115} @section Tutorial @@ -9153,7 +9252,7 @@ Compiling a context @end menu @node Tutorial part 1 "Hello world"<2>,Tutorial part 2 Creating a trivial machine code function<2>,,Tutorial<2> -@anchor{cp/intro/tutorial01 doc}@anchor{112}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{113} +@anchor{cp/intro/tutorial01 doc}@anchor{116}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{117} @subsection Tutorial part 1: "Hello world" @@ -9323,7 +9422,7 @@ hello world @c . @node Tutorial part 2 Creating a trivial machine code function<2>,Tutorial part 3 Loops and variables<2>,Tutorial part 1 "Hello world"<2>,Tutorial<2> -@anchor{cp/intro/tutorial02 doc}@anchor{114}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{115} +@anchor{cp/intro/tutorial02 doc}@anchor{118}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{119} @subsection Tutorial part 2: Creating a trivial machine code function @@ -9352,7 +9451,7 @@ All state associated with compilation is associated with a @code{gccjit::context}, which is a thin C++ wrapper around the C API's @pxref{8,,gcc_jit_context *}. -Create one using @pxref{116,,gccjit;;context;;acquire()}: +Create one using @pxref{11a,,gccjit;;context;;acquire()}: @example gccjit::context ctxt; @@ -9365,7 +9464,7 @@ The JIT library has a system of types. It is statically-typed: every expression is of a specific type, fixed at compile-time. In our example, all of the expressions are of the C @cite{int} type, so let's obtain this from the context, as a @code{gccjit::type}, using -@pxref{117,,gccjit;;context;;get_type()}: +@pxref{11b,,gccjit;;context;;get_type()}: @example gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT); @@ -9378,7 +9477,7 @@ entity in the API is associated with a @code{gccjit::context}. Memory management is easy: all such "contextual" objects are automatically cleaned up for you when the context is released, using -@pxref{118,,gccjit;;context;;release()}: +@pxref{11c,,gccjit;;context;;release()}: @example ctxt.release (); @@ -9411,7 +9510,7 @@ The C++ class hierarchy within the @code{gccjit} namespace looks like this: One thing you can do with a @code{gccjit::object} is to ask it for a human-readable description as a @code{std::string}, using -@pxref{119,,gccjit;;object;;get_debug_string()}: +@pxref{11d,,gccjit;;object;;get_debug_string()}: @example printf ("obj: %s\n", obj.get_debug_string ().c_str ()); @@ -9431,7 +9530,7 @@ This is invaluable when debugging. Let's create the function. To do so, we first need to construct its single parameter, specifying its type and giving it a name, -using @pxref{11a,,gccjit;;context;;new_param()}: +using @pxref{11e,,gccjit;;context;;new_param()}: @example gccjit::param param_i = ctxt.new_param (int_type, "i"); @@ -9480,7 +9579,7 @@ gccjit::block block = func.new_block (); Our basic block is relatively simple: it immediately terminates by returning the value of an expression. -We can build the expression using @pxref{11b,,gccjit;;context;;new_binary_op()}: +We can build the expression using @pxref{11f,,gccjit;;context;;new_binary_op()}: @example gccjit::rvalue expr = @@ -9493,7 +9592,7 @@ gccjit::rvalue expr = A @code{gccjit::rvalue} is another example of a @code{gccjit::object} subclass. As before, we can print it with -@pxref{119,,gccjit;;object;;get_debug_string()}. +@pxref{11d,,gccjit;;object;;get_debug_string()}. @example printf ("expr: %s\n", expr.get_debug_string ().c_str ()); @@ -9530,7 +9629,7 @@ block.end_with_return (expr); @noindent OK, we've populated the context. We can now compile it using -@pxref{11c,,gccjit;;context;;compile()}: +@pxref{120,,gccjit;;context;;compile()}: @example gcc_jit_result *result; @@ -9580,12 +9679,12 @@ result: 25 @end menu @node Options<3>,Full example<3>,,Tutorial part 2 Creating a trivial machine code function<2> -@anchor{cp/intro/tutorial02 options}@anchor{11d} +@anchor{cp/intro/tutorial02 options}@anchor{121} @subsubsection Options To get more information on what's going on, you can set debugging flags -on the context using @pxref{11e,,gccjit;;context;;set_bool_option()}. +on the context using @pxref{122,,gccjit;;context;;set_bool_option()}. @c (I'm deliberately not mentioning @c :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think @@ -9657,7 +9756,7 @@ square: By default, no optimizations are performed, the equivalent of GCC's @cite{-O0} option. We can turn things up to e.g. @cite{-O3} by calling -@pxref{11f,,gccjit;;context;;set_int_option()} with +@pxref{123,,gccjit;;context;;set_int_option()} with @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: @example @@ -9691,7 +9790,7 @@ square: Naturally this has only a small effect on such a trivial function. @node Full example<3>,,Options<3>,Tutorial part 2 Creating a trivial machine code function<2> -@anchor{cp/intro/tutorial02 full-example}@anchor{120} +@anchor{cp/intro/tutorial02 full-example}@anchor{124} @subsubsection Full example @@ -9834,7 +9933,7 @@ result: 25 @c . @node Tutorial part 3 Loops and variables<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>,Tutorial part 2 Creating a trivial machine code function<2>,Tutorial<2> -@anchor{cp/intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{121}@anchor{cp/intro/tutorial03 doc}@anchor{122} +@anchor{cp/intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{125}@anchor{cp/intro/tutorial03 doc}@anchor{126} @subsection Tutorial part 3: Loops and variables @@ -9958,7 +10057,7 @@ gccjit::function func = @end menu @node Expressions lvalues and rvalues<2>,Control flow<2>,,Tutorial part 3 Loops and variables<2> -@anchor{cp/intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{123} +@anchor{cp/intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{127} @subsubsection Expressions: lvalues and rvalues @@ -10031,7 +10130,7 @@ body of a function. Our new example has a new kind of expression: we have two local variables. We create them by calling -@pxref{124,,gccjit;;function;;new_local()}, supplying a type and a name: +@pxref{128,,gccjit;;function;;new_local()}, supplying a type and a name: @example /* Build locals: */ @@ -10057,7 +10156,7 @@ Instead, having added the local to the function, we have to separately add an assignment of @cite{0} to @cite{local_i} at the beginning of the function. @node Control flow<2>,Visualizing the control flow graph<2>,Expressions lvalues and rvalues<2>,Tutorial part 3 Loops and variables<2> -@anchor{cp/intro/tutorial03 control-flow}@anchor{125} +@anchor{cp/intro/tutorial03 control-flow}@anchor{129} @subsubsection Control flow @@ -10096,8 +10195,8 @@ We now populate each block with statements. The entry block @cite{b_initial} consists of initializations followed by a jump to the conditional. We assign @cite{0} to @cite{i} and to @cite{sum}, using -@pxref{126,,gccjit;;block;;add_assignment()} to add -an assignment statement, and using @pxref{127,,gccjit;;context;;zero()} to get +@pxref{12a,,gccjit;;block;;add_assignment()} to add +an assignment statement, and using @pxref{12b,,gccjit;;context;;zero()} to get the constant value @cite{0} for the relevant type for the right-hand side of the assignment: @@ -10124,7 +10223,7 @@ C example. It contains a single statement: a conditional, which jumps to one of two destination blocks depending on a boolean @code{gccjit::rvalue}, in this case the comparison of @cite{i} and @cite{n}. -We could build the comparison using @pxref{128,,gccjit;;context;;new_comparison()}: +We could build the comparison using @pxref{12c,,gccjit;;context;;new_comparison()}: @example gccjit::rvalue guard = @@ -10135,7 +10234,7 @@ gccjit::rvalue guard = @noindent and can then use this to add @cite{b_loop_cond}'s sole statement, via -@pxref{129,,gccjit;;block;;end_with_conditional()}: +@pxref{12d,,gccjit;;block;;end_with_conditional()}: @example b_loop_cond.end_with_conditional (guard, @@ -10169,7 +10268,7 @@ Next, we populate the body of the loop. The C statement @cite{sum += i * i;} is an assignment operation, where an lvalue is modified "in-place". We use -@pxref{12a,,gccjit;;block;;add_assignment_op()} to handle these operations: +@pxref{12e,,gccjit;;block;;add_assignment_op()} to handle these operations: @example /* sum += i * i */ @@ -10197,7 +10296,7 @@ b_loop_body.add_assignment_op (i, @cartouche @quotation Note For numeric constants other than 0 or 1, we could use -@pxref{12b,,gccjit;;context;;new_rvalue()}, which has overloads +@pxref{12f,,gccjit;;context;;new_rvalue()}, which has overloads for both @code{int} and @code{double}. @end quotation @end cartouche @@ -10273,12 +10372,12 @@ result: 285 @noindent @node Visualizing the control flow graph<2>,Full example<4>,Control flow<2>,Tutorial part 3 Loops and variables<2> -@anchor{cp/intro/tutorial03 visualizing-the-control-flow-graph}@anchor{12c} +@anchor{cp/intro/tutorial03 visualizing-the-control-flow-graph}@anchor{130} @subsubsection Visualizing the control flow graph You can see the control flow graph of a function using -@pxref{12d,,gccjit;;function;;dump_to_dot()}: +@pxref{131,,gccjit;;function;;dump_to_dot()}: @example func.dump_to_dot ("/tmp/sum-of-squares.dot"); @@ -10312,7 +10411,7 @@ install it with @cite{yum install python-xdot}): @end quotation @node Full example<4>,,Visualizing the control flow graph<2>,Tutorial part 3 Loops and variables<2> -@anchor{cp/intro/tutorial03 full-example}@anchor{12e} +@anchor{cp/intro/tutorial03 full-example}@anchor{132} @subsubsection Full example @@ -10495,7 +10594,7 @@ loop_test returned: 285 @c . @node Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>,,Tutorial part 3 Loops and variables<2>,Tutorial<2> -@anchor{cp/intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{12f}@anchor{cp/intro/tutorial04 doc}@anchor{130} +@anchor{cp/intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{133}@anchor{cp/intro/tutorial04 doc}@anchor{134} @subsection Tutorial part 4: Adding JIT-compilation to a toy interpreter @@ -10517,7 +10616,7 @@ to it. @end menu @node Our toy interpreter<2>,Compiling to machine code<2>,,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 our-toy-interpreter}@anchor{131} +@anchor{cp/intro/tutorial04 our-toy-interpreter}@anchor{135} @subsubsection Our toy interpreter @@ -10925,7 +11024,7 @@ toyvm_function::interpret (int arg, FILE *trace) @end quotation @node Compiling to machine code<2>,Setting things up<2>,Our toy interpreter<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 compiling-to-machine-code}@anchor{132} +@anchor{cp/intro/tutorial04 compiling-to-machine-code}@anchor{136} @subsubsection Compiling to machine code @@ -11005,7 +11104,7 @@ This means our compiler has the following state: @end quotation @node Setting things up<2>,Populating the function<2>,Compiling to machine code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 setting-things-up}@anchor{133} +@anchor{cp/intro/tutorial04 setting-things-up}@anchor{137} @subsubsection Setting things up @@ -11173,7 +11272,7 @@ We create the locals within the function. @end quotation @node Populating the function<2>,Verifying the control flow graph<2>,Setting things up<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 populating-the-function}@anchor{134} +@anchor{cp/intro/tutorial04 populating-the-function}@anchor{138} @subsubsection Populating the function @@ -11301,7 +11400,7 @@ stack into @code{y} instead erroneously assigned it to @code{x}, leaving @code{y uninitialized. To track this kind of thing down, we can use -@pxref{135,,gccjit;;block;;add_comment()} to add descriptive comments +@pxref{139,,gccjit;;block;;add_comment()} to add descriptive comments to the internal representation. This is invaluable when looking through the generated IR for, say @code{factorial}: @@ -11450,14 +11549,14 @@ to the next block. This is analogous to simply incrementing the program counter. @node Verifying the control flow graph<2>,Compiling the context<2>,Populating the function<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 verifying-the-control-flow-graph}@anchor{136} +@anchor{cp/intro/tutorial04 verifying-the-control-flow-graph}@anchor{13a} @subsubsection Verifying the control flow graph Having finished looping over the blocks, the context is complete. As before, we can verify that the control flow and statements are sane by -using @pxref{12d,,gccjit;;function;;dump_to_dot()}: +using @pxref{131,,gccjit;;function;;dump_to_dot()}: @example fn.dump_to_dot ("/tmp/factorial.dot"); @@ -11481,7 +11580,7 @@ errors in our compiler. @end quotation @node Compiling the context<2>,Single-stepping through the generated code<2>,Verifying the control flow graph<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 compiling-the-context}@anchor{137} +@anchor{cp/intro/tutorial04 compiling-the-context}@anchor{13b} @subsubsection Compiling the context @@ -11538,7 +11637,7 @@ private: @end quotation @node Single-stepping through the generated code<2>,Examining the generated code<2>,Compiling the context<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 single-stepping-through-the-generated-code}@anchor{138} +@anchor{cp/intro/tutorial04 single-stepping-through-the-generated-code}@anchor{13c} @subsubsection Single-stepping through the generated code @@ -11552,14 +11651,14 @@ It's possible to debug the generated code. To do this we need to both: @item Set up source code locations for our statements, so that we can meaningfully step through the code. We did this above by -calling @pxref{139,,gccjit;;context;;new_location()} and using the +calling @pxref{13d,,gccjit;;context;;new_location()} and using the results. @item Enable the generation of debugging information, by setting @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the @code{gccjit::context} via -@pxref{11e,,gccjit;;context;;set_bool_option()}: +@pxref{122,,gccjit;;context;;set_bool_option()}: @example ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1); @@ -11631,14 +11730,14 @@ optimization level in a regular compiler. @end cartouche @node Examining the generated code<2>,Putting it all together<2>,Single-stepping through the generated code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 examining-the-generated-code}@anchor{13a} +@anchor{cp/intro/tutorial04 examining-the-generated-code}@anchor{13e} @subsubsection Examining the generated code How good is the optimized code? We can turn up optimizations, by calling -@pxref{11f,,gccjit;;context;;set_int_option()} with +@pxref{123,,gccjit;;context;;set_int_option()} with @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: @example @@ -11820,7 +11919,7 @@ Note that the stack pushing and popping have been eliminated, as has the recursive call (in favor of an iteration). @node Putting it all together<2>,Behind the curtain How does our code get optimized?<2>,Examining the generated code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 putting-it-all-together}@anchor{13b} +@anchor{cp/intro/tutorial04 putting-it-all-together}@anchor{13f} @subsubsection Putting it all together @@ -11853,7 +11952,7 @@ compiler result: 55 @noindent @node Behind the curtain How does our code get optimized?<2>,,Putting it all together<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2> -@anchor{cp/intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{13c} +@anchor{cp/intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{140} @subsubsection Behind the curtain: How does our code get optimized? @@ -12054,7 +12153,7 @@ representation: @code{initial}, @code{instr4} and @code{instr9}. @end menu @node Optimizing away stack manipulation<2>,Elimination of tail recursion<2>,,Behind the curtain How does our code get optimized?<2> -@anchor{cp/intro/tutorial04 optimizing-away-stack-manipulation}@anchor{13d} +@anchor{cp/intro/tutorial04 optimizing-away-stack-manipulation}@anchor{141} @subsubsection Optimizing away stack manipulation @@ -12334,7 +12433,7 @@ instr9: @noindent @node Elimination of tail recursion<2>,,Optimizing away stack manipulation<2>,Behind the curtain How does our code get optimized?<2> -@anchor{cp/intro/tutorial04 elimination-of-tail-recursion}@anchor{13e} +@anchor{cp/intro/tutorial04 elimination-of-tail-recursion}@anchor{142} @subsubsection Elimination of tail recursion @@ -12421,7 +12520,7 @@ instr9: @c . @node Topic Reference<2>,,Tutorial<2>,C++ bindings for libgccjit -@anchor{cp/topics/index doc}@anchor{13f}@anchor{cp/topics/index topic-reference}@anchor{140} +@anchor{cp/topics/index doc}@anchor{143}@anchor{cp/topics/index topic-reference}@anchor{144} @section Topic Reference @@ -12486,7 +12585,7 @@ Rvalues * Binary Operations: Binary Operations<2>. * Comparisons: Comparisons<2>. * Function calls: Function calls<2>. -* Function pointers: Function pointers<2>. +* Function pointers: Function pointers<3>. * Type-coercion: Type-coercion<2>. Lvalues @@ -12513,22 +12612,22 @@ Compiling a context @node Compilation contexts<2>,Objects<2>,,Topic Reference<2> -@anchor{cp/topics/contexts compilation-contexts}@anchor{141}@anchor{cp/topics/contexts doc}@anchor{142} +@anchor{cp/topics/contexts compilation-contexts}@anchor{145}@anchor{cp/topics/contexts doc}@anchor{146} @subsection Compilation contexts @geindex gccjit;;context (C++ class) -@anchor{cp/topics/contexts gccjit context}@anchor{143} +@anchor{cp/topics/contexts gccjit context}@anchor{147} @deffn {C++ Class} gccjit::context @end deffn -The top-level of the C++ API is the @pxref{143,,gccjit;;context} type. +The top-level of the C++ API is the @pxref{147,,gccjit;;context} type. -A @pxref{143,,gccjit;;context} instance encapsulates the state of a +A @pxref{147,,gccjit;;context} instance encapsulates the state of a compilation. You can set up options on it, and add types, functions and code. -Invoking @pxref{11c,,gccjit;;context;;compile()} on it gives you a +Invoking @pxref{120,,gccjit;;context;;compile()} on it gives you a @pxref{16,,gcc_jit_result *}. It is a thin wrapper around the C API's @pxref{8,,gcc_jit_context *}. @@ -12543,7 +12642,7 @@ It is a thin wrapper around the C API's @pxref{8,,gcc_jit_context *}. @end menu @node Lifetime-management<2>,Thread-safety<2>,,Compilation contexts<2> -@anchor{cp/topics/contexts lifetime-management}@anchor{144} +@anchor{cp/topics/contexts lifetime-management}@anchor{148} @subsubsection Lifetime-management @@ -12552,16 +12651,16 @@ have their lifetime bounded by the context they are created within, and cleanup of such objects is done for you when the context is released. @geindex gccjit;;context;;acquire (C++ function) -@anchor{cp/topics/contexts gccjit context acquire}@anchor{116} +@anchor{cp/topics/contexts gccjit context acquire}@anchor{11a} @deffn {C++ Function} gccjit::context gccjit::context::acquire () -This function acquires a new @pxref{143,,gccjit;;context} instance, +This function acquires a new @pxref{147,,gccjit;;context} instance, which is independent of any others that may be present within this process. @end deffn @geindex gccjit;;context;;release (C++ function) -@anchor{cp/topics/contexts gccjit context release}@anchor{118} +@anchor{cp/topics/contexts gccjit context release}@anchor{11c} @deffn {C++ Function} void gccjit::context::release () This function releases all resources associated with the given context. @@ -12580,7 +12679,7 @@ ctxt.release (); @end deffn @geindex gccjit;;context;;new_child_context (C++ function) -@anchor{cp/topics/contexts gccjit context new_child_context}@anchor{145} +@anchor{cp/topics/contexts gccjit context new_child_context}@anchor{149} @deffn {C++ Function} gccjit::context gccjit::context::new_child_context () Given an existing JIT context, create a child context. @@ -12612,16 +12711,16 @@ there will likely be a performance hit for such nesting. @end deffn @node Thread-safety<2>,Error-handling<3>,Lifetime-management<2>,Compilation contexts<2> -@anchor{cp/topics/contexts thread-safety}@anchor{146} +@anchor{cp/topics/contexts thread-safety}@anchor{14a} @subsubsection Thread-safety -Instances of @pxref{143,,gccjit;;context} created via -@pxref{116,,gccjit;;context;;acquire()} are independent from each other: +Instances of @pxref{147,,gccjit;;context} created via +@pxref{11a,,gccjit;;context;;acquire()} are independent from each other: only one thread may use a given context at once, but multiple threads could each have their own contexts without needing locks. -Contexts created via @pxref{145,,gccjit;;context;;new_child_context()} are +Contexts created via @pxref{149,,gccjit;;context;;new_child_context()} are related to their parent context. They can be partitioned by their ultimate ancestor into independent "family trees". Only one thread within a process may use a given "family tree" of such contexts at once, @@ -12629,7 +12728,7 @@ and if you're using multiple threads you should provide your own locking around entire such context partitions. @node Error-handling<3>,Debugging<2>,Thread-safety<2>,Compilation contexts<2> -@anchor{cp/topics/contexts error-handling}@anchor{147} +@anchor{cp/topics/contexts error-handling}@anchor{14b} @subsubsection Error-handling @@ -12642,10 +12741,10 @@ NULL. You don't have to check everywhere for NULL results, since the API gracefully handles a NULL being passed in for any argument. Errors are printed on stderr and can be queried using -@pxref{148,,gccjit;;context;;get_first_error()}. +@pxref{14c,,gccjit;;context;;get_first_error()}. @geindex gccjit;;context;;get_first_error (C++ function) -@anchor{cp/topics/contexts gccjit context get_first_error__gccjit contextP}@anchor{148} +@anchor{cp/topics/contexts gccjit context get_first_error__gccjit contextP}@anchor{14c} @deffn {C++ Function} const char* gccjit::context::get_first_error (gccjit::context* ctxt) Returns the first error message that occurred on the context. @@ -12657,18 +12756,18 @@ If no errors occurred, this will be NULL. @end deffn @node Debugging<2>,Options<4>,Error-handling<3>,Compilation contexts<2> -@anchor{cp/topics/contexts debugging}@anchor{149} +@anchor{cp/topics/contexts debugging}@anchor{14d} @subsubsection Debugging @geindex gccjit;;context;;dump_to_file (C++ function) -@anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{14a} +@anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{14e} @deffn {C++ Function} void gccjit::context::dump_to_file (const std::string& path, int update_locations) To help with debugging: dump a C-like representation to the given path, describing what's been set up on the context. -If "update_locations" is true, then also set up @pxref{14b,,gccjit;;location} +If "update_locations" is true, then also set up @pxref{14f,,gccjit;;location} information throughout the context, pointing at the dump file as if it were a source file. This may be of use in conjunction with @code{GCCJIT::BOOL_OPTION_DEBUGINFO} to allow stepping through the @@ -12676,7 +12775,7 @@ code in a debugger. @end deffn @geindex gccjit;;context;;dump_reproducer_to_file (C++ function) -@anchor{cp/topics/contexts gccjit context dump_reproducer_to_file__gcc_jit_contextP cCP}@anchor{14c} +@anchor{cp/topics/contexts gccjit context dump_reproducer_to_file__gcc_jit_contextP cCP}@anchor{150} @deffn {C++ Function} void gccjit::context::dump_reproducer_to_file (gcc_jit_context* ctxt, const char* path) This is a thin wrapper around the C API @@ -12688,7 +12787,7 @@ for seeing what the C++ bindings are doing at the C level. @end deffn @node Options<4>,,Debugging<2>,Compilation contexts<2> -@anchor{cp/topics/contexts options}@anchor{14d} +@anchor{cp/topics/contexts options}@anchor{151} @subsubsection Options @@ -12701,12 +12800,12 @@ for seeing what the C++ bindings are doing at the C level. @end menu @node String Options<2>,Boolean options<2>,,Options<4> -@anchor{cp/topics/contexts string-options}@anchor{14e} +@anchor{cp/topics/contexts string-options}@anchor{152} @subsubsection String Options @geindex gccjit;;context;;set_str_option (C++ function) -@anchor{cp/topics/contexts gccjit context set_str_option__enum cCP}@anchor{14f} +@anchor{cp/topics/contexts gccjit context set_str_option__enum cCP}@anchor{153} @deffn {C++ Function} void gccjit::context::set_str_option (enum gcc_jit_str_option, const char* value) Set a string option of the context. @@ -12717,12 +12816,12 @@ meaning. @end deffn @node Boolean options<2>,Integer options<2>,String Options<2>,Options<4> -@anchor{cp/topics/contexts boolean-options}@anchor{150} +@anchor{cp/topics/contexts boolean-options}@anchor{154} @subsubsection Boolean options @geindex gccjit;;context;;set_bool_option (C++ function) -@anchor{cp/topics/contexts gccjit context set_bool_option__enum i}@anchor{11e} +@anchor{cp/topics/contexts gccjit context set_bool_option__enum i}@anchor{122} @deffn {C++ Function} void gccjit::context::set_bool_option (enum gcc_jit_bool_option, int value) Set a boolean option of the context. @@ -12733,7 +12832,7 @@ meaning. @end deffn @geindex gccjit;;context;;set_bool_allow_unreachable_blocks (C++ function) -@anchor{cp/topics/contexts gccjit context set_bool_allow_unreachable_blocks__i}@anchor{151} +@anchor{cp/topics/contexts gccjit context set_bool_allow_unreachable_blocks__i}@anchor{155} @deffn {C++ Function} void gccjit::context::set_bool_allow_unreachable_blocks (int bool_value) By default, libgccjit will issue an error about unreachable blocks @@ -12754,7 +12853,7 @@ its presence using @end deffn @geindex gccjit;;context;;set_bool_use_external_driver (C++ function) -@anchor{cp/topics/contexts gccjit context set_bool_use_external_driver__i}@anchor{152} +@anchor{cp/topics/contexts gccjit context set_bool_use_external_driver__i}@anchor{156} @deffn {C++ Function} void gccjit::context::set_bool_use_external_driver (int bool_value) libgccjit internally generates assembler, and uses "driver" code @@ -12778,12 +12877,12 @@ its presence using @end deffn @node Integer options<2>,Additional command-line options<2>,Boolean options<2>,Options<4> -@anchor{cp/topics/contexts integer-options}@anchor{153} +@anchor{cp/topics/contexts integer-options}@anchor{157} @subsubsection Integer options @geindex gccjit;;context;;set_int_option (C++ function) -@anchor{cp/topics/contexts gccjit context set_int_option__enum i}@anchor{11f} +@anchor{cp/topics/contexts gccjit context set_int_option__enum i}@anchor{123} @deffn {C++ Function} void gccjit::context::set_int_option (enum gcc_jit_int_option, int value) Set an integer option of the context. @@ -12794,12 +12893,12 @@ meaning. @end deffn @node Additional command-line options<2>,,Integer options<2>,Options<4> -@anchor{cp/topics/contexts additional-command-line-options}@anchor{154} +@anchor{cp/topics/contexts additional-command-line-options}@anchor{158} @subsubsection Additional command-line options @geindex gccjit;;context;;add_command_line_option (C++ function) -@anchor{cp/topics/contexts gccjit context add_command_line_option__cCP}@anchor{155} +@anchor{cp/topics/contexts gccjit context add_command_line_option__cCP}@anchor{159} @deffn {C++ Function} void gccjit::context::add_command_line_option (const char* optname) Add an arbitrary gcc command-line option to the context for use @@ -12836,18 +12935,18 @@ its presence using @c . @node Objects<2>,Types<2>,Compilation contexts<2>,Topic Reference<2> -@anchor{cp/topics/objects objects}@anchor{156}@anchor{cp/topics/objects doc}@anchor{157} +@anchor{cp/topics/objects objects}@anchor{15a}@anchor{cp/topics/objects doc}@anchor{15b} @subsection Objects @geindex gccjit;;object (C++ class) -@anchor{cp/topics/objects gccjit object}@anchor{158} +@anchor{cp/topics/objects gccjit object}@anchor{15c} @deffn {C++ Class} gccjit::object @end deffn Almost every entity in the API (with the exception of -@pxref{143,,gccjit;;context} and @pxref{16,,gcc_jit_result *}) is a -"contextual" object, a @pxref{158,,gccjit;;object}. +@pxref{147,,gccjit;;context} and @pxref{16,,gcc_jit_result *}) is a +"contextual" object, a @pxref{15c,,gccjit;;object}. A JIT object: @@ -12857,7 +12956,7 @@ A JIT object: @itemize * @item -is associated with a @pxref{143,,gccjit;;context}. +is associated with a @pxref{147,,gccjit;;context}. @item is automatically cleaned up for you when its context is released so @@ -12884,17 +12983,17 @@ The C++ class hierarchy within the @code{gccjit} namespace looks like this: @noindent -The @pxref{158,,gccjit;;object} base class has the following operations: +The @pxref{15c,,gccjit;;object} base class has the following operations: @geindex gccjit;;object;;get_context (C++ function) -@anchor{cp/topics/objects gccjit object get_contextC}@anchor{159} +@anchor{cp/topics/objects gccjit object get_contextC}@anchor{15d} @deffn {C++ Function} gccjit::context gccjit::object::get_context () const Which context is the obj within? @end deffn @geindex gccjit;;object;;get_debug_string (C++ function) -@anchor{cp/topics/objects gccjit object get_debug_stringC}@anchor{119} +@anchor{cp/topics/objects gccjit object get_debug_stringC}@anchor{11d} @deffn {C++ Function} std::string gccjit::object::get_debug_string () const Generate a human-readable description for the given object. @@ -12934,16 +13033,16 @@ obj: 4.0 * (float)i @c . @node Types<2>,Expressions<2>,Objects<2>,Topic Reference<2> -@anchor{cp/topics/types doc}@anchor{15a}@anchor{cp/topics/types types}@anchor{15b} +@anchor{cp/topics/types doc}@anchor{15e}@anchor{cp/topics/types types}@anchor{15f} @subsection Types @geindex gccjit;;type (C++ class) -@anchor{cp/topics/types gccjit type}@anchor{15c} +@anchor{cp/topics/types gccjit type}@anchor{160} @deffn {C++ Class} gccjit::type gccjit::type represents a type within the library. It is a subclass -of @pxref{158,,gccjit;;object}. +of @pxref{15c,,gccjit;;object}. @end deffn Types can be created in several ways: @@ -12953,7 +13052,7 @@ Types can be created in several ways: @item fundamental types can be accessed using -@pxref{117,,gccjit;;context;;get_type()}: +@pxref{11b,,gccjit;;context;;get_type()}: @example gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT); @@ -12973,7 +13072,7 @@ See @pxref{b,,gcc_jit_context_get_type()} for the available types. @item derived types can be accessed by using functions such as -@pxref{15d,,gccjit;;type;;get_pointer()} and @pxref{15e,,gccjit;;type;;get_const()}: +@pxref{161,,gccjit;;type;;get_pointer()} and @pxref{162,,gccjit;;type;;get_const()}: @example gccjit::type const_int_star = int_type.get_const ().get_pointer (); @@ -12995,12 +13094,12 @@ by creating structures (see below). @end menu @node Standard types<2>,Pointers const and volatile<2>,,Types<2> -@anchor{cp/topics/types standard-types}@anchor{15f} +@anchor{cp/topics/types standard-types}@anchor{163} @subsubsection Standard types @geindex gccjit;;context;;get_type (C++ function) -@anchor{cp/topics/types gccjit context get_type__enum}@anchor{117} +@anchor{cp/topics/types gccjit context get_type__enum}@anchor{11b} @deffn {C++ Function} gccjit::type gccjit::context::get_type (enum gcc_jit_types) Access a specific type. This is a thin wrapper around @@ -13008,14 +13107,14 @@ Access a specific type. This is a thin wrapper around @end deffn @geindex gccjit;;context;;get_int_type (C++ function) -@anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{160} +@anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{164} @deffn {C++ Function} gccjit::type gccjit::context::get_int_type (size_t num_bytes, int is_signed) Access the integer type of the given size. @end deffn @geindex gccjit;;context;;get_int_type (C++ function) -@anchor{cp/topics/types gccjit context get_int_type T}@anchor{161} +@anchor{cp/topics/types gccjit context get_int_type T}@anchor{165} @deffn {C++ Function} gccjit::type gccjit::context::get_int_type () Access the given integer type. For example, you could map the @@ -13029,33 +13128,33 @@ gccjit::type t = ctxt.get_int_type (); @end deffn @node Pointers const and volatile<2>,Vector types<2>,Standard types<2>,Types<2> -@anchor{cp/topics/types pointers-const-and-volatile}@anchor{162} +@anchor{cp/topics/types pointers-const-and-volatile}@anchor{166} @subsubsection Pointers, @cite{const}, and @cite{volatile} @geindex gccjit;;type;;get_pointer (C++ function) -@anchor{cp/topics/types gccjit type get_pointer}@anchor{15d} +@anchor{cp/topics/types gccjit type get_pointer}@anchor{161} @deffn {C++ Function} gccjit::type gccjit::type::get_pointer () Given type "T", get type "T*". @end deffn @geindex gccjit;;type;;get_const (C++ function) -@anchor{cp/topics/types gccjit type get_const}@anchor{15e} +@anchor{cp/topics/types gccjit type get_const}@anchor{162} @deffn {C++ Function} gccjit::type gccjit::type::get_const () Given type "T", get type "const T". @end deffn @geindex gccjit;;type;;get_volatile (C++ function) -@anchor{cp/topics/types gccjit type get_volatile}@anchor{163} +@anchor{cp/topics/types gccjit type get_volatile}@anchor{167} @deffn {C++ Function} gccjit::type gccjit::type::get_volatile () Given type "T", get type "volatile T". @end deffn @geindex gccjit;;type;;get_aligned (C++ function) -@anchor{cp/topics/types gccjit type get_aligned__s}@anchor{164} +@anchor{cp/topics/types gccjit type get_aligned__s}@anchor{168} @deffn {C++ Function} gccjit::type gccjit::type::get_aligned (size_t alignment_in_bytes) Given type "T", get type: @@ -13070,7 +13169,7 @@ The alignment must be a power of two. @end deffn @geindex gccjit;;context;;new_array_type (C++ function) -@anchor{cp/topics/types gccjit context new_array_type__gccjit type i gccjit location}@anchor{165} +@anchor{cp/topics/types gccjit context new_array_type__gccjit type i gccjit location}@anchor{169} @deffn {C++ Function} gccjit::type gccjit::context::new_array_type (gccjit::type element_type, int num_elements, gccjit::location loc) Given type "T", get type "T[N]" (for a constant N). @@ -13078,12 +13177,12 @@ Param "loc" is optional. @end deffn @node Vector types<2>,Structures and unions<2>,Pointers const and volatile<2>,Types<2> -@anchor{cp/topics/types vector-types}@anchor{166} +@anchor{cp/topics/types vector-types}@anchor{16a} @subsubsection Vector types @geindex gccjit;;type;;get_vector (C++ function) -@anchor{cp/topics/types gccjit type get_vector__s}@anchor{167} +@anchor{cp/topics/types gccjit type get_vector__s}@anchor{16b} @deffn {C++ Function} gccjit::type gccjit::type::get_vector (size_t num_units) Given type "T", get type: @@ -13098,31 +13197,31 @@ T must be integral or floating point; num_units must be a power of two. @end deffn @node Structures and unions<2>,,Vector types<2>,Types<2> -@anchor{cp/topics/types structures-and-unions}@anchor{168} +@anchor{cp/topics/types structures-and-unions}@anchor{16c} @subsubsection Structures and unions @geindex gccjit;;struct_ (C++ class) -@anchor{cp/topics/types gccjit struct_}@anchor{169} +@anchor{cp/topics/types gccjit struct_}@anchor{16d} @deffn {C++ Class} gccjit::struct_ @end deffn A compound type analagous to a C @cite{struct}. -@pxref{169,,gccjit;;struct_} is a subclass of @pxref{15c,,gccjit;;type} (and thus -of @pxref{158,,gccjit;;object} in turn). +@pxref{16d,,gccjit;;struct_} is a subclass of @pxref{160,,gccjit;;type} (and thus +of @pxref{15c,,gccjit;;object} in turn). @geindex gccjit;;field (C++ class) -@anchor{cp/topics/types gccjit field}@anchor{16a} +@anchor{cp/topics/types gccjit field}@anchor{16e} @deffn {C++ Class} gccjit::field @end deffn -A field within a @pxref{169,,gccjit;;struct_}. +A field within a @pxref{16d,,gccjit;;struct_}. -@pxref{16a,,gccjit;;field} is a subclass of @pxref{158,,gccjit;;object}. +@pxref{16e,,gccjit;;field} is a subclass of @pxref{15c,,gccjit;;object}. -You can model C @cite{struct} types by creating @pxref{169,,gccjit;;struct_} and -@pxref{16a,,gccjit;;field} instances, in either order: +You can model C @cite{struct} types by creating @pxref{16d,,gccjit;;struct_} and +@pxref{16e,,gccjit;;field} instances, in either order: @itemize * @@ -13178,14 +13277,14 @@ node.set_fields (fields); @c FIXME: the above API doesn't seem to exist yet @geindex gccjit;;context;;new_field (C++ function) -@anchor{cp/topics/types gccjit context new_field__gccjit type cCP gccjit location}@anchor{16b} +@anchor{cp/topics/types gccjit context new_field__gccjit type cCP gccjit location}@anchor{16f} @deffn {C++ Function} gccjit::field gccjit::context::new_field (gccjit::type type, const char* name, gccjit::location loc) Construct a new field, with the given type and name. @end deffn @geindex gccjit;;context;;new_struct_type (C++ function) -@anchor{cp/topics/types gccjit context new_struct_type__ssCR std vector field R gccjit location}@anchor{16c} +@anchor{cp/topics/types gccjit context new_struct_type__ssCR std vector field R gccjit location}@anchor{170} @deffn {C++ Function} gccjit::struct_ gccjit::context::new_struct_type (const std::string& name, std::vector& fields, gccjit::location loc) @quotation @@ -13195,7 +13294,7 @@ Construct a new struct type, with the given name and fields. @end deffn @geindex gccjit;;context;;new_opaque_struct (C++ function) -@anchor{cp/topics/types gccjit context new_opaque_struct__ssCR gccjit location}@anchor{16d} +@anchor{cp/topics/types gccjit context new_opaque_struct__ssCR gccjit location}@anchor{171} @deffn {C++ Function} gccjit::struct_ gccjit::context::new_opaque_struct (const std::string& name, gccjit::location loc) Construct a new struct type, with the given name, but without @@ -13222,7 +13321,7 @@ size of the struct is not known), or later specified using @c . @node Expressions<2>,Creating and using functions<2>,Types<2>,Topic Reference<2> -@anchor{cp/topics/expressions expressions}@anchor{16e}@anchor{cp/topics/expressions doc}@anchor{16f} +@anchor{cp/topics/expressions expressions}@anchor{172}@anchor{cp/topics/expressions doc}@anchor{173} @subsection Expressions @@ -13238,7 +13337,7 @@ Rvalues * Binary Operations: Binary Operations<2>. * Comparisons: Comparisons<2>. * Function calls: Function calls<2>. -* Function pointers: Function pointers<2>. +* Function pointers: Function pointers<3>. * Type-coercion: Type-coercion<2>. Lvalues @@ -13249,17 +13348,17 @@ Lvalues @node Rvalues<2>,Lvalues<2>,,Expressions<2> -@anchor{cp/topics/expressions rvalues}@anchor{170} +@anchor{cp/topics/expressions rvalues}@anchor{174} @subsubsection Rvalues @geindex gccjit;;rvalue (C++ class) -@anchor{cp/topics/expressions gccjit rvalue}@anchor{171} +@anchor{cp/topics/expressions gccjit rvalue}@anchor{175} @deffn {C++ Class} gccjit::rvalue @end deffn -A @pxref{171,,gccjit;;rvalue} is an expression that can be computed. It is a -subclass of @pxref{158,,gccjit;;object}, and is a thin wrapper around +A @pxref{175,,gccjit;;rvalue} is an expression that can be computed. It is a +subclass of @pxref{15c,,gccjit;;object}, and is a thin wrapper around @pxref{13,,gcc_jit_rvalue *} from the C API. It can be simple, e.g.: @@ -13305,7 +13404,7 @@ Every rvalue has an associated type, and the API will check to ensure that types match up correctly (otherwise the context will emit an error). @geindex gccjit;;rvalue;;get_type (C++ function) -@anchor{cp/topics/expressions gccjit rvalue get_type}@anchor{172} +@anchor{cp/topics/expressions gccjit rvalue get_type}@anchor{176} @deffn {C++ Function} gccjit::type gccjit::rvalue::get_type () Get the type of this rvalue. @@ -13317,18 +13416,18 @@ Get the type of this rvalue. * Binary Operations: Binary Operations<2>. * Comparisons: Comparisons<2>. * Function calls: Function calls<2>. -* Function pointers: Function pointers<2>. +* Function pointers: Function pointers<3>. * Type-coercion: Type-coercion<2>. @end menu @node Simple expressions<2>,Unary Operations<2>,,Rvalues<2> -@anchor{cp/topics/expressions simple-expressions}@anchor{173} +@anchor{cp/topics/expressions simple-expressions}@anchor{177} @subsubsection Simple expressions @geindex gccjit;;context;;new_rvalue (C++ function) -@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{12b} +@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{12f} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, int value) const Given a numeric type (integer or floating point), build an rvalue for @@ -13336,7 +13435,7 @@ the given constant @code{int} value. @end deffn @geindex gccjit;;context;;new_rvalue (C++ function) -@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type lC}@anchor{174} +@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type lC}@anchor{178} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, long value) const Given a numeric type (integer or floating point), build an rvalue for @@ -13344,7 +13443,7 @@ the given constant @code{long} value. @end deffn @geindex gccjit;;context;;zero (C++ function) -@anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{127} +@anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{12b} @deffn {C++ Function} gccjit::rvalue gccjit::context::zero (gccjit::type numeric_type) const Given a numeric type (integer or floating point), get the rvalue for @@ -13358,7 +13457,7 @@ ctxt.new_rvalue (numeric_type, 0) @end deffn @geindex gccjit;;context;;one (C++ function) -@anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{175} +@anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{179} @deffn {C++ Function} gccjit::rvalue gccjit::context::one (gccjit::type numeric_type) const Given a numeric type (integer or floating point), get the rvalue for @@ -13372,7 +13471,7 @@ ctxt.new_rvalue (numeric_type, 1) @end deffn @geindex gccjit;;context;;new_rvalue (C++ function) -@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{176} +@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{17a} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, double value) const Given a numeric type (integer or floating point), build an rvalue for @@ -13380,14 +13479,14 @@ the given constant @code{double} value. @end deffn @geindex gccjit;;context;;new_rvalue (C++ function) -@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type voidPC}@anchor{177} +@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type voidPC}@anchor{17b} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type pointer_type, void* value) const Given a pointer type, build an rvalue for the given address. @end deffn @geindex gccjit;;context;;new_rvalue (C++ function) -@anchor{cp/topics/expressions gccjit context new_rvalue__ssCRC}@anchor{178} +@anchor{cp/topics/expressions gccjit context new_rvalue__ssCRC}@anchor{17c} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (const std::string& value) const Generate an rvalue of type @code{GCC_JIT_TYPE_CONST_CHAR_PTR} for @@ -13395,12 +13494,12 @@ the given string. This is akin to a string literal. @end deffn @node Unary Operations<2>,Binary Operations<2>,Simple expressions<2>,Rvalues<2> -@anchor{cp/topics/expressions unary-operations}@anchor{179} +@anchor{cp/topics/expressions unary-operations}@anchor{17d} @subsubsection Unary Operations @geindex gccjit;;context;;new_unary_op (C++ function) -@anchor{cp/topics/expressions gccjit context new_unary_op__enum gccjit type gccjit rvalue gccjit location}@anchor{17a} +@anchor{cp/topics/expressions gccjit context new_unary_op__enum gccjit type gccjit rvalue gccjit location}@anchor{17e} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_unary_op (enum gcc_jit_unary_op, gccjit::type result_type, gccjit::rvalue rvalue, gccjit::location loc) Build a unary operation out of an input rvalue. @@ -13408,7 +13507,7 @@ Build a unary operation out of an input rvalue. Parameter @code{loc} is optional. This is a thin wrapper around the C API's -@pxref{99,,gcc_jit_context_new_unary_op()} and the available unary +@pxref{9b,,gcc_jit_context_new_unary_op()} and the available unary operations are documented there. @end deffn @@ -13416,7 +13515,7 @@ There are shorter ways to spell the various specific kinds of unary operation: @geindex gccjit;;context;;new_minus (C++ function) -@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit location}@anchor{17b} +@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit location}@anchor{17f} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc) Negate an arithmetic value; for example: @@ -13437,7 +13536,7 @@ builds the equivalent of this C expression: @end deffn @geindex new_bitwise_negate (C++ function) -@anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{17c} +@anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{180} @deffn {C++ Function} gccjit::rvalue new_bitwise_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc) Bitwise negation of an integer value (one's complement); for example: @@ -13458,7 +13557,7 @@ builds the equivalent of this C expression: @end deffn @geindex new_logical_negate (C++ function) -@anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{17d} +@anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{181} @deffn {C++ Function} gccjit::rvalue new_logical_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc) Logical negation of an arithmetic or pointer value; for example: @@ -13481,7 +13580,7 @@ builds the equivalent of this C expression: The most concise way to spell them is with overloaded operators: @geindex operator- (C++ function) -@anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{17e} +@anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{182} @deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a) @example @@ -13492,7 +13591,7 @@ gccjit::rvalue negpi = -pi; @end deffn @geindex operator~ (C++ function) -@anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{17f} +@anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{183} @deffn {C++ Function} gccjit::rvalue operator~ (gccjit::rvalue a) @example @@ -13503,7 +13602,7 @@ gccjit::rvalue mask = ~a; @end deffn @geindex operator! (C++ function) -@anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{180} +@anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{184} @deffn {C++ Function} gccjit::rvalue operator! (gccjit::rvalue a) @example @@ -13514,12 +13613,12 @@ gccjit::rvalue guard = !cond; @end deffn @node Binary Operations<2>,Comparisons<2>,Unary Operations<2>,Rvalues<2> -@anchor{cp/topics/expressions binary-operations}@anchor{181} +@anchor{cp/topics/expressions binary-operations}@anchor{185} @subsubsection Binary Operations @geindex gccjit;;context;;new_binary_op (C++ function) -@anchor{cp/topics/expressions gccjit context new_binary_op__enum gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{11b} +@anchor{cp/topics/expressions gccjit context new_binary_op__enum gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{11f} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_binary_op (enum gcc_jit_binary_op, gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) Build a binary operation out of two constituent rvalues. @@ -13535,59 +13634,59 @@ There are shorter ways to spell the various specific kinds of binary operation: @geindex gccjit;;context;;new_plus (C++ function) -@anchor{cp/topics/expressions gccjit context new_plus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{182} +@anchor{cp/topics/expressions gccjit context new_plus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{186} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_plus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_minus (C++ function) -@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{183} +@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{187} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_mult (C++ function) -@anchor{cp/topics/expressions gccjit context new_mult__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{184} +@anchor{cp/topics/expressions gccjit context new_mult__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{188} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_mult (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_divide (C++ function) -@anchor{cp/topics/expressions gccjit context new_divide__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{185} +@anchor{cp/topics/expressions gccjit context new_divide__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{189} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_divide (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_modulo (C++ function) -@anchor{cp/topics/expressions gccjit context new_modulo__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{186} +@anchor{cp/topics/expressions gccjit context new_modulo__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{18a} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_modulo (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_bitwise_and (C++ function) -@anchor{cp/topics/expressions gccjit context new_bitwise_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{187} +@anchor{cp/topics/expressions gccjit context new_bitwise_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{18b} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_bitwise_xor (C++ function) -@anchor{cp/topics/expressions gccjit context new_bitwise_xor__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{188} +@anchor{cp/topics/expressions gccjit context new_bitwise_xor__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{18c} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_xor (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_bitwise_or (C++ function) -@anchor{cp/topics/expressions gccjit context new_bitwise_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{189} +@anchor{cp/topics/expressions gccjit context new_bitwise_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{18d} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_logical_and (C++ function) -@anchor{cp/topics/expressions gccjit context new_logical_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{18a} +@anchor{cp/topics/expressions gccjit context new_logical_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{18e} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_logical_or (C++ function) -@anchor{cp/topics/expressions gccjit context new_logical_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{18b} +@anchor{cp/topics/expressions gccjit context new_logical_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{18f} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn The most concise way to spell them is with overloaded operators: @geindex operator+ (C++ function) -@anchor{cp/topics/expressions add-operator__gccjit rvalue gccjit rvalue}@anchor{18c} +@anchor{cp/topics/expressions add-operator__gccjit rvalue gccjit rvalue}@anchor{190} @deffn {C++ Function} gccjit::rvalue operator+ (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13598,7 +13697,7 @@ gccjit::rvalue sum = a + b; @end deffn @geindex operator- (C++ function) -@anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{18d} +@anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{191} @deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13609,7 +13708,7 @@ gccjit::rvalue diff = a - b; @end deffn @geindex operator* (C++ function) -@anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{18e} +@anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{192} @deffn {C++ Function} gccjit::rvalue operator* (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13620,7 +13719,7 @@ gccjit::rvalue prod = a * b; @end deffn @geindex operator/ (C++ function) -@anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{18f} +@anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{193} @deffn {C++ Function} gccjit::rvalue operator/ (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13631,7 +13730,7 @@ gccjit::rvalue result = a / b; @end deffn @geindex operator% (C++ function) -@anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{190} +@anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{194} @deffn {C++ Function} gccjit::rvalue operator% (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13642,7 +13741,7 @@ gccjit::rvalue mod = a % b; @end deffn @geindex operator& (C++ function) -@anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{191} +@anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{195} @deffn {C++ Function} gccjit::rvalue operator& (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13653,7 +13752,7 @@ gccjit::rvalue x = a & b; @end deffn @geindex operator^ (C++ function) -@anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{192} +@anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{196} @deffn {C++ Function} gccjit::rvalue operator^ (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13664,7 +13763,7 @@ gccjit::rvalue x = a ^ b; @end deffn @geindex operator| (C++ function) -@anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{193} +@anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{197} @deffn {C++ Function} gccjit::rvalue operator| (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13675,7 +13774,7 @@ gccjit::rvalue x = a | b; @end deffn @geindex operator&& (C++ function) -@anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{194} +@anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{198} @deffn {C++ Function} gccjit::rvalue operator&& (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13686,7 +13785,7 @@ gccjit::rvalue cond = a && b; @end deffn @geindex operator|| (C++ function) -@anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{195} +@anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{199} @deffn {C++ Function} gccjit::rvalue operator|| (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13709,12 +13808,12 @@ gccjit::rvalue discriminant = (b * b) - (four * a * c); @end quotation @node Comparisons<2>,Function calls<2>,Binary Operations<2>,Rvalues<2> -@anchor{cp/topics/expressions comparisons}@anchor{196} +@anchor{cp/topics/expressions comparisons}@anchor{19a} @subsubsection Comparisons @geindex gccjit;;context;;new_comparison (C++ function) -@anchor{cp/topics/expressions gccjit context new_comparison__enum gccjit rvalue gccjit rvalue gccjit location}@anchor{128} +@anchor{cp/topics/expressions gccjit context new_comparison__enum gccjit rvalue gccjit rvalue gccjit location}@anchor{12c} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_comparison (enum gcc_jit_comparison, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) Build a boolean rvalue out of the comparison of two other rvalues. @@ -13730,39 +13829,39 @@ There are shorter ways to spell the various specific kinds of binary operation: @geindex gccjit;;context;;new_eq (C++ function) -@anchor{cp/topics/expressions gccjit context new_eq__gccjit rvalue gccjit rvalue gccjit location}@anchor{197} +@anchor{cp/topics/expressions gccjit context new_eq__gccjit rvalue gccjit rvalue gccjit location}@anchor{19b} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_eq (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_ne (C++ function) -@anchor{cp/topics/expressions gccjit context new_ne__gccjit rvalue gccjit rvalue gccjit location}@anchor{198} +@anchor{cp/topics/expressions gccjit context new_ne__gccjit rvalue gccjit rvalue gccjit location}@anchor{19c} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_ne (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_lt (C++ function) -@anchor{cp/topics/expressions gccjit context new_lt__gccjit rvalue gccjit rvalue gccjit location}@anchor{199} +@anchor{cp/topics/expressions gccjit context new_lt__gccjit rvalue gccjit rvalue gccjit location}@anchor{19d} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_lt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_le (C++ function) -@anchor{cp/topics/expressions gccjit context new_le__gccjit rvalue gccjit rvalue gccjit location}@anchor{19a} +@anchor{cp/topics/expressions gccjit context new_le__gccjit rvalue gccjit rvalue gccjit location}@anchor{19e} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_le (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_gt (C++ function) -@anchor{cp/topics/expressions gccjit context new_gt__gccjit rvalue gccjit rvalue gccjit location}@anchor{19b} +@anchor{cp/topics/expressions gccjit context new_gt__gccjit rvalue gccjit rvalue gccjit location}@anchor{19f} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_gt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn @geindex gccjit;;context;;new_ge (C++ function) -@anchor{cp/topics/expressions gccjit context new_ge__gccjit rvalue gccjit rvalue gccjit location}@anchor{19c} +@anchor{cp/topics/expressions gccjit context new_ge__gccjit rvalue gccjit rvalue gccjit location}@anchor{1a0} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_ge (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) @end deffn The most concise way to spell them is with overloaded operators: @geindex operator== (C++ function) -@anchor{cp/topics/expressions eq-operator__gccjit rvalue gccjit rvalue}@anchor{19d} +@anchor{cp/topics/expressions eq-operator__gccjit rvalue gccjit rvalue}@anchor{1a1} @deffn {C++ Function} gccjit::rvalue operator== (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13773,7 +13872,7 @@ gccjit::rvalue cond = (a == ctxt.zero (t_int)); @end deffn @geindex operator!= (C++ function) -@anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{19e} +@anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{1a2} @deffn {C++ Function} gccjit::rvalue operator!= (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13784,7 +13883,7 @@ gccjit::rvalue cond = (i != j); @end deffn @geindex operator< (C++ function) -@anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{19f} +@anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{1a3} @deffn {C++ Function} gccjit::rvalue operator< (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13795,7 +13894,7 @@ gccjit::rvalue cond = i < n; @end deffn @geindex operator<= (C++ function) -@anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{1a0} +@anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{1a4} @deffn {C++ Function} gccjit::rvalue operator<= (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13806,7 +13905,7 @@ gccjit::rvalue cond = i <= n; @end deffn @geindex operator> (C++ function) -@anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{1a1} +@anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{1a5} @deffn {C++ Function} gccjit::rvalue operator> (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13817,7 +13916,7 @@ gccjit::rvalue cond = (ch > limit); @end deffn @geindex operator>= (C++ function) -@anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{1a2} +@anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{1a6} @deffn {C++ Function} gccjit::rvalue operator>= (gccjit::rvalue a, gccjit::rvalue b) @example @@ -13829,13 +13928,13 @@ gccjit::rvalue cond = (score >= ctxt.new_rvalue (t_int, 100)); @c TODO: beyond this point -@node Function calls<2>,Function pointers<2>,Comparisons<2>,Rvalues<2> -@anchor{cp/topics/expressions function-calls}@anchor{1a3} +@node Function calls<2>,Function pointers<3>,Comparisons<2>,Rvalues<2> +@anchor{cp/topics/expressions function-calls}@anchor{1a7} @subsubsection Function calls @geindex gcc_jit_context_new_call (C++ function) -@anchor{cp/topics/expressions gcc_jit_context_new_call__gcc_jit_contextP gcc_jit_locationP gcc_jit_functionP i gcc_jit_rvaluePP}@anchor{1a4} +@anchor{cp/topics/expressions gcc_jit_context_new_call__gcc_jit_contextP gcc_jit_locationP gcc_jit_functionP i gcc_jit_rvaluePP}@anchor{1a8} @deffn {C++ Function} gcc_jit_rvalue* gcc_jit_context_new_call (gcc_jit_context* ctxt, gcc_jit_location* loc, gcc_jit_function* func, int numargs, gcc_jit_rvalue** args) Given a function and the given table of argument rvalues, construct a @@ -13844,14 +13943,14 @@ call to the function, with the result as an rvalue. @cartouche @quotation Note @code{gccjit::context::new_call()} merely builds a -@pxref{171,,gccjit;;rvalue} i.e. an expression that can be evaluated, +@pxref{175,,gccjit;;rvalue} i.e. an expression that can be evaluated, perhaps as part of a more complicated expression. The call @emph{won't} happen unless you add a statement to a function that evaluates the expression. For example, if you want to call a function and discard the result (or to call a function with @code{void} return type), use -@pxref{1a5,,gccjit;;block;;add_eval()}: +@pxref{1a9,,gccjit;;block;;add_eval()}: @example /* Add "(void)printf (arg0, arg1);". */ @@ -13863,26 +13962,26 @@ block.add_eval (ctxt.new_call (printf_func, arg0, arg1)); @end cartouche @end deffn -@node Function pointers<2>,Type-coercion<2>,Function calls<2>,Rvalues<2> -@anchor{cp/topics/expressions function-pointers}@anchor{1a6} +@node Function pointers<3>,Type-coercion<2>,Function calls<2>,Rvalues<2> +@anchor{cp/topics/expressions function-pointers}@anchor{1aa} @subsubsection Function pointers @geindex gccjit;;function;;get_address (C++ function) -@anchor{cp/topics/expressions gccjit function get_address__gccjit location}@anchor{1a7} +@anchor{cp/topics/expressions gccjit function get_address__gccjit location}@anchor{1ab} @deffn {C++ Function} gccjit::rvalue gccjit::function::get_address (gccjit::location loc) Get the address of a function as an rvalue, of function pointer type. @end deffn -@node Type-coercion<2>,,Function pointers<2>,Rvalues<2> -@anchor{cp/topics/expressions type-coercion}@anchor{1a8} +@node Type-coercion<2>,,Function pointers<3>,Rvalues<2> +@anchor{cp/topics/expressions type-coercion}@anchor{1ac} @subsubsection Type-coercion @geindex gccjit;;context;;new_cast (C++ function) -@anchor{cp/topics/expressions gccjit context new_cast__gccjit rvalue gccjit type gccjit location}@anchor{1a9} +@anchor{cp/topics/expressions gccjit context new_cast__gccjit rvalue gccjit type gccjit location}@anchor{1ad} @deffn {C++ Function} gccjit::rvalue gccjit::context::new_cast (gccjit::rvalue rvalue, gccjit::type type, gccjit::location loc) Given an rvalue of T, construct another rvalue of another type. @@ -13907,24 +14006,24 @@ P* <-> Q*, for pointer types P and Q @end deffn @node Lvalues<2>,Working with pointers structs and unions<2>,Rvalues<2>,Expressions<2> -@anchor{cp/topics/expressions lvalues}@anchor{1aa} +@anchor{cp/topics/expressions lvalues}@anchor{1ae} @subsubsection Lvalues @geindex gccjit;;lvalue (C++ class) -@anchor{cp/topics/expressions gccjit lvalue}@anchor{1ab} +@anchor{cp/topics/expressions gccjit lvalue}@anchor{1af} @deffn {C++ Class} gccjit::lvalue @end deffn An lvalue is something that can of the @emph{left}-hand side of an assignment: a storage area (such as a variable). It is a subclass of -@pxref{171,,gccjit;;rvalue}, where the rvalue is computed by reading from the +@pxref{175,,gccjit;;rvalue}, where the rvalue is computed by reading from the storage area. It iss a thin wrapper around @pxref{24,,gcc_jit_lvalue *} from the C API. @geindex gccjit;;lvalue;;get_address (C++ function) -@anchor{cp/topics/expressions gccjit lvalue get_address__gccjit location}@anchor{1ac} +@anchor{cp/topics/expressions gccjit lvalue get_address__gccjit location}@anchor{1b0} @deffn {C++ Function} gccjit::rvalue gccjit::lvalue::get_address (gccjit::location loc) Take the address of an lvalue; analogous to: @@ -13946,27 +14045,27 @@ Parameter "loc" is optional. @end menu @node Global variables<2>,,,Lvalues<2> -@anchor{cp/topics/expressions global-variables}@anchor{1ad} +@anchor{cp/topics/expressions global-variables}@anchor{1b1} @subsubsection Global variables @geindex gccjit;;context;;new_global (C++ function) -@anchor{cp/topics/expressions gccjit context new_global__enum gccjit type cCP gccjit location}@anchor{1ae} +@anchor{cp/topics/expressions gccjit context new_global__enum gccjit type cCP gccjit location}@anchor{1b2} @deffn {C++ Function} gccjit::lvalue gccjit::context::new_global (enum gcc_jit_global_kind, gccjit::type type, const char* name, gccjit::location loc) Add a new global variable of the given type and name to the context. -This is a thin wrapper around @pxref{c0,,gcc_jit_context_new_global()} from +This is a thin wrapper around @pxref{c1,,gcc_jit_context_new_global()} from the C API; the "kind" parameter has the same meaning as there. @end deffn @node Working with pointers structs and unions<2>,,Lvalues<2>,Expressions<2> -@anchor{cp/topics/expressions working-with-pointers-structs-and-unions}@anchor{1af} +@anchor{cp/topics/expressions working-with-pointers-structs-and-unions}@anchor{1b3} @subsubsection Working with pointers, structs and unions @geindex gccjit;;rvalue;;dereference (C++ function) -@anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{1b0} +@anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{1b4} @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference (gccjit::location loc) Given an rvalue of pointer type @code{T *}, dereferencing the pointer, @@ -13987,7 +14086,7 @@ If you don't need to specify the location, this can also be expressed using an overloaded operator: @geindex gccjit;;rvalue;;operator* (C++ function) -@anchor{cp/topics/expressions gccjit rvalue mul-operator}@anchor{1b1} +@anchor{cp/topics/expressions gccjit rvalue mul-operator}@anchor{1b5} @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::operator* () @example @@ -14000,7 +14099,7 @@ gccjit::lvalue content = *ptr; Field access is provided separately for both lvalues and rvalues: @geindex gccjit;;lvalue;;access_field (C++ function) -@anchor{cp/topics/expressions gccjit lvalue access_field__gccjit field gccjit location}@anchor{1b2} +@anchor{cp/topics/expressions gccjit lvalue access_field__gccjit field gccjit location}@anchor{1b6} @deffn {C++ Function} gccjit::lvalue gccjit::lvalue::access_field (gccjit::field field, gccjit::location loc) Given an lvalue of struct or union type, access the given field, @@ -14016,7 +14115,7 @@ in C. @end deffn @geindex gccjit;;rvalue;;access_field (C++ function) -@anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{1b3} +@anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{1b7} @deffn {C++ Function} gccjit::rvalue gccjit::rvalue::access_field (gccjit::field field, gccjit::location loc) Given an rvalue of struct or union type, access the given field @@ -14032,7 +14131,7 @@ in C. @end deffn @geindex gccjit;;rvalue;;dereference_field (C++ function) -@anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{1b4} +@anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{1b8} @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference_field (gccjit::field field, gccjit::location loc) Given an rvalue of pointer type @code{T *} where T is of struct or union @@ -14048,7 +14147,7 @@ in C, itself equivalent to @code{(*EXPR).FIELD}. @end deffn @geindex gccjit;;context;;new_array_access (C++ function) -@anchor{cp/topics/expressions gccjit context new_array_access__gccjit rvalue gccjit rvalue gccjit location}@anchor{1b5} +@anchor{cp/topics/expressions gccjit context new_array_access__gccjit rvalue gccjit rvalue gccjit location}@anchor{1b9} @deffn {C++ Function} gccjit::lvalue gccjit::context::new_array_access (gccjit::rvalue ptr, gccjit::rvalue index, gccjit::location loc) Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at @@ -14067,7 +14166,7 @@ in C (or, indeed, to @code{PTR + INDEX}). Parameter "loc" is optional. @end deffn -For array accesses where you don't need to specify a @pxref{14b,,gccjit;;location}, +For array accesses where you don't need to specify a @pxref{14f,,gccjit;;location}, two overloaded operators are available: @quotation @@ -14107,7 +14206,7 @@ gccjit::lvalue element = array[0]; @c . @node Creating and using functions<2>,Source Locations<2>,Expressions<2>,Topic Reference<2> -@anchor{cp/topics/functions doc}@anchor{1b6}@anchor{cp/topics/functions creating-and-using-functions}@anchor{1b7} +@anchor{cp/topics/functions doc}@anchor{1ba}@anchor{cp/topics/functions creating-and-using-functions}@anchor{1bb} @subsection Creating and using functions @@ -14120,36 +14219,36 @@ gccjit::lvalue element = array[0]; @end menu @node Params<2>,Functions<2>,,Creating and using functions<2> -@anchor{cp/topics/functions params}@anchor{1b8} +@anchor{cp/topics/functions params}@anchor{1bc} @subsubsection Params @geindex gccjit;;param (C++ class) -@anchor{cp/topics/functions gccjit param}@anchor{1b9} +@anchor{cp/topics/functions gccjit param}@anchor{1bd} @deffn {C++ Class} gccjit::param A @cite{gccjit::param} represents a parameter to a function. @end deffn @geindex gccjit;;context;;new_param (C++ function) -@anchor{cp/topics/functions gccjit context new_param__gccjit type cCP gccjit location}@anchor{11a} +@anchor{cp/topics/functions gccjit context new_param__gccjit type cCP gccjit location}@anchor{11e} @deffn {C++ Function} gccjit::param gccjit::context::new_param (gccjit::type type, const char* name, gccjit::location loc) In preparation for creating a function, create a new parameter of the given type and name. @end deffn -@pxref{1b9,,gccjit;;param} is a subclass of @pxref{1ab,,gccjit;;lvalue} (and thus -of @pxref{171,,gccjit;;rvalue} and @pxref{158,,gccjit;;object}). It is a thin +@pxref{1bd,,gccjit;;param} is a subclass of @pxref{1af,,gccjit;;lvalue} (and thus +of @pxref{175,,gccjit;;rvalue} and @pxref{15c,,gccjit;;object}). It is a thin wrapper around the C API's @pxref{25,,gcc_jit_param *}. @node Functions<2>,Blocks<2>,Params<2>,Creating and using functions<2> -@anchor{cp/topics/functions functions}@anchor{1ba} +@anchor{cp/topics/functions functions}@anchor{1be} @subsubsection Functions @geindex gccjit;;function (C++ class) -@anchor{cp/topics/functions gccjit function}@anchor{1bb} +@anchor{cp/topics/functions gccjit function}@anchor{1bf} @deffn {C++ Class} gccjit::function A @cite{gccjit::function} represents a function - either one that we're @@ -14157,7 +14256,7 @@ creating ourselves, or one that we're referencing. @end deffn @geindex gccjit;;context;;new_function (C++ function) -@anchor{cp/topics/functions gccjit context new_function__enum gccjit type cCP std vector param R i gccjit location}@anchor{1bc} +@anchor{cp/topics/functions gccjit context new_function__enum gccjit type cCP std vector param R i gccjit location}@anchor{1c0} @deffn {C++ Function} gccjit::function gccjit::context::new_function (enum gcc_jit_function_kind, gccjit::type return_type, const char* name, std::vector& params, int is_variadic, gccjit::location loc) Create a gcc_jit_function with the given name and parameters. @@ -14168,29 +14267,29 @@ This is a wrapper around the C API's @pxref{11,,gcc_jit_context_new_function()}. @end deffn @geindex gccjit;;context;;get_builtin_function (C++ function) -@anchor{cp/topics/functions gccjit context get_builtin_function__cCP}@anchor{1bd} +@anchor{cp/topics/functions gccjit context get_builtin_function__cCP}@anchor{1c1} @deffn {C++ Function} gccjit::function gccjit::context::get_builtin_function (const char* name) This is a wrapper around the C API's -@pxref{d7,,gcc_jit_context_get_builtin_function()}. +@pxref{d8,,gcc_jit_context_get_builtin_function()}. @end deffn @geindex gccjit;;function;;get_param (C++ function) -@anchor{cp/topics/functions gccjit function get_param__iC}@anchor{1be} +@anchor{cp/topics/functions gccjit function get_param__iC}@anchor{1c2} @deffn {C++ Function} gccjit::param gccjit::function::get_param (int index) const Get the param of the given index (0-based). @end deffn @geindex gccjit;;function;;dump_to_dot (C++ function) -@anchor{cp/topics/functions gccjit function dump_to_dot__cCP}@anchor{12d} +@anchor{cp/topics/functions gccjit function dump_to_dot__cCP}@anchor{131} @deffn {C++ Function} void gccjit::function::dump_to_dot (const char* path) Emit the function in graphviz format to the given path. @end deffn @geindex gccjit;;function;;new_local (C++ function) -@anchor{cp/topics/functions gccjit function new_local__gccjit type cCP gccjit location}@anchor{124} +@anchor{cp/topics/functions gccjit function new_local__gccjit type cCP gccjit location}@anchor{128} @deffn {C++ Function} gccjit::lvalue gccjit::function::new_local (gccjit::type type, const char* name, gccjit::location loc) Create a new local variable within the function, of the given type and @@ -14198,19 +14297,19 @@ name. @end deffn @node Blocks<2>,Statements<2>,Functions<2>,Creating and using functions<2> -@anchor{cp/topics/functions blocks}@anchor{1bf} +@anchor{cp/topics/functions blocks}@anchor{1c3} @subsubsection Blocks @geindex gccjit;;block (C++ class) -@anchor{cp/topics/functions gccjit block}@anchor{1c0} +@anchor{cp/topics/functions gccjit block}@anchor{1c4} @deffn {C++ Class} gccjit::block A @cite{gccjit::block} represents a basic block within a function i.e. a sequence of statements with a single entry point and a single exit point. -@pxref{1c0,,gccjit;;block} is a subclass of @pxref{158,,gccjit;;object}. +@pxref{1c4,,gccjit;;block} is a subclass of @pxref{15c,,gccjit;;object}. The first basic block that you create within a function will be the entrypoint. @@ -14224,7 +14323,7 @@ one function. @end deffn @geindex gccjit;;function;;new_block (C++ function) -@anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{1c1} +@anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{1c5} @deffn {C++ Function} gccjit::block gccjit::function::new_block (const char* name) Create a basic block of the given name. The name may be NULL, but @@ -14234,12 +14333,12 @@ messages. @end deffn @node Statements<2>,,Blocks<2>,Creating and using functions<2> -@anchor{cp/topics/functions statements}@anchor{1c2} +@anchor{cp/topics/functions statements}@anchor{1c6} @subsubsection Statements @geindex gccjit;;block;;add_eval (C++ function) -@anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{1a5} +@anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{1a9} @deffn {C++ Function} void gccjit::block::add_eval (gccjit::rvalue rvalue, gccjit::location loc) Add evaluation of an rvalue, discarding the result @@ -14255,7 +14354,7 @@ This is equivalent to this C code: @end deffn @geindex gccjit;;block;;add_assignment (C++ function) -@anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{126} +@anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{12a} @deffn {C++ Function} void gccjit::block::add_assignment (gccjit::lvalue lvalue, gccjit::rvalue rvalue, gccjit::location loc) Add evaluation of an rvalue, assigning the result to the given @@ -14271,7 +14370,7 @@ lvalue = rvalue; @end deffn @geindex gccjit;;block;;add_assignment_op (C++ function) -@anchor{cp/topics/functions gccjit block add_assignment_op__gccjit lvalue enum gccjit rvalue gccjit location}@anchor{12a} +@anchor{cp/topics/functions gccjit block add_assignment_op__gccjit lvalue enum gccjit rvalue gccjit location}@anchor{12e} @deffn {C++ Function} void gccjit::block::add_assignment_op (gccjit::lvalue lvalue, enum gcc_jit_binary_op, gccjit::rvalue rvalue, gccjit::location loc) Add evaluation of an rvalue, using the result to modify an @@ -14301,7 +14400,7 @@ loop_body.add_assignment_op ( @end deffn @geindex gccjit;;block;;add_comment (C++ function) -@anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{135} +@anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{139} @deffn {C++ Function} void gccjit::block::add_comment (const char* text, gccjit::location loc) Add a no-op textual comment to the internal representation of the @@ -14315,7 +14414,7 @@ Parameter "loc" is optional. @end deffn @geindex gccjit;;block;;end_with_conditional (C++ function) -@anchor{cp/topics/functions gccjit block end_with_conditional__gccjit rvalue gccjit block gccjit block gccjit location}@anchor{129} +@anchor{cp/topics/functions gccjit block end_with_conditional__gccjit rvalue gccjit block gccjit block gccjit location}@anchor{12d} @deffn {C++ Function} void gccjit::block::end_with_conditional (gccjit::rvalue boolval, gccjit::block on_true, gccjit::block on_false, gccjit::location loc) Terminate a block by adding evaluation of an rvalue, branching on the @@ -14336,7 +14435,7 @@ block, boolval, on_true, and on_false must be non-NULL. @end deffn @geindex gccjit;;block;;end_with_jump (C++ function) -@anchor{cp/topics/functions gccjit block end_with_jump__gccjit block gccjit location}@anchor{1c3} +@anchor{cp/topics/functions gccjit block end_with_jump__gccjit block gccjit location}@anchor{1c7} @deffn {C++ Function} void gccjit::block::end_with_jump (gccjit::block target, gccjit::location loc) Terminate a block by adding a jump to the given target block. @@ -14351,7 +14450,7 @@ goto target; @end deffn @geindex gccjit;;block;;end_with_return (C++ function) -@anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{1c4} +@anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{1c8} @deffn {C++ Function} void gccjit::block::end_with_return (gccjit::rvalue rvalue, gccjit::location loc) Terminate a block. @@ -14385,7 +14484,7 @@ return; @end deffn @geindex gccjit;;block;;end_with_switch (C++ function) -@anchor{cp/topics/functions gccjit block end_with_switch__gccjit rvalue gccjit block std vector gccjit case_ gccjit location}@anchor{1c5} +@anchor{cp/topics/functions gccjit block end_with_switch__gccjit rvalue gccjit block std vector gccjit case_ gccjit location}@anchor{1c9} @deffn {C++ Function} void gccjit::block::end_with_switch (gccjit::rvalue expr, gccjit::block default_block, std::vector cases, gccjit::location loc) Terminate a block by adding evalation of an rvalue, then performing @@ -14428,14 +14527,14 @@ The API entrypoints relating to switch statements and cases: @itemize * @item -@pxref{1c5,,gccjit;;block;;end_with_switch()} +@pxref{1c9,,gccjit;;block;;end_with_switch()} @item -@pxref{1c6,,gccjit;;context;;new_case()} +@pxref{1ca,,gccjit;;context;;new_case()} @end itemize @end quotation -were added in @pxref{e5,,LIBGCCJIT_ABI_3}; you can test for their presence +were added in @pxref{e6,,LIBGCCJIT_ABI_3}; you can test for their presence using @example @@ -14445,21 +14544,21 @@ using @noindent @geindex gccjit;;block;;end_with_switch;;gccjit;;case_ (C++ class) -@anchor{cp/topics/functions gccjit block end_with_switch gccjit case_}@anchor{1c7} +@anchor{cp/topics/functions gccjit block end_with_switch gccjit case_}@anchor{1cb} @deffn {C++ Class} gccjit::case_ @end deffn A @cite{gccjit::case_} represents a case within a switch statement, and -is created within a particular @pxref{143,,gccjit;;context} using -@pxref{1c6,,gccjit;;context;;new_case()}. It is a subclass of -@pxref{158,,gccjit;;object}. +is created within a particular @pxref{147,,gccjit;;context} using +@pxref{1ca,,gccjit;;context;;new_case()}. It is a subclass of +@pxref{15c,,gccjit;;object}. Each case expresses a multivalued range of integer values. You can express single-valued cases by passing in the same value for both @cite{min_value} and @cite{max_value}. @geindex gccjit;;block;;end_with_switch;;gccjit;;context;;new_case (C++ function) -@anchor{cp/topics/functions gccjit block end_with_switch gccjit context new_case__gccjit rvalue gccjit rvalue gccjit block}@anchor{1c6} +@anchor{cp/topics/functions gccjit block end_with_switch gccjit context new_case__gccjit rvalue gccjit rvalue gccjit block}@anchor{1ca} @deffn {C++ Function} gccjit::case_* gccjit::context::new_case (gccjit::rvalue min_value, gccjit::rvalue max_value, gccjit::block dest_block) Create a new gccjit::case for use in a switch statement. @@ -14570,12 +14669,12 @@ create_code (gcc_jit_context *c_ctxt, void *user_data) @c . @node Source Locations<2>,Compiling a context<2>,Creating and using functions<2>,Topic Reference<2> -@anchor{cp/topics/locations source-locations}@anchor{1c8}@anchor{cp/topics/locations doc}@anchor{1c9} +@anchor{cp/topics/locations source-locations}@anchor{1cc}@anchor{cp/topics/locations doc}@anchor{1cd} @subsection Source Locations @geindex gccjit;;location (C++ class) -@anchor{cp/topics/locations gccjit location}@anchor{14b} +@anchor{cp/topics/locations gccjit location}@anchor{14f} @deffn {C++ Class} gccjit::location A @cite{gccjit::location} encapsulates a source code location, so that @@ -14586,10 +14685,10 @@ single-step through your language. @cite{gccjit::location} instances are optional: you can always omit them from any C++ API entrypoint accepting one. -You can construct them using @pxref{139,,gccjit;;context;;new_location()}. +You can construct them using @pxref{13d,,gccjit;;context;;new_location()}. You need to enable @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the -@pxref{143,,gccjit;;context} for these locations to actually be usable by +@pxref{147,,gccjit;;context} for these locations to actually be usable by the debugger: @example @@ -14600,7 +14699,7 @@ ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1); @end deffn @geindex gccjit;;context;;new_location (C++ function) -@anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{139} +@anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{13d} @deffn {C++ Function} gccjit::location gccjit::context::new_location (const char* filename, int line, int column) Create a @cite{gccjit::location} instance representing the given source @@ -14613,13 +14712,13 @@ location. @end menu @node Faking it<2>,,,Source Locations<2> -@anchor{cp/topics/locations faking-it}@anchor{1ca} +@anchor{cp/topics/locations faking-it}@anchor{1ce} @subsubsection Faking it If you don't have source code for your internal representation, but need to debug, you can generate a C-like representation of the functions in -your context using @pxref{14a,,gccjit;;context;;dump_to_file()}: +your context using @pxref{14e,,gccjit;;context;;dump_to_file()}: @example ctxt.dump_to_file ("/tmp/something.c", @@ -14651,13 +14750,13 @@ file, giving you @emph{something} you can step through in the debugger. @c . @node Compiling a context<2>,,Source Locations<2>,Topic Reference<2> -@anchor{cp/topics/compilation compiling-a-context}@anchor{1cb}@anchor{cp/topics/compilation doc}@anchor{1cc} +@anchor{cp/topics/compilation compiling-a-context}@anchor{1cf}@anchor{cp/topics/compilation doc}@anchor{1d0} @subsection Compiling a context -Once populated, a @pxref{143,,gccjit;;context} can be compiled to -machine code, either in-memory via @pxref{11c,,gccjit;;context;;compile()} or -to disk via @pxref{1cd,,gccjit;;context;;compile_to_file()}. +Once populated, a @pxref{147,,gccjit;;context} can be compiled to +machine code, either in-memory via @pxref{120,,gccjit;;context;;compile()} or +to disk via @pxref{1d1,,gccjit;;context;;compile_to_file()}. You can compile a context multiple times (using either form of compilation), although any errors that occur on the context will @@ -14670,12 +14769,12 @@ prevent any future compilation of that context. @end menu @node In-memory compilation<2>,Ahead-of-time compilation<2>,,Compiling a context<2> -@anchor{cp/topics/compilation in-memory-compilation}@anchor{1ce} +@anchor{cp/topics/compilation in-memory-compilation}@anchor{1d2} @subsubsection In-memory compilation @geindex gccjit;;context;;compile (C++ function) -@anchor{cp/topics/compilation gccjit context compile}@anchor{11c} +@anchor{cp/topics/compilation gccjit context compile}@anchor{120} @deffn {C++ Function} gcc_jit_result* gccjit::context::compile () This calls into GCC and builds the code, returning a @@ -14686,19 +14785,19 @@ This is a thin wrapper around the @end deffn @node Ahead-of-time compilation<2>,,In-memory compilation<2>,Compiling a context<2> -@anchor{cp/topics/compilation ahead-of-time-compilation}@anchor{1cf} +@anchor{cp/topics/compilation ahead-of-time-compilation}@anchor{1d3} @subsubsection Ahead-of-time compilation Although libgccjit is primarily aimed at just-in-time compilation, it can also be used for implementing more traditional ahead-of-time -compilers, via the @pxref{1cd,,gccjit;;context;;compile_to_file()} method. +compilers, via the @pxref{1d1,,gccjit;;context;;compile_to_file()} method. @geindex gccjit;;context;;compile_to_file (C++ function) -@anchor{cp/topics/compilation gccjit context compile_to_file__enum cCP}@anchor{1cd} +@anchor{cp/topics/compilation gccjit context compile_to_file__enum cCP}@anchor{1d1} @deffn {C++ Function} void gccjit::context::compile_to_file (enum gcc_jit_output_kind, const char* output_path) -Compile the @pxref{143,,gccjit;;context} to a file of the given +Compile the @pxref{147,,gccjit;;context} to a file of the given kind. This is a thin wrapper around the @@ -14723,7 +14822,7 @@ This is a thin wrapper around the @c . @node Internals,Indices and tables,C++ bindings for libgccjit,Top -@anchor{internals/index internals}@anchor{1d0}@anchor{internals/index doc}@anchor{1d1} +@anchor{internals/index internals}@anchor{1d4}@anchor{internals/index doc}@anchor{1d5} @chapter Internals @@ -14739,7 +14838,7 @@ This is a thin wrapper around the @end menu @node Working on the JIT library,Running the test suite,,Internals -@anchor{internals/index working-on-the-jit-library}@anchor{1d2} +@anchor{internals/index working-on-the-jit-library}@anchor{1d6} @section Working on the JIT library @@ -14776,7 +14875,7 @@ gcc/libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), Here's what those configuration options mean: @geindex command line option; --enable-host-shared -@anchor{internals/index cmdoption--enable-host-shared}@anchor{1d3} +@anchor{internals/index cmdoption--enable-host-shared}@anchor{1d7} @deffn {Option} --enable-host-shared Configuring with this option means that the compiler is built as @@ -14785,7 +14884,7 @@ but it necessary for a shared library. @end deffn @geindex command line option; --enable-languages=jit@comma{}c++ -@anchor{internals/index cmdoption--enable-languages}@anchor{1d4} +@anchor{internals/index cmdoption--enable-languages}@anchor{1d8} @deffn {Option} --enable-languages=jit,c++ This specifies which frontends to build. The JIT library looks like @@ -14804,7 +14903,7 @@ c++: error trying to exec 'cc1plus': execvp: No such file or directory @end deffn @geindex command line option; --disable-bootstrap -@anchor{internals/index cmdoption--disable-bootstrap}@anchor{1d5} +@anchor{internals/index cmdoption--disable-bootstrap}@anchor{1d9} @deffn {Option} --disable-bootstrap For hacking on the "jit" subdirectory, performing a full @@ -14814,7 +14913,7 @@ the compiler can still bootstrap itself. @end deffn @geindex command line option; --enable-checking=release -@anchor{internals/index cmdoption--enable-checking}@anchor{1d6} +@anchor{internals/index cmdoption--enable-checking}@anchor{1da} @deffn {Option} --enable-checking=release The compile can perform extensive self-checking as it runs, useful when @@ -14825,7 +14924,7 @@ disable this self-checking. @end deffn @node Running the test suite,Environment variables,Working on the JIT library,Internals -@anchor{internals/index running-the-test-suite}@anchor{1d7} +@anchor{internals/index running-the-test-suite}@anchor{1db} @section Running the test suite @@ -14888,7 +14987,7 @@ and once a test has been compiled, you can debug it directly: @end menu @node Running under valgrind,,,Running the test suite -@anchor{internals/index running-under-valgrind}@anchor{1d8} +@anchor{internals/index running-under-valgrind}@anchor{1dc} @subsection Running under valgrind @@ -14936,7 +15035,7 @@ When running under valgrind, it's best to have configured gcc with various known false positives. @node Environment variables,Packaging notes,Running the test suite,Internals -@anchor{internals/index environment-variables}@anchor{1d9} +@anchor{internals/index environment-variables}@anchor{1dd} @section Environment variables @@ -14944,7 +15043,7 @@ When running client code against a locally-built libgccjit, three environment variables need to be set up: @geindex environment variable; LD_LIBRARY_PATH -@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{1da} +@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{1de} @deffn {Environment Variable} LD_LIBRARY_PATH @quotation @@ -14966,7 +15065,7 @@ libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux), @end deffn @geindex environment variable; PATH -@anchor{internals/index envvar-PATH}@anchor{1db} +@anchor{internals/index envvar-PATH}@anchor{1df} @deffn {Environment Variable} PATH The library uses a driver executable for converting from .s assembler @@ -14985,7 +15084,7 @@ of development. @end deffn @geindex environment variable; LIBRARY_PATH -@anchor{internals/index envvar-LIBRARY_PATH}@anchor{1dc} +@anchor{internals/index envvar-LIBRARY_PATH}@anchor{1e0} @deffn {Environment Variable} LIBRARY_PATH The driver executable invokes the linker, and the latter needs to locate @@ -15021,11 +15120,11 @@ hello world @noindent @node Packaging notes,Overview of code structure,Environment variables,Internals -@anchor{internals/index packaging-notes}@anchor{1dd} +@anchor{internals/index packaging-notes}@anchor{1e1} @section Packaging notes -The configure-time option @pxref{1d3,,--enable-host-shared} is needed when +The configure-time option @pxref{1d7,,--enable-host-shared} is needed when building the jit in order to get position-independent code. This will slow down the regular compiler by a few percent. Hence when packaging gcc with libgccjit, please configure and build twice: @@ -15036,10 +15135,10 @@ with libgccjit, please configure and build twice: @itemize * @item -once without @pxref{1d3,,--enable-host-shared} for most languages, and +once without @pxref{1d7,,--enable-host-shared} for most languages, and @item -once with @pxref{1d3,,--enable-host-shared} for the jit +once with @pxref{1d7,,--enable-host-shared} for the jit @end itemize @end quotation @@ -15083,7 +15182,7 @@ popd @noindent @node Overview of code structure,Design notes,Packaging notes,Internals -@anchor{internals/index overview-of-code-structure}@anchor{1de} +@anchor{internals/index overview-of-code-structure}@anchor{1e2} @section Overview of code structure @@ -15560,7 +15659,7 @@ JIT: gcc::jit::logger::~logger() @noindent @node Design notes,Submitting patches,Overview of code structure,Internals -@anchor{internals/index design-notes}@anchor{1df} +@anchor{internals/index design-notes}@anchor{1e3} @section Design notes @@ -15573,7 +15672,7 @@ close as possible to the error; failing that, a good place is within @code{recording::context::validate ()} in jit-recording.c. @node Submitting patches,,Design notes,Internals -@anchor{internals/index submitting-patches}@anchor{1e0} +@anchor{internals/index submitting-patches}@anchor{1e4} @section Submitting patches @@ -15707,7 +15806,7 @@ large and inconsequential (e.g. anchor renumbering), rather like generated committing to svn. @node Indices and tables,Index,Internals,Top -@anchor{index indices-and-tables}@anchor{1e1} +@anchor{index indices-and-tables}@anchor{1e5} @unnumbered Indices and tables diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst index f5c2d0f2616..76aa4eb4fc6 100644 --- a/gcc/jit/docs/topics/expressions.rst +++ b/gcc/jit/docs/topics/expressions.rst @@ -416,7 +416,8 @@ Function calls int numargs, \ gcc_jit_rvalue **args) - Given an rvalue of function pointer type, and the given table of + Given an rvalue of function pointer type (e.g. from + :c:func:`gcc_jit_context_new_function_ptr_type`), and the given table of argument rvalues, construct a call to the function pointer, with the result as an rvalue. @@ -452,19 +453,15 @@ Function calls Function pointers ***************** -.. function:: gcc_jit_rvalue *\ - gcc_jit_function_get_address (gcc_jit_function *fn,\ - gcc_jit_location *loc) - - Get the address of a function as an rvalue, of function pointer - type. +Function pointers can be obtained: - This entrypoint was added in :ref:`LIBGCCJIT_ABI_9`; you can test - for its presence using - - .. code-block:: c + * from a :c:type:`gcc_jit_function` using + :c:func:`gcc_jit_function_get_address`, or - #ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address + * from an existing function using + :c:func:`gcc_jit_context_new_rvalue_from_ptr`, + using a function pointer type obtained using + :c:func:`gcc_jit_context_new_function_ptr_type`. Type-coercion ************* diff --git a/gcc/jit/docs/topics/function-pointers.rst b/gcc/jit/docs/topics/function-pointers.rst new file mode 100644 index 00000000000..b5b9d1b72b5 --- /dev/null +++ b/gcc/jit/docs/topics/function-pointers.rst @@ -0,0 +1,80 @@ +.. Copyright (C) 2017 Free Software Foundation, Inc. + Originally contributed by David Malcolm + + This is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see + . + +.. default-domain:: c + +Function pointers +================= + +You can generate calls that use a function pointer via +:c:func:`gcc_jit_context_new_call_through_ptr`. + +To do requires a :c:type:`gcc_jit_rvalue` of the correct function pointer type. + +Function pointers for a :c:type:`gcc_jit_function` can be obtained +via :c:func:`gcc_jit_function_get_address`. + +.. function:: gcc_jit_rvalue *\ + gcc_jit_function_get_address (gcc_jit_function *fn,\ + gcc_jit_location *loc) + + Get the address of a function as an rvalue, of function pointer + type. + + This entrypoint was added in :ref:`LIBGCCJIT_ABI_9`; you can test + for its presence using + + .. code-block:: c + + #ifdef LIBGCCJIT_HAVE_gcc_jit_function_get_address + +Alternatively, given an existing function, you can obtain a pointer +to it in :c:type:`gcc_jit_rvalue` form using +:c:func:`gcc_jit_context_new_rvalue_from_ptr`, using a function pointer +type obtained using :c:func:`gcc_jit_context_new_function_ptr_type`. + +Here's an example of creating a function pointer type corresponding to C's +:c:type:`void (*) (int, int, int)`: + +.. code-block:: c + + gcc_jit_type *void_type = + gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_VOID); + gcc_jit_type *int_type = + gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT); + + /* Build the function ptr type. */ + gcc_jit_type *param_types[3]; + param_types[0] = int_type; + param_types[1] = int_type; + param_types[2] = int_type; + + gcc_jit_type *fn_ptr_type = + gcc_jit_context_new_function_ptr_type (ctxt, NULL, + void_type, + 3, param_types, 0); + +.. function:: gcc_jit_type *\ + gcc_jit_context_new_function_ptr_type (gcc_jit_context *ctxt,\ + gcc_jit_location *loc,\ + gcc_jit_type *return_type,\ + int num_params,\ + gcc_jit_type **param_types,\ + int is_variadic) + + Generate a :c:type:`gcc_jit_type` for a function pointer with the + given return type and parameters. diff --git a/gcc/jit/docs/topics/index.rst b/gcc/jit/docs/topics/index.rst index 890f21c5fd3..a912a6d933f 100644 --- a/gcc/jit/docs/topics/index.rst +++ b/gcc/jit/docs/topics/index.rst @@ -26,6 +26,7 @@ Topic Reference types.rst expressions.rst functions.rst + function-pointers.rst locations.rst compilation.rst compatibility.rst diff --git a/gcc/jit/docs/topics/types.rst b/gcc/jit/docs/topics/types.rst index c279222964b..35a82310b63 100644 --- a/gcc/jit/docs/topics/types.rst +++ b/gcc/jit/docs/topics/types.rst @@ -309,3 +309,9 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and :start-after: /* Quote from here in docs/topics/types.rst. */ :end-before: /* Quote up to here in docs/topics/types.rst. */ :language: c + +Function pointer types +---------------------- + +Function pointer types can be created using +:c:func:`gcc_jit_context_new_function_ptr_type`. -- 2.30.2