diff options
| author | David Malcolm <dmalcolm@redhat.com> | 2020-05-24 18:36:36 -0400 |
|---|---|---|
| committer | David Malcolm <dmalcolm@redhat.com> | 2020-05-26 10:47:46 -0400 |
| commit | 6f7585deedc140667fd496b48c9fc4f7d625605c (patch) | |
| tree | c95d7f29482b6cb3ca5575d40475f4262ffa8fea /gcc/jit | |
| parent | 6232d02b4fce4c67d39815aa8fb956e4b10a4e1b (diff) | |
| download | gcc-6f7585deedc140667fd496b48c9fc4f7d625605c.zip gcc-6f7585deedc140667fd496b48c9fc4f7d625605c.tar.gz gcc-6f7585deedc140667fd496b48c9fc4f7d625605c.tar.bz2 | |
jit: check for void types [PR 95296]
PR jit/95296 reports an ICE when using libgccjit to create a local of void
type.
This patch adds checking to various API entrypoints in libgccjit.c so that
they fail gracefully with an error if the client code attempts to create
various kinds of rvalues or types involving void types.
The patch documents these and various pre-existing restrictions on types
in the API.
gcc/jit/ChangeLog:
PR jit/95296
* docs/topics/expressions.rst (Unary Operations): Document that
result_type of gcc_jit_context_new_unary_op must be a numeric type.
(Binary Operations): Likewise for gcc_jit_context_new_binary_op.
(Global variables): Document that "type" of
gcc_jit_context_new_global must be non-`void`.
* docs/topics/function-pointers.rst
(gcc_jit_context_new_function_ptr_type): Document that the
param_types must be non-void, but that return_type may be.
* docs/topics/functions.rst (Params): Document that
gcc_jit_context_new_param's type must be non-void.
(Functions): Likewise for gcc_jit_function_new_local.
* docs/topics/types.rst (gcc_jit_context_new_array_type): Document
that the type must be non-void.
(gcc_jit_context_new_field): Likewise.
* docs/_build/texinfo/Makefile: Regenerate.
* docs/_build/texinfo/libgccjit.texi: Regenerate.
* libgccjit.c (gcc_jit_context_new_array_type): Fail if
element_type is void.
(gcc_jit_context_new_field): Likewise for "type".
(gcc_jit_context_new_function_ptr_type): Likewise for each
element of param_types.
(gcc_jit_context_new_param): Likewise for "type".
(gcc_jit_context_new_global): Likewise.
(gcc_jit_function_new_local): Likewise.
(gcc_jit_type_get_aligned): Likewise.
gcc/testsuite/ChangeLog:
PR jit/95296
* jit.dg/test-error-gcc_jit_context_new_global-void-type.c: New
test.
* jit.dg/test-error-gcc_jit_function_new_local-void-type.c: New
test.
* jit.dg/test-fuzzer.c (fuzzer_init): Allow for make_random_type
to return NULL.
(get_random_type): Allow for elements in f->types to be NULL.
Diffstat (limited to 'gcc/jit')
| -rw-r--r-- | gcc/jit/docs/_build/texinfo/Makefile | 6 | ||||
| -rw-r--r-- | gcc/jit/docs/_build/texinfo/libgccjit.texi | 3917 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/expressions.rst | 6 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/function-pointers.rst | 2 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/functions.rst | 4 | ||||
| -rw-r--r-- | gcc/jit/docs/topics/types.rst | 6 | ||||
| -rw-r--r-- | gcc/jit/libgccjit.c | 34 |
7 files changed, 1402 insertions, 2573 deletions
diff --git a/gcc/jit/docs/_build/texinfo/Makefile b/gcc/jit/docs/_build/texinfo/Makefile index 87e3048..81c60f5 100644 --- a/gcc/jit/docs/_build/texinfo/Makefile +++ b/gcc/jit/docs/_build/texinfo/Makefile @@ -43,8 +43,8 @@ uninstall-info: info -$(TEXI2PDF) '$<' clean: - -rm -f *.info *.pdf *.txt *.html - -rm -f *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ky *.pg - -rm -f *.vr *.tp *.fn *.fns *.def *.defs *.cp *.cps *.ge *.ges *.mo + rm -f *.info *.pdf *.txt *.html + rm -f *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla *.ky *.pg + rm -f *.vr *.tp *.fn *.fns *.def *.defs *.cp *.cps *.ge *.ges *.mo .PHONY: all info plaintext html pdf install-info uninstall-info clean diff --git a/gcc/jit/docs/_build/texinfo/libgccjit.texi b/gcc/jit/docs/_build/texinfo/libgccjit.texi index f2d6d0e..8795b1d 100644 --- a/gcc/jit/docs/_build/texinfo/libgccjit.texi +++ b/gcc/jit/docs/_build/texinfo/libgccjit.texi @@ -3,23 +3,25 @@ @setfilename libgccjit.info @documentencoding UTF-8 @ifinfo -@*Generated by Sphinx 1.1.3.@* +@*Generated by Sphinx 1.8.4.@* @end ifinfo @settitle libgccjit Documentation @defindex ge -@paragraphindent 2 +@paragraphindent 0 @exampleindent 4 -@afourlatex +@finalout @dircategory Miscellaneous @direntry * libgccjit: (libgccjit.info). One line description of project. @end direntry +@definfoenclose strong,`,' +@definfoenclose emph,`,' @c %**end of header @copying @quotation -libgccjit 8.0.0 (experimental 20171031), October 31, 2017 +libgccjit 11.0.0 (experimental 20200526), May 26, 2020 David Malcolm @@ -66,8 +68,8 @@ Copyright @copyright{} 2014-2020 Free Software Foundation, Inc. This document describes libgccjit@footnote{http://gcc.gnu.org/wiki/JIT}, an API for embedding GCC inside programs and libraries. -Note that libgccjit is currently of "Alpha" quality; -the APIs are not yet set in stone, and they shouldn't be used in +Note that libgccjit is currently of “Alpha” quality; +the APIs are not yet set in stone, and they shouldn’t be used in production yet. There are actually two APIs for the library: @@ -79,7 +81,7 @@ There are actually two APIs for the library: a pure C API: @code{libgccjit.h} @item -a C++ wrapper API: @code{libgccjit++.h}. This is a collection of "thin" +a C++ wrapper API: @code{libgccjit++.h}. This is a collection of “thin” wrapper classes around the C API, to save typing. @end itemize @@ -115,7 +117,7 @@ Contents: Tutorial -* Tutorial part 1; "Hello world": Tutorial part 1 "Hello world". +* Tutorial part 1; “Hello world”: Tutorial part 1 “Hello world”. * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function. * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables. * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter. @@ -154,7 +156,7 @@ Behind the curtain: How does our code get optimized? Tutorial part 5: Implementing an Ahead-of-Time compiler -* The "brainf" language:: +* The “brainf” language:: * Converting a brainf script to libgccjit IR:: * Compiling a context to a file:: * Other forms of ahead-of-time-compilation:: @@ -234,6 +236,7 @@ Compiling a context ABI and API compatibility +* Programmatically checking version:: * ABI symbol tags:: ABI symbol tags @@ -249,6 +252,9 @@ ABI symbol tags * LIBGCCJIT_ABI_8:: * LIBGCCJIT_ABI_9:: * LIBGCCJIT_ABI_10:: +* LIBGCCJIT_ABI_11:: +* LIBGCCJIT_ABI_12:: +* LIBGCCJIT_ABI_13:: Performance @@ -261,7 +267,7 @@ C++ bindings for libgccjit Tutorial -* Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>. +* Tutorial part 1; “Hello world”: Tutorial part 1 “Hello world”<2>. * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>. * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>. * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>. @@ -382,9 +388,8 @@ Running the test suite @end detailmenu @end menu - @node Tutorial,Topic Reference,Top,Top -@anchor{intro/index libgccjit}@anchor{1}@anchor{intro/index doc}@anchor{2}@anchor{intro/index tutorial}@anchor{3} +@anchor{intro/index doc}@anchor{1}@anchor{intro/index libgccjit}@anchor{2}@anchor{intro/index tutorial}@anchor{3} @chapter Tutorial @@ -406,7 +411,7 @@ Running the test suite @c <http://www.gnu.org/licenses/>. @menu -* Tutorial part 1; "Hello world": Tutorial part 1 "Hello world". +* Tutorial part 1; “Hello world”: Tutorial part 1 “Hello world”. * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function. * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables. * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter. @@ -414,18 +419,18 @@ Running the test suite @end menu -@node Tutorial part 1 "Hello world",Tutorial part 2 Creating a trivial machine code function,,Tutorial +@node Tutorial part 1 “Hello world”,Tutorial part 2 Creating a trivial machine code function,,Tutorial @anchor{intro/tutorial01 doc}@anchor{4}@anchor{intro/tutorial01 tutorial-part-1-hello-world}@anchor{5} -@section Tutorial part 1: "Hello world" +@section Tutorial part 1: “Hello world” -Before we look at the details of the API, let's look at building and +Before we look at the details of the API, let’s look at building and running programs that use the library. -Here's a toy "hello world" program that uses the library to synthesize +Here’s a toy “hello world” program that uses the library to synthesize a call to @cite{printf} and uses it to write a message to stdout. -Don't worry about the content of the program for now; we'll cover +Don’t worry about the content of the program for now; we’ll cover the details in later parts of this tutorial. @quotation @@ -554,10 +559,7 @@ main (int argc, char **argv) gcc_jit_result_release (result); return 0; @} - @end example - -@noindent @end quotation Copy the above to @cite{tut01-hello-world.c}. @@ -572,8 +574,6 @@ $ gcc \ -lgccjit @end example -@noindent - You should then be able to run the built program: @example @@ -581,8 +581,6 @@ $ ./tut01-hello-world hello world @end example -@noindent - @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @c @@ -600,7 +598,7 @@ hello world @c along with this program. If not, see @c <http://www.gnu.org/licenses/>. -@node Tutorial part 2 Creating a trivial machine code function,Tutorial part 3 Loops and variables,Tutorial part 1 "Hello world",Tutorial +@node Tutorial part 2 Creating a trivial machine code function,Tutorial part 3 Loops and variables,Tutorial part 1 “Hello world”,Tutorial @anchor{intro/tutorial02 doc}@anchor{6}@anchor{intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{7} @section Tutorial part 2: Creating a trivial machine code function @@ -614,8 +612,6 @@ int square (int i) @} @end example -@noindent - How can we construct this at run-time using libgccjit? First we need to include the relevant header: @@ -624,47 +620,39 @@ First we need to include the relevant header: #include <libgccjit.h> @end example -@noindent - All state associated with compilation is associated with a -@pxref{8,,gcc_jit_context *}. +@ref{8,,gcc_jit_context *}. -Create one using @pxref{9,,gcc_jit_context_acquire()}: +Create one using @ref{9,,gcc_jit_context_acquire()}: @example gcc_jit_context *ctxt; ctxt = gcc_jit_context_acquire (); @end example -@noindent - 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 @pxref{a,,gcc_jit_type *}, using -@pxref{b,,gcc_jit_context_get_type()}: +all of the expressions are of the C @cite{int} type, so let’s obtain this from +the context, as a @ref{a,,gcc_jit_type *}, using +@ref{b,,gcc_jit_context_get_type()}: @example gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT); @end example -@noindent +@ref{a,,gcc_jit_type *} is an example of a “contextual” object: every +entity in the API is associated with a @ref{8,,gcc_jit_context *}. -@pxref{a,,gcc_jit_type *} is an example of a "contextual" object: every -entity in the API is associated with a @pxref{8,,gcc_jit_context *}. - -Memory management is easy: all such "contextual" objects are automatically +Memory management is easy: all such “contextual” objects are automatically cleaned up for you when the context is released, using -@pxref{c,,gcc_jit_context_release()}: +@ref{c,,gcc_jit_context_release()}: @example gcc_jit_context_release (ctxt); @end example -@noindent - -so you don't need to manually track and cleanup all objects, just the +so you don’t need to manually track and cleanup all objects, just the contexts. Although the API is C-based, there is a form of class hierarchy, which @@ -683,50 +671,40 @@ looks like this: +- gcc_jit_param @end example -@noindent - There are casting methods for upcasting from subclasses to parent classes. -For example, @pxref{d,,gcc_jit_type_as_object()}: +For example, @ref{d,,gcc_jit_type_as_object()}: @example gcc_jit_object *obj = gcc_jit_type_as_object (int_type); @end example -@noindent - -One thing you can do with a @pxref{e,,gcc_jit_object *} is +One thing you can do with a @ref{e,,gcc_jit_object *} is to ask it for a human-readable description, using -@pxref{f,,gcc_jit_object_get_debug_string()}: +@ref{f,,gcc_jit_object_get_debug_string()}: @example printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj)); @end example -@noindent - giving this text on stdout: @example obj: int @end example -@noindent - This is invaluable when debugging. -Let's create the function. To do so, we first need to construct +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{10,,gcc_jit_context_new_param()}: +using @ref{10,,gcc_jit_context_new_param()}: @example gcc_jit_param *param_i = gcc_jit_context_new_param (ctxt, NULL, int_type, "i"); @end example -@noindent - Now we can create the function, using -@pxref{11,,gcc_jit_context_new_function()}: +@ref{11,,gcc_jit_context_new_function()}: @example gcc_jit_function *func = @@ -738,8 +716,6 @@ gcc_jit_function *func = 0); @end example -@noindent - To define the code within the function, we must create basic blocks containing statements. @@ -752,12 +728,10 @@ Our function has no control-flow, so we just need one basic block: gcc_jit_block *block = gcc_jit_function_new_block (func, NULL); @end example -@noindent - Our basic block is relatively simple: it immediately terminates by returning the value of an expression. -We can build the expression using @pxref{12,,gcc_jit_context_new_binary_op()}: +We can build the expression using @ref{12,,gcc_jit_context_new_binary_op()}: @example gcc_jit_rvalue *expr = @@ -768,12 +742,10 @@ gcc_jit_rvalue *expr = gcc_jit_param_as_rvalue (param_i)); @end example -@noindent - -A @pxref{13,,gcc_jit_rvalue *} is another example of a -@pxref{e,,gcc_jit_object *} subclass. We can upcast it using -@pxref{14,,gcc_jit_rvalue_as_object()} and as before print it with -@pxref{f,,gcc_jit_object_get_debug_string()}. +A @ref{13,,gcc_jit_rvalue *} is another example of a +@ref{e,,gcc_jit_object *} subclass. We can upcast it using +@ref{14,,gcc_jit_rvalue_as_object()} and as before print it with +@ref{f,,gcc_jit_object_get_debug_string()}. @example printf ("expr: %s\n", @@ -781,17 +753,13 @@ printf ("expr: %s\n", gcc_jit_rvalue_as_object (expr))); @end example -@noindent - giving this output: @example expr: i * i @end example -@noindent - -Creating the expression in itself doesn't do anything; we have to add +Creating the expression in itself doesn’t do anything; we have to add this expression to a statement within the block. In this case, we use it to build a return statement, which terminates the basic block: @@ -799,29 +767,23 @@ to build a return statement, which terminates the basic block: gcc_jit_block_end_with_return (block, NULL, expr); @end example -@noindent - -OK, we've populated the context. We can now compile it using -@pxref{15,,gcc_jit_context_compile()}: +OK, we’ve populated the context. We can now compile it using +@ref{15,,gcc_jit_context_compile()}: @example gcc_jit_result *result; result = gcc_jit_context_compile (ctxt); @end example -@noindent - -and get a @pxref{16,,gcc_jit_result *}. +and get a @ref{16,,gcc_jit_result *}. -At this point we're done with the context; we can release it: +At this point we’re done with the context; we can release it: @example gcc_jit_context_release (ctxt); @end example -@noindent - -We can now use @pxref{17,,gcc_jit_result_get_code()} to look up a specific +We can now use @ref{17,,gcc_jit_result_get_code()} to look up a specific machine code routine within the result, in this case, the function we created above. @@ -834,8 +796,6 @@ if (!fn_ptr) @} @end example -@noindent - We can now cast the pointer to an appropriate function pointer type, and then call it: @@ -845,23 +805,17 @@ fn_type square = (fn_type)fn_ptr; printf ("result: %d", square (5)); @end example -@noindent - @example result: 25 @end example -@noindent - -Once we're done with the code, we can release the result: +Once we’re done with the code, we can release the result: @example gcc_jit_result_release (result); @end example -@noindent - -We can't call @code{square} anymore once we've released @code{result}. +We can’t call @code{square} anymore once we’ve released @code{result}. @menu * Error-handling:: @@ -887,8 +841,6 @@ problem: ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *) @end example -@noindent - The API is designed to cope with errors without crashing, so you can get away with having a single error-handling check in your code: @@ -901,9 +853,7 @@ if (!fn_ptr) @} @end example -@noindent - -For more information, see the @pxref{19,,error-handling guide} +For more information, see the @ref{19,,error-handling guide} within the Topic eference. @node Options,Full example,Error-handling,Tutorial part 2 Creating a trivial machine code function @@ -911,15 +861,15 @@ within the Topic eference. @subsection Options -To get more information on what's going on, you can set debugging flags -on the context using @pxref{1b,,gcc_jit_context_set_bool_option()}. +To get more information on what’s going on, you can set debugging flags +on the context using @ref{1b,,gcc_jit_context_set_bool_option()}. @c (I'm deliberately not mentioning @c :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE` here since I think @c it's probably more of use to implementors than to users) -Setting @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a -C-like representation to stderr when you compile (GCC's "GIMPLE" +Setting @ref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a +C-like representation to stderr when you compile (GCC’s “GIMPLE” representation): @example @@ -930,8 +880,6 @@ gcc_jit_context_set_bool_option ( result = gcc_jit_context_compile (ctxt); @end example -@noindent - @example square (signed int i) @{ @@ -943,10 +891,8 @@ square (signed int i) @} @end example -@noindent - We can see the generated machine code in assembler form (on stderr) by -setting @pxref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context +setting @ref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context before compiling: @example @@ -957,8 +903,6 @@ gcc_jit_context_set_bool_option ( result = gcc_jit_context_compile (ctxt); @end example -@noindent - @example .file "fake.c" .text @@ -986,12 +930,10 @@ square: .section .note.GNU-stack,"",@@progbits @end example -@noindent - -By default, no optimizations are performed, the equivalent of GCC's +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{1e,,gcc_jit_context_set_int_option()} with -@pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: +@ref{1e,,gcc_jit_context_set_int_option()} with +@ref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: @example gcc_jit_context_set_int_option ( @@ -1000,8 +942,6 @@ gcc_jit_context_set_int_option ( 3); @end example -@noindent - @example .file "fake.c" .text @@ -1022,8 +962,6 @@ square: .section .note.GNU-stack,"",@@progbits @end example -@noindent - Naturally this has only a small effect on such a trivial function. @node Full example,,Options,Tutorial part 2 Creating a trivial machine code function @@ -1031,7 +969,7 @@ Naturally this has only a small effect on such a trivial function. @subsection Full example -Here's what the above looks like as a complete program: +Here’s what the above looks like as a complete program: @quotation @@ -1149,10 +1087,7 @@ main (int argc, char **argv) gcc_jit_result_release (result); return 0; @} - @end example - -@noindent @end quotation Building and running it: @@ -1168,8 +1103,6 @@ $ ./tut02-square result: 25 @end example -@noindent - @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @c @@ -1188,7 +1121,7 @@ result: 25 @c <http://www.gnu.org/licenses/>. @node Tutorial part 3 Loops and variables,Tutorial part 4 Adding JIT-compilation to a toy interpreter,Tutorial part 2 Creating a trivial machine code function,Tutorial -@anchor{intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{21}@anchor{intro/tutorial03 doc}@anchor{22} +@anchor{intro/tutorial03 doc}@anchor{21}@anchor{intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{22} @section Tutorial part 3: Loops and variables @@ -1205,14 +1138,12 @@ int loop_test (int n) return sum; @} @end example - -@noindent @end quotation This example demonstrates some more features of libgccjit, with local variables and a loop. -To break this down into libgccjit terms, it's usually easier to reword +To break this down into libgccjit terms, it’s usually easier to reword the @cite{for} loop as a @cite{while} loop, giving: @quotation @@ -1230,11 +1161,9 @@ int loop_test (int n) return sum; @} @end example - -@noindent @end quotation -Here's what the final control flow graph will look like: +Here’s what the final control flow graph will look like: @quotation @@ -1248,7 +1177,7 @@ Here's what the final control flow graph will look like: @end quotation As before, we include the libgccjit header and make a -@pxref{8,,gcc_jit_context *}. +@ref{8,,gcc_jit_context *}. @example #include <libgccjit.h> @@ -1259,8 +1188,6 @@ void test (void) ctxt = gcc_jit_context_acquire (); @end example -@noindent - The function works with the C @cite{int} type: @example @@ -1269,8 +1196,6 @@ gcc_jit_type *the_type = gcc_jit_type *return_type = the_type; @end example -@noindent - though we could equally well make it work on, say, @cite{double}: @example @@ -1278,9 +1203,7 @@ gcc_jit_type *the_type = gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_DOUBLE); @end example -@noindent - -Let's build the function: +Let’s build the function: @example gcc_jit_param *n = @@ -1294,8 +1217,6 @@ gcc_jit_function *func = 1, params, 0); @end example -@noindent - @menu * Expressions; lvalues and rvalues: Expressions lvalues and rvalues. * Control flow:: @@ -1309,14 +1230,14 @@ gcc_jit_function *func = @subsection Expressions: lvalues and rvalues -The base class of expression is the @pxref{13,,gcc_jit_rvalue *}, +The base class of expression is the @ref{13,,gcc_jit_rvalue *}, representing an expression that can be on the @emph{right}-hand side of an assignment: a value that can be computed somehow, and assigned @emph{to} a storage area (such as a variable). It has a specific -@pxref{a,,gcc_jit_type *}. +@ref{a,,gcc_jit_type *}. -Anothe important class is @pxref{24,,gcc_jit_lvalue *}. -A @pxref{24,,gcc_jit_lvalue *}. is something that can of the @emph{left}-hand +Anothe important class is @ref{24,,gcc_jit_lvalue *}. +A @ref{24,,gcc_jit_lvalue *}. is something that can of the @emph{left}-hand side of an assignment: a storage area (such as a variable). In other words, every assignment can be thought of as: @@ -1325,21 +1246,17 @@ In other words, every assignment can be thought of as: LVALUE = RVALUE; @end example -@noindent - -Note that @pxref{24,,gcc_jit_lvalue *} is a subclass of -@pxref{13,,gcc_jit_rvalue *}, where in an assignment of the form: +Note that @ref{24,,gcc_jit_lvalue *} is a subclass of +@ref{13,,gcc_jit_rvalue *}, where in an assignment of the form: @example LVALUE_A = LVALUE_B; @end example -@noindent - the @cite{LVALUE_B} implies reading the current value of that storage area, assigning it into the @cite{LVALUE_A}. -So far the only expressions we've seen are @cite{i * i}: +So far the only expressions we’ve seen are @cite{i * i}: @example gcc_jit_rvalue *expr = @@ -1350,17 +1267,15 @@ gcc_jit_rvalue *expr = gcc_jit_param_as_rvalue (param_i)); @end example -@noindent - -which is a @pxref{13,,gcc_jit_rvalue *}, and the various function +which is a @ref{13,,gcc_jit_rvalue *}, and the various function parameters: @cite{param_i} and @cite{param_n}, instances of -@pxref{25,,gcc_jit_param *}, which is a subclass of -@pxref{24,,gcc_jit_lvalue *} (and, in turn, of @pxref{13,,gcc_jit_rvalue *}): +@ref{25,,gcc_jit_param *}, which is a subclass of +@ref{24,,gcc_jit_lvalue *} (and, in turn, of @ref{13,,gcc_jit_rvalue *}): we can both read from and write to function parameters within the body of a function. Our new example has a couple of local variables. We create them by -calling @pxref{26,,gcc_jit_function_new_local()}, supplying a type and a +calling @ref{26,,gcc_jit_function_new_local()}, supplying a type and a name: @example @@ -1371,9 +1286,7 @@ gcc_jit_lvalue *sum = gcc_jit_function_new_local (func, NULL, the_type, "sum"); @end example -@noindent - -These are instances of @pxref{24,,gcc_jit_lvalue *} - they can be read from +These are instances of @ref{24,,gcc_jit_lvalue *} - they can be read from and written to. Note that there is no precanned way to create @emph{and} initialize a variable @@ -1383,8 +1296,6 @@ like in C: int i = 0; @end example -@noindent - 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. @@ -1412,8 +1323,8 @@ the body of the loop after the loop terminates (@cite{return sum}) @end enumerate -so we create these as @pxref{28,,gcc_jit_block *} instances within the -@pxref{29,,gcc_jit_function *}: +so we create these as @ref{28,,gcc_jit_block *} instances within the +@ref{29,,gcc_jit_function *}: @example gcc_jit_block *b_initial = @@ -1426,14 +1337,12 @@ gcc_jit_block *b_after_loop = gcc_jit_function_new_block (func, "after_loop"); @end example -@noindent - 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{2a,,gcc_jit_block_add_assignment()} to add -an assignment statement, and using @pxref{2b,,gcc_jit_context_zero()} to get +@ref{2a,,gcc_jit_block_add_assignment()} to add +an assignment statement, and using @ref{2b,,gcc_jit_context_zero()} to get the constant value @cite{0} for the relevant type for the right-hand side of the assignment: @@ -1451,21 +1360,17 @@ gcc_jit_block_add_assignment ( gcc_jit_context_zero (ctxt, the_type)); @end example -@noindent - We can then terminate the entry block by jumping to the conditional: @example gcc_jit_block_end_with_jump (b_initial, NULL, b_loop_cond); @end example -@noindent - The conditional block is equivalent to the line @cite{while (i < n)} from our C example. It contains a single statement: a conditional, which jumps to one of two destination blocks depending on a boolean -@pxref{13,,gcc_jit_rvalue *}, in this case the comparison of @cite{i} and @cite{n}. -We build the comparison using @pxref{2c,,gcc_jit_context_new_comparison()}: +@ref{13,,gcc_jit_rvalue *}, in this case the comparison of @cite{i} and @cite{n}. +We build the comparison using @ref{2c,,gcc_jit_context_new_comparison()}: @example /* (i >= n) */ @@ -1477,10 +1382,8 @@ We build the comparison using @pxref{2c,,gcc_jit_context_new_comparison()}: gcc_jit_param_as_rvalue (n)); @end example -@noindent - -and can then use this to add @cite{b_loop_cond}'s sole statement, via -@pxref{2d,,gcc_jit_block_end_with_conditional()}: +and can then use this to add @cite{b_loop_cond}’s sole statement, via +@ref{2d,,gcc_jit_block_end_with_conditional()}: @example /* Equivalent to: @@ -1495,13 +1398,11 @@ gcc_jit_block_end_with_conditional ( b_loop_body); /* on_false */ @end example -@noindent - 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{2e,,gcc_jit_block_add_assignment_op()} to handle these operations: +lvalue is modified “in-place”. We use +@ref{2e,,gcc_jit_block_add_assignment_op()} to handle these operations: @example /* sum += i * i */ @@ -1516,10 +1417,8 @@ gcc_jit_block_add_assignment_op ( gcc_jit_lvalue_as_rvalue (i))); @end example -@noindent - The @cite{i++} can be thought of as @cite{i += 1}, and can thus be handled in -a similar way. We use @pxref{2f,,gcc_jit_context_one()} to get the constant +a similar way. We use @ref{2f,,gcc_jit_context_one()} to get the constant value @cite{1} (for the relevant type) for the right-hand side of the assignment. @@ -1532,13 +1431,11 @@ gcc_jit_block_add_assignment_op ( gcc_jit_context_one (ctxt, the_type)); @end example -@noindent - @cartouche @quotation Note For numeric constants other than 0 or 1, we could use -@pxref{30,,gcc_jit_context_new_rvalue_from_int()} and -@pxref{31,,gcc_jit_context_new_rvalue_from_double()}. +@ref{30,,gcc_jit_context_new_rvalue_from_int()} and +@ref{31,,gcc_jit_context_new_rvalue_from_double()}. @end quotation @end cartouche @@ -1548,8 +1445,6 @@ The loop body completes by jumping back to the conditional: gcc_jit_block_end_with_jump (b_loop_body, NULL, b_loop_cond); @end example -@noindent - Finally, we populate the @cite{b_after_loop} block, reached when the loop conditional is false. We want to generate the equivalent of: @@ -1557,8 +1452,6 @@ conditional is false. We want to generate the equivalent of: return sum; @end example -@noindent - so the block is just one statement: @example @@ -1569,18 +1462,16 @@ gcc_jit_block_end_with_return ( gcc_jit_lvalue_as_rvalue (sum)); @end example -@noindent - @cartouche @quotation Note You can intermingle block creation with statement creation, but given that the terminator statements generally include references -to other blocks, I find it's clearer to create all the blocks, +to other blocks, I find it’s clearer to create all the blocks, @emph{then} all the statements. @end quotation @end cartouche -We've finished populating the function. As before, we can now compile it +We’ve finished populating the function. As before, we can now compile it to machine code: @example @@ -1595,28 +1486,22 @@ if (!loop_test) printf ("result: %d", loop_test (10)); @end example -@noindent - @example result: 285 @end example -@noindent - @node Visualizing the control flow graph,Full example<2>,Control flow,Tutorial part 3 Loops and variables @anchor{intro/tutorial03 visualizing-the-control-flow-graph}@anchor{32} @subsection Visualizing the control flow graph You can see the control flow graph of a function using -@pxref{33,,gcc_jit_function_dump_to_dot()}: +@ref{33,,gcc_jit_function_dump_to_dot()}: @example gcc_jit_function_dump_to_dot (func, "/tmp/sum-of-squares.dot"); @end example -@noindent - giving a .dot file in GraphViz format. You can convert this to an image using @cite{dot}: @@ -1625,8 +1510,6 @@ You can convert this to an image using @cite{dot}: $ dot -Tpng /tmp/sum-of-squares.dot -o /tmp/sum-of-squares.png @end example -@noindent - or use a viewer (my preferred one is xdot.py; see @indicateurl{https://github.com/jrfonseca/xdot.py}; on Fedora you can install it with @cite{yum install python-xdot}): @@ -1822,10 +1705,7 @@ main (int argc, char **argv) gcc_jit_result_release (result); return 0; @} - @end example - -@noindent @end quotation Building and running it: @@ -1841,8 +1721,6 @@ $ ./tut03-sum-of-squares loop_test returned: 285 @end example -@noindent - @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @c @@ -1861,11 +1739,11 @@ loop_test returned: 285 @c <http://www.gnu.org/licenses/>. @node Tutorial part 4 Adding JIT-compilation to a toy interpreter,Tutorial part 5 Implementing an Ahead-of-Time compiler,Tutorial part 3 Loops and variables,Tutorial -@anchor{intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{35}@anchor{intro/tutorial04 doc}@anchor{36} +@anchor{intro/tutorial04 doc}@anchor{35}@anchor{intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{36} @section Tutorial part 4: Adding JIT-compilation to a toy interpreter -In this example we construct a "toy" interpreter, and add JIT-compilation +In this example we construct a “toy” interpreter, and add JIT-compilation to it. @menu @@ -1887,7 +1765,7 @@ to it. @subsection Our toy interpreter -It's a stack-based interpreter, and is intended as a (very simple) example +It’s a stack-based interpreter, and is intended as a (very simple) example of the kind of bytecode interpreter seen in dynamic languages such as Python, Ruby etc. @@ -1912,7 +1790,7 @@ Functions can only take one parameter. Functions have a stack of @cite{int} values. @item -We'll implement function call within the interpreter by calling a +We’ll implement function call within the interpreter by calling a function in our implementation, rather than implementing our own frame stack. @@ -2118,7 +1996,7 @@ nonzero, jump to Programs can be interpreted, disassembled, and compiled to machine code. -The interpreter reads @code{.toy} scripts. Here's what a simple recursive +The interpreter reads @code{.toy} scripts. Here’s what a simple recursive factorial program looks like, the script @code{factorial.toy}. The parser ignores lines beginning with a @cite{#}. @@ -2175,10 +2053,7 @@ BINARY_MULT # 9: RETURN - @end example - -@noindent @end quotation The interpreter is a simple infinite loop with a big @code{switch} statement @@ -2284,10 +2159,7 @@ toyvm_function_interpret (toyvm_function *fn, int arg, FILE *trace) #undef POP @} - @end example - -@noindent @end quotation @node Compiling to machine code,Setting things up,Our toy interpreter,Tutorial part 4 Adding JIT-compilation to a toy interpreter @@ -2303,15 +2175,12 @@ then directly executed in-process: @example typedef int (*toyvm_compiled_code) (int); - @end example - -@noindent @end quotation -The lifetime of the code is tied to that of a @pxref{16,,gcc_jit_result *}. -We'll handle this by bundling them up in a structure, so that we can -clean them up together by calling @pxref{39,,gcc_jit_result_release()}: +The lifetime of the code is tied to that of a @ref{16,,gcc_jit_result *}. +We’ll handle this by bundling them up in a structure, so that we can +clean them up together by calling @ref{39,,gcc_jit_result_release()}: @quotation @@ -2323,20 +2192,17 @@ struct toyvm_compiled_function toyvm_compiled_code cf_code; @}; - @end example - -@noindent @end quotation -Our compiler isn't very sophisticated; it takes the implementation of +Our compiler isn’t very sophisticated; it takes the implementation of each opcode above, and maps it directly to the operations supported by the libgccjit API. How should we handle the stack? In theory we could calculate what the stack depth will be at each opcode, and optimize away the stack -manipulation "by hand". We'll see below that libgccjit is able to do -this for us, so we'll implement stack manipulation +manipulation “by hand”. We’ll see below that libgccjit is able to do +this for us, so we’ll implement stack manipulation in a direct way, by creating a @code{stack} array and @code{stack_depth} variables, local within the generated function, equivalent to this C code: @@ -2345,9 +2211,7 @@ int stack_depth; int stack[MAX_STACK_DEPTH]; @end example -@noindent - -We'll also have local variables @code{x} and @code{y} for use when implementing +We’ll also have local variables @code{x} and @code{y} for use when implementing the opcodes, equivalent to this: @example @@ -2355,8 +2219,6 @@ int x; int y; @end example -@noindent - This means our compiler has the following state: @quotation @@ -2386,10 +2248,7 @@ struct compilation_state @}; - @end example - -@noindent @end quotation @node Setting things up,Populating the function,Compiling to machine code,Tutorial part 4 Adding JIT-compilation to a toy interpreter @@ -2410,10 +2269,7 @@ First we create our types: gcc_jit_context_new_array_type (state.ctxt, NULL, state.int_type, MAX_STACK_DEPTH); - @end example - -@noindent @end quotation along with extracting a useful @cite{int} constant: @@ -2423,13 +2279,10 @@ along with extracting a useful @cite{int} constant: @example state.const_one = gcc_jit_context_one (state.ctxt, state.int_type); - @end example - -@noindent @end quotation -We'll implement push and pop in terms of the @code{stack} array and +We’ll implement push and pop in terms of the @code{stack} array and @code{stack_depth}. Here are helper functions for adding statements to a block, implementing pushing and popping values: @@ -2492,14 +2345,11 @@ add_pop (compilation_state *state, gcc_jit_lvalue_as_rvalue (state->stack_depth)))); @} - @end example - -@noindent @end quotation We will support single-stepping through the generated code in the -debugger, so we need to create @pxref{3b,,gcc_jit_location} instances, one +debugger, so we need to create @ref{3b,,gcc_jit_location} instances, one per operation in the source code. These will reference the lines of e.g. @code{factorial.toy}. @@ -2516,13 +2366,10 @@ e.g. @code{factorial.toy}. 0); /* column */ @} - @end example - -@noindent @end quotation -Let's create the function itself. As usual, we create its parameter +Let’s create the function itself. As usual, we create its parameter first, then use the parameter to create the function: @quotation @@ -2539,10 +2386,7 @@ first, then use the parameter to create the function: funcname, 1, &state.param_arg, 0); - @end example - -@noindent @end quotation We create the locals within the function. @@ -2563,10 +2407,7 @@ We create the locals within the function. gcc_jit_function_new_local (state.fn, NULL, state.int_type, "y"); - @end example - -@noindent @end quotation @node Populating the function,Verifying the control flow graph,Setting things up,Tutorial part 4 Adding JIT-compilation to a toy interpreter @@ -2574,7 +2415,7 @@ We create the locals within the function. @subsection Populating the function -There's some one-time initialization, and the API treats the first block +There’s some one-time initialization, and the API treats the first block you create as the entrypoint of the function, so we need to create that block first: @@ -2583,10 +2424,7 @@ block first: @example state.initial_block = gcc_jit_function_new_block (state.fn, "initial"); - @end example - -@noindent @end quotation We can now create blocks for each of the operations. Most of these will @@ -2602,13 +2440,10 @@ be consolidated into larger blocks when the optimizer runs. state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf); @} - @end example - -@noindent @end quotation -Now that we have a block it can jump to when it's done, we can populate +Now that we have a block it can jump to when it’s done, we can populate the initial block: @quotation @@ -2633,10 +2468,7 @@ the initial block: state.op_locs[0], state.op_blocks[0]); - @end example - -@noindent @end quotation We can now populate the blocks for the individual operations. We loop @@ -2657,16 +2489,13 @@ through them, adding instructions to their blocks: toyvm_op *op; op = &fn->fn_ops[pc]; - @end example - -@noindent @end quotation -We're going to have another big @code{switch} statement for implementing +We’re going to have another big @code{switch} statement for implementing the opcodes, this time for compiling them, rather than interpreting -them. It's helpful to have macros for implementing push and pop, so that -we can make the @code{switch} statement that's coming up look as much as +them. It’s helpful to have macros for implementing push and pop, so that +we can make the @code{switch} statement that’s coming up look as much as possible like the one above within the interpreter: @example @@ -2682,16 +2511,13 @@ possible like the one above within the interpreter: #define PUSH_Y() \ PUSH_RVALUE (gcc_jit_lvalue_as_rvalue (state.y)) - @end example -@noindent - @cartouche @quotation Note A particularly clever implementation would have an @emph{identical} @code{switch} statement shared by the interpreter and the compiler, with -some preprocessor "magic". We're not doing that here, for the sake +some preprocessor “magic”. We’re not doing that here, for the sake of simplicity. @end quotation @end cartouche @@ -2702,7 +2528,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{3d,,gcc_jit_block_add_comment()} to add descriptive comments +@ref{3d,,gcc_jit_block_add_comment()} to add descriptive comments to the internal representation. This is invaluable when looking through the generated IR for, say @code{factorial}: @@ -2712,10 +2538,7 @@ the generated IR for, say @code{factorial}: gcc_jit_block_add_comment (block, loc, opcode_names[op->op_opcode]); - @end example - -@noindent @end quotation We can now write the big @code{switch} statement that implements the @@ -2846,10 +2669,7 @@ individual opcodes, populating the relevant block with statements: assert(0); @} /* end of switch on opcode */ - @end example - -@noindent @end quotation Every block must be terminated, via a call to one of the @@ -2867,10 +2687,7 @@ to the next block. loc, next_block); - @end example - -@noindent @end quotation This is analogous to simply incrementing the program counter. @@ -2883,14 +2700,12 @@ This is analogous to simply incrementing the program counter. 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{33,,gcc_jit_function_dump_to_dot()}: +using @ref{33,,gcc_jit_function_dump_to_dot()}: @example gcc_jit_function_dump_to_dot (state.fn, "/tmp/factorial.dot"); @end example -@noindent - and viewing the result. Note how the label names, comments, and variable names show up in the dump, to make it easier to spot errors in our compiler. @@ -2917,174 +2732,6 @@ statements, the context is complete. We can now compile it, and extract machine code from the result: @quotation - -@example - gcc_jit_result *jit_result = gcc_jit_context_compile (state.ctxt); - gcc_jit_context_release (state.ctxt); - - toyvm_compiled_function *toyvm_result = - (toyvm_compiled_function *)calloc (1, sizeof (toyvm_compiled_function)); - if (!toyvm_result) - @{ - fprintf (stderr, "out of memory allocating toyvm_compiled_function\n"); - gcc_jit_result_release (jit_result); - return NULL; - @} - - toyvm_result->cf_jit_result = jit_result; - toyvm_result->cf_code = - (toyvm_compiled_code)gcc_jit_result_get_code (jit_result, - funcname); - - free (funcname); - - return toyvm_result; -@} - -char test[1024]; - -#define CHECK_NON_NULL(PTR) \ - do @{ \ - if ((PTR) != NULL) \ - @{ \ - pass ("%s: %s is non-null", test, #PTR); \ - @} \ - else \ - @{ \ - fail ("%s: %s is NULL", test, #PTR); \ - abort (); \ - @} \ - @} while (0) - -#define CHECK_VALUE(ACTUAL, EXPECTED) \ - do @{ \ - if ((ACTUAL) == (EXPECTED)) \ - @{ \ - pass ("%s: actual: %s == expected: %s", test, #ACTUAL, #EXPECTED); \ - @} \ - else \ - @{ \ - fail ("%s: actual: %s != expected: %s", test, #ACTUAL, #EXPECTED); \ - fprintf (stderr, "incorrect value\n"); \ - abort (); \ - @} \ - @} while (0) - -static void -test_script (const char *scripts_dir, const char *script_name, int input, - int expected_result) -@{ - char *script_path; - toyvm_function *fn; - int interpreted_result; - toyvm_compiled_function *compiled_fn; - toyvm_compiled_code code; - int compiled_result; - - snprintf (test, sizeof (test), "toyvm.c: %s", script_name); - - script_path = (char *)malloc (strlen (scripts_dir) - + strlen (script_name) + 1); - CHECK_NON_NULL (script_path); - sprintf (script_path, "%s%s", scripts_dir, script_name); - - fn = toyvm_function_parse (script_path, script_name); - CHECK_NON_NULL (fn); - - interpreted_result = toyvm_function_interpret (fn, input, NULL); - CHECK_VALUE (interpreted_result, expected_result); - - compiled_fn = toyvm_function_compile (fn); - CHECK_NON_NULL (compiled_fn); - - code = (toyvm_compiled_code)compiled_fn->cf_code; - CHECK_NON_NULL (code); - - compiled_result = code (input); - CHECK_VALUE (compiled_result, expected_result); - - gcc_jit_result_release (compiled_fn->cf_jit_result); - free (compiled_fn); - free (fn); - free (script_path); -@} - -#define PATH_TO_SCRIPTS ("/jit/docs/examples/tut04-toyvm/") - -static void -test_suite (void) -@{ - const char *srcdir; - char *scripts_dir; - - snprintf (test, sizeof (test), "toyvm.c"); - - /* We need to locate the test scripts. - Rely on "srcdir" being set in the environment. */ - - srcdir = getenv ("srcdir"); - CHECK_NON_NULL (srcdir); - - scripts_dir = (char *)malloc (strlen (srcdir) + strlen(PATH_TO_SCRIPTS) - + 1); - CHECK_NON_NULL (scripts_dir); - sprintf (scripts_dir, "%s%s", srcdir, PATH_TO_SCRIPTS); - - test_script (scripts_dir, "factorial.toy", 10, 3628800); - test_script (scripts_dir, "fibonacci.toy", 10, 55); - - free (scripts_dir); -@} - -int -main (int argc, char **argv) -@{ - const char *filename = NULL; - toyvm_function *fn = NULL; - - /* If called with no args, assume we're being run by the test suite. */ - if (argc < 3) - @{ - test_suite (); - return 0; - @} - - if (argc != 3) - @{ - fprintf (stdout, - "%s FILENAME INPUT: Parse and run a .toy file\n", - argv[0]); - exit (1); - @} - - filename = argv[1]; - fn = toyvm_function_parse (filename, filename); - if (!fn) - exit (1); - - if (0) - toyvm_function_disassemble (fn, stdout); - - printf ("interpreter result: %d\n", - toyvm_function_interpret (fn, atoi (argv[2]), NULL)); - - /* JIT-compilation. */ - toyvm_compiled_function *compiled_fn - = toyvm_function_compile (fn); - - toyvm_compiled_code code = compiled_fn->cf_code; - printf ("compiler result: %d\n", - code (atoi (argv[2]))); - - gcc_jit_result_release (compiled_fn->cf_jit_result); - free (compiled_fn); - - return 0; -@} - -@end example - -@noindent @end quotation We can now run the result: @@ -3102,10 +2749,7 @@ We can now run the result: gcc_jit_result_release (compiled_fn->cf_jit_result); free (compiled_fn); - @end example - -@noindent @end quotation @node Single-stepping through the generated code,Examining the generated code,Compiling the context,Tutorial part 4 Adding JIT-compilation to a toy interpreter @@ -3113,7 +2757,7 @@ We can now run the result: @subsection Single-stepping through the generated code -It's possible to debug the generated code. To do this we need to both: +It’s possible to debug the generated code. To do this we need to both: @quotation @@ -3123,14 +2767,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{41,,gcc_jit_context_new_location()} and using the +calling @ref{41,,gcc_jit_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 -@pxref{8,,gcc_jit_context} via -@pxref{1b,,gcc_jit_context_set_bool_option()}: +@ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the +@ref{8,,gcc_jit_context} via +@ref{1b,,gcc_jit_context_set_bool_option()}: @example gcc_jit_context_set_bool_option ( @@ -3138,8 +2782,6 @@ gcc_jit_context_set_bool_option ( GCC_JIT_BOOL_OPTION_DEBUGINFO, 1); @end example - -@noindent @end itemize @end quotation @@ -3156,9 +2798,7 @@ Breakpoint 1, factorial (arg=10) at factorial.toy:14 14 DUP @end example -@noindent - -We've set up location information, which references @code{factorial.toy}. +We’ve set up location information, which references @code{factorial.toy}. This allows us to use e.g. @code{list} to see where we are in the script: @example @@ -3175,8 +2815,6 @@ This allows us to use e.g. @code{list} to see where we are in the script: 18 PUSH_CONST 2 @end example -@noindent - and to step through the function, examining the data: @example @@ -3190,16 +2828,14 @@ $5 = @{10, 10, 2, 0, -7152, 32767, 0, 0@} $6 = 3 @end example -@noindent - -You'll see that the parts of the @code{stack} array that haven't been +You’ll see that the parts of the @code{stack} array that haven’t been touched yet are uninitialized. @cartouche @quotation Note Turning on optimizations may lead to unpredictable results when stepping through the generated code: the execution may appear to -"jump around" the source code. This is analogous to turning up the +“jump around” the source code. This is analogous to turning up the optimization level in a regular compiler. @end quotation @end cartouche @@ -3212,8 +2848,8 @@ optimization level in a regular compiler. How good is the optimized code? We can turn up optimizations, by calling -@pxref{1e,,gcc_jit_context_set_int_option()} with -@pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: +@ref{1e,,gcc_jit_context_set_int_option()} with +@ref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: @example gcc_jit_context_set_int_option ( @@ -3222,9 +2858,7 @@ gcc_jit_context_set_int_option ( 3); @end example -@noindent - -One of GCC's internal representations is called "gimple". A dump of the +One of GCC’s internal representations is called “gimple”. A dump of the initial gimple representation of the code can be seen by setting: @example @@ -3233,8 +2867,6 @@ gcc_jit_context_set_bool_option (ctxt, 1); @end example -@noindent - With optimization on and source locations displayed, this gives: @c We'll use "c" for gimple dumps @@ -3278,8 +2910,6 @@ factorial (signed int arg) /* etc */ @end example -@noindent - You can see the generated machine code in assembly form via: @example @@ -3290,8 +2920,6 @@ gcc_jit_context_set_bool_option ( result = gcc_jit_context_compile (ctxt); @end example -@noindent - which shows that (on this x86_64 box) the compiler has unrolled the loop and is using MMX instructions to perform several multiplications simultaneously: @@ -3341,8 +2969,6 @@ factorial: # etc - edited for brevity @end example -@noindent - This is clearly overkill for a function that will likely overflow the @code{int} type before the vectorization is worthwhile - but then again, this is a toy example. @@ -3356,8 +2982,6 @@ gcc_jit_context_set_int_option ( 3); @end example -@noindent - yields this code, which is simple enough to quote in its entirety: @example @@ -3399,8 +3023,6 @@ factorial: .section .note.GNU-stack,"",@@progbits @end example -@noindent - Note that the stack pushing and popping have been eliminated, as has the recursive call (in favor of an iteration). @@ -3435,8 +3057,6 @@ interpreter result: 55 compiler result: 55 @end example -@noindent - @node Behind the curtain How does our code get optimized?,,Putting it all together,Tutorial part 4 Adding JIT-compilation to a toy interpreter @anchor{intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{45} @subsection Behind the curtain: How does our code get optimized? @@ -3456,14 +3076,12 @@ gcc_jit_context_set_bool_option (state.ctxt, 1); @end example -@noindent - -This will dump detailed information about the compiler's state to a +This will dump detailed information about the compiler’s state to a directory under @code{/tmp}, and keep it from being cleaned up. The precise names and their formats of these files is subject to change. Higher optimization levels lead to more files. -Here's what I saw (edited for brevity; there were almost 200 files): +Here’s what I saw (edited for brevity; there were almost 200 files): @example intermediate files written to /tmp/libgccjit-KPQbGw @@ -3481,8 +3099,6 @@ fake.c.016t.ssa # etc @end example -@noindent - The gimple code is converted into Static Single Assignment form, with annotations for use when generating the debuginfo: @@ -3490,8 +3106,6 @@ with annotations for use when generating the debuginfo: $ less /tmp/libgccjit-KPQbGw/fake.c.016t.ssa @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -3533,18 +3147,14 @@ initial: /* etc; edited for brevity */ @end example -@noindent - We can perhaps better see the code by turning off -@pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG} +@ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG} statements, giving: @example $ less /tmp/libgccjit-1Hywc0/fake.c.016t.ssa @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -3630,10 +3240,8 @@ instr9: @} @end example -@noindent - -Note in the above how all the @pxref{28,,gcc_jit_block} instances we -created have been consolidated into just 3 blocks in GCC's internal +Note in the above how all the @ref{28,,gcc_jit_block} instances we +created have been consolidated into just 3 blocks in GCC’s internal representation: @code{initial}, @code{instr4} and @code{instr9}. @menu @@ -3647,7 +3255,7 @@ representation: @code{initial}, @code{instr4} and @code{instr9}. @subsubsection Optimizing away stack manipulation -Recall our simple implementation of stack operations. Let's examine +Recall our simple implementation of stack operations. Let’s examine how the stack operations are optimized away. After a pass of constant-propagation, the depth of the stack at each @@ -3657,8 +3265,6 @@ opcode can be determined at compile-time: $ less /tmp/libgccjit-1Hywc0/fake.c.021t.ccp1 @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -3719,20 +3325,16 @@ instr9: @} @end example -@noindent - Note how, in the above, all those @code{stack_depth} values are now just -constants: we're accessing specific stack locations at each opcode. +constants: we’re accessing specific stack locations at each opcode. -The "esra" pass ("Early Scalar Replacement of Aggregates") breaks -out our "stack" array into individual elements: +The “esra” pass (“Early Scalar Replacement of Aggregates”) breaks +out our “stack” array into individual elements: @example $ less /tmp/libgccjit-1Hywc0/fake.c.024t.esra @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -3808,8 +3410,6 @@ instr9: @} @end example -@noindent - Hence at this point, all those pushes and pops of the stack are now simply assignments to specific temporary variables. @@ -3820,8 +3420,6 @@ optimized away: $ less /tmp/libgccjit-1Hywc0/fake.c.026t.copyprop1 @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -3865,8 +3463,6 @@ instr9: @} @end example -@noindent - Later on, another pass finally eliminated @code{stack_depth} local and the unused parts of the @cite{stack`} array altogether: @@ -3874,8 +3470,6 @@ unused parts of the @cite{stack`} array altogether: $ less /tmp/libgccjit-1Hywc0/fake.c.036t.release_ssa @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -3920,8 +3514,6 @@ instr9: @} @end example -@noindent - @node Elimination of tail recursion,,Optimizing away stack manipulation,Behind the curtain How does our code get optimized? @anchor{intro/tutorial04 elimination-of-tail-recursion}@anchor{47} @subsubsection Elimination of tail recursion @@ -3935,8 +3527,6 @@ an iteration: $ less /tmp/libgccjit-1Hywc0/fake.c.030t.tailr1 @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -3990,8 +3580,6 @@ instr9: @} @end example -@noindent - @c Copyright (C) 2015-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @c @@ -4014,38 +3602,38 @@ instr9: @section Tutorial part 5: Implementing an Ahead-of-Time compiler -If you have a pre-existing language frontend that's compatible with -libgccjit's license, it's possible to hook it up to libgccjit as a +If you have a pre-existing language frontend that’s compatible with +libgccjit’s license, it’s possible to hook it up to libgccjit as a backend. In the previous example we showed how to do that for in-memory JIT-compilation, but libgccjit can also compile code directly to a file, allowing you to implement a more -traditional ahead-of-time compiler ("JIT" is something of a misnomer +traditional ahead-of-time compiler (“JIT” is something of a misnomer for this use-case). The essential difference is to compile the context using -@pxref{4a,,gcc_jit_context_compile_to_file()} rather than -@pxref{15,,gcc_jit_context_compile()}. +@ref{4a,,gcc_jit_context_compile_to_file()} rather than +@ref{15,,gcc_jit_context_compile()}. @menu -* The "brainf" language:: +* The “brainf” language:: * Converting a brainf script to libgccjit IR:: * Compiling a context to a file:: * Other forms of ahead-of-time-compilation:: @end menu -@node The "brainf" language,Converting a brainf script to libgccjit IR,,Tutorial part 5 Implementing an Ahead-of-Time compiler +@node The “brainf” language,Converting a brainf script to libgccjit IR,,Tutorial part 5 Implementing an Ahead-of-Time compiler @anchor{intro/tutorial05 the-brainf-language}@anchor{4b} -@subsection The "brainf" language +@subsection The “brainf” language In this example we use libgccjit to construct an ahead-of-time compiler -for an esoteric programming language that we shall refer to as "brainf". +for an esoteric programming language that we shall refer to as “brainf”. brainf scripts operate on an array of bytes, with a notional data pointer within the array. -brainf is hard for humans to read, but it's trivial to write a parser for +brainf is hard for humans to read, but it’s trivial to write a parser for it, as there is no lexing; just a stream of bytes. The operations are: @@ -4133,11 +3721,11 @@ ignored @end multitable -Unlike the previous example, we'll implement an ahead-of-time compiler, +Unlike the previous example, we’ll implement an ahead-of-time compiler, which reads @code{.bf} scripts and outputs executables (though it would be trivial to have it run them JIT-compiled in-process). -Here's what a simple @code{.bf} script looks like: +Here’s what a simple @code{.bf} script looks like: @quotation @@ -4159,10 +3747,7 @@ while cell#0 != 0 + increment cell@@1 <- decrement cell@@0 ] - @end example - -@noindent @end quotation @cartouche @@ -4176,23 +3761,21 @@ could have been written as: [>.+<-] @end example -@noindent - -It's not a particularly useful language, except for providing -compiler-writers with a test case that's easy to parse. The point -is that you can use @pxref{4a,,gcc_jit_context_compile_to_file()} +It’s not a particularly useful language, except for providing +compiler-writers with a test case that’s easy to parse. The point +is that you can use @ref{4a,,gcc_jit_context_compile_to_file()} to use libgccjit as a backend for a pre-existing language frontend -(provided that the pre-existing frontend is compatible with libgccjit's +(provided that the pre-existing frontend is compatible with libgccjit’s license). @end quotation @end cartouche -@node Converting a brainf script to libgccjit IR,Compiling a context to a file,The "brainf" language,Tutorial part 5 Implementing an Ahead-of-Time compiler +@node Converting a brainf script to libgccjit IR,Compiling a context to a file,The “brainf” language,Tutorial part 5 Implementing an Ahead-of-Time compiler @anchor{intro/tutorial05 converting-a-brainf-script-to-libgccjit-ir}@anchor{4c} @subsection Converting a brainf script to libgccjit IR -As before we write simple code to populate a @pxref{8,,gcc_jit_context *}. +As before we write simple code to populate a @ref{8,,gcc_jit_context *}. @quotation @@ -4560,10 +4143,7 @@ bf_compile (const char *filename) return bfc.ctxt; @} - @end example - -@noindent @end quotation @node Compiling a context to a file,Other forms of ahead-of-time-compilation,Converting a brainf script to libgccjit IR,Tutorial part 5 Implementing an Ahead-of-Time compiler @@ -4571,8 +4151,8 @@ bf_compile (const char *filename) @subsection Compiling a context to a file -Unlike the previous tutorial, this time we'll compile the context -directly to an executable, using @pxref{4a,,gcc_jit_context_compile_to_file()}: +Unlike the previous tutorial, this time we’ll compile the context +directly to an executable, using @ref{4a,,gcc_jit_context_compile_to_file()}: @example gcc_jit_context_compile_to_file (ctxt, @@ -4580,10 +4160,8 @@ gcc_jit_context_compile_to_file (ctxt, output_file); @end example -@noindent - -Here's the top-level of the compiler, which is what actually calls into -@pxref{4a,,gcc_jit_context_compile_to_file()}: +Here’s the top-level of the compiler, which is what actually calls into +@ref{4a,,gcc_jit_context_compile_to_file()}: @quotation @@ -4623,17 +4201,14 @@ main (int argc, char **argv) return 0; @} - @end example - -@noindent @end quotation Note how once the context is populated you could trivially instead compile -it to memory using @pxref{15,,gcc_jit_context_compile()} and run it in-process +it to memory using @ref{15,,gcc_jit_context_compile()} and run it in-process as in the previous tutorial. -To create an executable, we need to export a @code{main} function. Here's +To create an executable, we need to export a @code{main} function. Here’s how to create one from the JIT API: @quotation @@ -4671,10 +4246,7 @@ make_main (gcc_jit_context *ctxt) return func_main; @} - @end example - -@noindent @end quotation @cartouche @@ -4686,7 +4258,7 @@ caller. @end cartouche Upon compiling this C code, we obtain a bf-to-machine-code compiler; -let's call it @code{bfc}: +let’s call it @code{bfc}: @example $ gcc \ @@ -4695,8 +4267,6 @@ $ gcc \ -lgccjit @end example -@noindent - We can now use @code{bfc} to compile .bf files into machine code executables: @example @@ -4705,8 +4275,6 @@ $ ./bfc \ a.out @end example -@noindent - which we can run directly: @example @@ -4714,8 +4282,6 @@ $ ./a.out ABCDEFGHIJKLMNOPQRSTUVWXYZ @end example -@noindent - Success! We can also inspect the generated executable using standard tools: @@ -4724,8 +4290,6 @@ We can also inspect the generated executable using standard tools: $ objdump -d a.out |less @end example -@noindent - which shows that libgccjit has managed to optimize the function somewhat (for example, the runs of 26 and 65 increment operations have become integer constants 0x1a and 0x41): @@ -4755,11 +4319,9 @@ have become integer constants 0x1a and 0x41): 40067a: 66 0f 1f 44 00 00 nopw 0x0(%rax,%rax,1) @end example -@noindent - We also set up debugging information (via -@pxref{41,,gcc_jit_context_new_location()} and -@pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO}), so it's possible to use @code{gdb} +@ref{41,,gcc_jit_context_new_location()} and +@ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO}), so it’s possible to use @code{gdb} to singlestep through the generated binary and inspect the internal state @code{idx} and @code{data_cells}: @@ -4812,17 +4374,15 @@ $4 = 0 '\000' 13 > @end example -@noindent - @node Other forms of ahead-of-time-compilation,,Compiling a context to a file,Tutorial part 5 Implementing an Ahead-of-Time compiler @anchor{intro/tutorial05 other-forms-of-ahead-of-time-compilation}@anchor{4e} @subsection Other forms of ahead-of-time-compilation -The above demonstrates compiling a @pxref{8,,gcc_jit_context *} directly -to an executable. It's also possible to compile it to an object file, +The above demonstrates compiling a @ref{8,,gcc_jit_context *} directly +to an executable. It’s also possible to compile it to an object file, and to a dynamic library. See the documentation of -@pxref{4a,,gcc_jit_context_compile_to_file()} for more information. +@ref{4a,,gcc_jit_context_compile_to_file()} for more information. @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @@ -4875,109 +4435,26 @@ and to a dynamic library. See the documentation of * ABI and API compatibility:: * Performance:: -Compilation contexts - -* Lifetime-management:: -* Thread-safety:: -* Error-handling: Error-handling<2>. -* Debugging:: -* Options: Options<2>. - -Options - -* String Options:: -* Boolean options:: -* Integer options:: -* Additional command-line options:: - -Types - -* Standard types:: -* Pointers@comma{} const@comma{} and volatile: Pointers const and volatile. -* Vector types:: -* Structures and unions:: -* Function pointer types:: - -Expressions - -* Rvalues:: -* Lvalues:: -* Working with pointers@comma{} structs and unions: Working with pointers structs and unions. - -Rvalues - -* Simple expressions:: -* Vector expressions:: -* Unary Operations:: -* Binary Operations:: -* Comparisons:: -* Function calls:: -* Function pointers:: -* Type-coercion:: - -Lvalues - -* Global variables:: - -Creating and using functions - -* Params:: -* Functions:: -* Blocks:: -* Statements:: - -Source Locations - -* Faking it:: - -Compiling a context - -* In-memory compilation:: -* Ahead-of-time compilation:: - -ABI and API compatibility - -* ABI symbol tags:: - -ABI symbol tags - -* LIBGCCJIT_ABI_0:: -* LIBGCCJIT_ABI_1:: -* LIBGCCJIT_ABI_2:: -* LIBGCCJIT_ABI_3:: -* LIBGCCJIT_ABI_4:: -* LIBGCCJIT_ABI_5:: -* LIBGCCJIT_ABI_6:: -* LIBGCCJIT_ABI_7:: -* LIBGCCJIT_ABI_8:: -* LIBGCCJIT_ABI_9:: -* LIBGCCJIT_ABI_10:: - -Performance - -* The timing API:: - @end menu - @node Compilation contexts,Objects,,Topic Reference -@anchor{topics/contexts compilation-contexts}@anchor{51}@anchor{topics/contexts doc}@anchor{52} +@anchor{topics/contexts doc}@anchor{51}@anchor{topics/contexts compilation-contexts}@anchor{52} @section Compilation contexts @geindex gcc_jit_context (C type) -@anchor{topics/contexts gcc_jit_context}@anchor{8} +@anchor{topics/contexts c gcc_jit_context}@anchor{8} @deffn {C Type} gcc_jit_context @end deffn -The top-level of the API is the @pxref{8,,gcc_jit_context} type. +The top-level of the API is the @ref{8,,gcc_jit_context} type. -A @pxref{8,,gcc_jit_context} instance encapsulates the state of a +A @ref{8,,gcc_jit_context} instance encapsulates the state of a compilation. You can set up options on it, and add types, functions and code. -Invoking @pxref{15,,gcc_jit_context_compile()} on it gives you a -@pxref{16,,gcc_jit_result}. +Invoking @ref{15,,gcc_jit_context_compile()} on it gives you a +@ref{16,,gcc_jit_result}. @menu * Lifetime-management:: @@ -4998,35 +4475,33 @@ 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 gcc_jit_context_acquire (C function) -@anchor{topics/contexts gcc_jit_context_acquire}@anchor{9} +@anchor{topics/contexts c gcc_jit_context_acquire}@anchor{9} @deffn {C Function} gcc_jit_context *gcc_jit_context_acquire (void) -This function acquires a new @pxref{8,,gcc_jit_context *} instance, +This function acquires a new @ref{8,,gcc_jit_context *} instance, which is independent of any others that may be present within this process. @end deffn @geindex gcc_jit_context_release (C function) -@anchor{topics/contexts gcc_jit_context_release}@anchor{c} +@anchor{topics/contexts c gcc_jit_context_release}@anchor{c} @deffn {C Function} void gcc_jit_context_release (gcc_jit_context@w{ }*ctxt) This function releases all resources associated with the given context. -Both the context itself and all of its @pxref{e,,gcc_jit_object *} +Both the context itself and all of its @ref{e,,gcc_jit_object *} instances are cleaned up. It should be called exactly once on a given context. -It is invalid to use the context or any of its "contextual" objects +It is invalid to use the context or any of its “contextual” objects after calling this. @example gcc_jit_context_release (ctxt); @end example - -@noindent @end deffn @geindex gcc_jit_context_new_child_context (C function) -@anchor{topics/contexts gcc_jit_context_new_child_context}@anchor{54} +@anchor{topics/contexts c gcc_jit_context_new_child_context}@anchor{54} @deffn {C Function} gcc_jit_context * gcc_jit_context_new_child_context (gcc_jit_context@w{ }*parent_ctxt) Given an existing JIT context, create a child context. @@ -5053,7 +4528,7 @@ JIT-compiling just one function or loop, but can reference types and helper functions created within the parent context. Contexts can be arbitrarily nested, provided the above rules are -followed, but it's probably not worth going above 2 or 3 levels, and +followed, but it’s probably not worth going above 2 or 3 levels, and there will likely be a performance hit for such nesting. @end deffn @@ -5062,16 +4537,16 @@ there will likely be a performance hit for such nesting. @subsection Thread-safety -Instances of @pxref{8,,gcc_jit_context *} created via -@pxref{9,,gcc_jit_context_acquire()} are independent from each other: +Instances of @ref{8,,gcc_jit_context *} created via +@ref{9,,gcc_jit_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{54,,gcc_jit_context_new_child_context()} are +Contexts created via @ref{54,,gcc_jit_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, -and if you're using multiple threads you should provide your own locking +ultimate ancestor into independent “family trees”. Only one thread +within a process may use a given “family tree” of such contexts at once, +and if you’re using multiple threads you should provide your own locking around entire such context partitions. @node Error-handling<2>,Debugging,Thread-safety,Compilation contexts @@ -5084,7 +4559,7 @@ mismatched types in an assignment. You can only compile and get code from a context if no errors occur. Errors are printed on stderr and can be queried using -@pxref{57,,gcc_jit_context_get_first_error()}. +@ref{57,,gcc_jit_context_get_first_error()}. They typically contain the name of the API entrypoint where the error occurred, and pertinent information on the problem: @@ -5093,10 +4568,8 @@ occurred, and pertinent information on the problem: ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *) @end example -@noindent - In general, if an error occurs when using an API entrypoint, the -entrypoint returns NULL. You don't have to check everywhere for NULL +entrypoint returns NULL. You don’t have to check everywhere for NULL results, since the API handles a NULL being passed in for any argument by issuing another error. This typically leads to a cascade of followup error messages, but is safe (albeit verbose). The first error @@ -5104,7 +4577,7 @@ message is usually the one to pay attention to, since it is likely to be responsible for all of the rest: @geindex gcc_jit_context_get_first_error (C function) -@anchor{topics/contexts gcc_jit_context_get_first_error}@anchor{57} +@anchor{topics/contexts c gcc_jit_context_get_first_error}@anchor{57} @deffn {C Function} const char * gcc_jit_context_get_first_error (gcc_jit_context@w{ }*ctxt) Returns the first error message that occurred on the context. @@ -5120,7 +4593,7 @@ exception-handling, you may instead be interested in the last error that occurred on the context, so that you can embed this in an exception: @geindex gcc_jit_context_get_last_error (C function) -@anchor{topics/contexts gcc_jit_context_get_last_error}@anchor{58} +@anchor{topics/contexts c gcc_jit_context_get_last_error}@anchor{58} @deffn {C Function} const char * gcc_jit_context_get_last_error (gcc_jit_context@w{ }*ctxt) Returns the last error message that occurred on the context. @@ -5137,24 +4610,24 @@ the next call to libgccjit relating to this context. @geindex gcc_jit_context_dump_to_file (C function) -@anchor{topics/contexts gcc_jit_context_dump_to_file}@anchor{5a} +@anchor{topics/contexts c gcc_jit_context_dump_to_file}@anchor{5a} @deffn {C Function} void gcc_jit_context_dump_to_file (gcc_jit_context@w{ }*ctxt, const char@w{ }*path, int@w{ }update_locations) To help with debugging: dump a C-like representation to the given path, -describing what's been set up on the context. +describing what’s been set up on the context. -If "update_locations" is true, then also set up @pxref{3b,,gcc_jit_location} +If “update_locations” is true, then also set up @ref{3b,,gcc_jit_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 -@pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to allow stepping through the +@ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to allow stepping through the code in a debugger. @end deffn @geindex gcc_jit_context_set_logfile (C function) -@anchor{topics/contexts gcc_jit_context_set_logfile}@anchor{5b} +@anchor{topics/contexts c gcc_jit_context_set_logfile}@anchor{5b} @deffn {C Function} void gcc_jit_context_set_logfile (gcc_jit_context@w{ }*ctxt, FILE@w{ }*logfile, int@w{ }flags, int@w{ }verbosity) -To help with debugging; enable ongoing logging of the context's +To help with debugging; enable ongoing logging of the context’s activity to the given file. For example, the following will enable logging to stderr. @@ -5163,8 +4636,6 @@ For example, the following will enable logging to stderr. gcc_jit_context_set_logfile (ctxt, stderr, 0, 0); @end example -@noindent - Examples of information logged include: @@ -5177,40 +4648,40 @@ API calls the various steps involved within compilation @item -activity on any @pxref{16,,gcc_jit_result} instances created by +activity on any @ref{16,,gcc_jit_result} instances created by the context @item activity within any child contexts @end itemize -An example of a log can be seen @pxref{5c,,here}, +An example of a log can be seen @ref{5c,,here}, though the precise format and kinds of information logged is subject to change. The caller remains responsible for closing @cite{logfile}, and it must not be closed until all users are released. In particular, note that -child contexts and @pxref{16,,gcc_jit_result} instances created by +child contexts and @ref{16,,gcc_jit_result} instances created by the context will use the logfile. There may a performance cost for logging. You can turn off logging on @cite{ctxt} by passing @cite{NULL} for @cite{logfile}. Doing so only affects the context; it does not affect child contexts -or @pxref{16,,gcc_jit_result} instances already created by +or @ref{16,,gcc_jit_result} instances already created by the context. -The parameters "flags" and "verbosity" are reserved for future +The parameters “flags” and “verbosity” are reserved for future expansion, and must be zero for now. @end deffn -To contrast the above: @pxref{5a,,gcc_jit_context_dump_to_file()} dumps the +To contrast the above: @ref{5a,,gcc_jit_context_dump_to_file()} dumps the current state of a context to the given path, whereas -@pxref{5b,,gcc_jit_context_set_logfile()} enables on-going logging of +@ref{5b,,gcc_jit_context_set_logfile()} enables on-going logging of future activies on a context to the given @cite{FILE *}. @geindex gcc_jit_context_dump_reproducer_to_file (C function) -@anchor{topics/contexts gcc_jit_context_dump_reproducer_to_file}@anchor{5d} +@anchor{topics/contexts c gcc_jit_context_dump_reproducer_to_file}@anchor{5d} @deffn {C Function} void gcc_jit_context_dump_reproducer_to_file (gcc_jit_context@w{ }*ctxt, const char@w{ }*path) Write C source code into @cite{path} that can be compiled into a @@ -5234,14 +4705,14 @@ all are necessarily then used). @end deffn @geindex gcc_jit_context_enable_dump (C function) -@anchor{topics/contexts gcc_jit_context_enable_dump}@anchor{5e} +@anchor{topics/contexts c gcc_jit_context_enable_dump}@anchor{5e} @deffn {C Function} void gcc_jit_context_enable_dump (gcc_jit_context@w{ }*ctxt, const char@w{ }*dumpname, char@w{ }**out_ptr) Enable the dumping of a specific set of internal state from the compilation, capturing the result in-memory as a buffer. -Parameter "dumpname" corresponds to the equivalent gcc command-line -option, without the "-fdump-" prefix. +Parameter “dumpname” corresponds to the equivalent gcc command-line +option, without the “-fdump-” prefix. For example, to get the equivalent of @code{-fdump-tree-vrp1}, supply @code{"tree-vrp1"}: @@ -5256,12 +4727,10 @@ create_code (gcc_jit_context *ctxt) @} @end example -@noindent - The context directly stores the dumpname as a @code{(const char *)}, so the passed string must outlive the context. -@pxref{15,,gcc_jit_context_compile()} will capture the dump as a +@ref{15,,gcc_jit_context_compile()} will capture the dump as a dynamically-allocated buffer, writing it to @code{*out_ptr}. The caller becomes responsible for calling: @@ -5270,9 +4739,7 @@ The caller becomes responsible for calling: free (*out_ptr) @end example -@noindent - -each time that @pxref{15,,gcc_jit_context_compile()} is called. +each time that @ref{15,,gcc_jit_context_compile()} is called. @code{*out_ptr} will be written to, either with the address of a buffer, or with @code{NULL} if an error occurred. @@ -5282,7 +4749,7 @@ This API entrypoint is likely to be less stable than the others. In particular, both the precise dumpnames, and the format and content of the dumps are subject to change. -It exists primarily for writing the library's own test suite. +It exists primarily for writing the library’s own test suite. @end quotation @end cartouche @end deffn @@ -5315,13 +4782,13 @@ would not be possible if we instead extended the various @geindex gcc_jit_context_set_str_option (C function) -@anchor{topics/contexts gcc_jit_context_set_str_option}@anchor{61} +@anchor{topics/contexts c gcc_jit_context_set_str_option}@anchor{61} @deffn {C Function} void gcc_jit_context_set_str_option (gcc_jit_context@w{ }*ctxt, enum gcc_jit_str_option@w{ }opt, const char@w{ }*value) Set a string option of the context. @geindex gcc_jit_str_option (C type) -@anchor{topics/contexts gcc_jit_str_option}@anchor{62} +@anchor{topics/contexts c gcc_jit_str_option}@anchor{62} @deffn {C Type} enum gcc_jit_str_option @end deffn @@ -5332,11 +4799,11 @@ an on-stack buffer. There is just one string option specified this way: @geindex GCC_JIT_STR_OPTION_PROGNAME (C macro) -@anchor{topics/contexts GCC_JIT_STR_OPTION_PROGNAME}@anchor{63} +@anchor{topics/contexts c GCC_JIT_STR_OPTION_PROGNAME}@anchor{63} @deffn {C Macro} GCC_JIT_STR_OPTION_PROGNAME The name of the program, for use as a prefix when printing error -messages to stderr. If @cite{NULL}, or default, "libgccjit.so" is used. +messages to stderr. If @cite{NULL}, or default, “libgccjit.so” is used. @end deffn @end deffn @@ -5346,39 +4813,39 @@ messages to stderr. If @cite{NULL}, or default, "libgccjit.so" is used. @geindex gcc_jit_context_set_bool_option (C function) -@anchor{topics/contexts gcc_jit_context_set_bool_option}@anchor{1b} +@anchor{topics/contexts c gcc_jit_context_set_bool_option}@anchor{1b} @deffn {C Function} void gcc_jit_context_set_bool_option (gcc_jit_context@w{ }*ctxt, enum gcc_jit_bool_option@w{ }opt, int@w{ }value) Set a boolean option of the context. -Zero is "false" (the default), non-zero is "true". +Zero is “false” (the default), non-zero is “true”. @geindex gcc_jit_bool_option (C type) -@anchor{topics/contexts gcc_jit_bool_option}@anchor{65} +@anchor{topics/contexts c gcc_jit_bool_option}@anchor{65} @deffn {C Type} enum gcc_jit_bool_option @end deffn @geindex GCC_JIT_BOOL_OPTION_DEBUGINFO (C macro) -@anchor{topics/contexts GCC_JIT_BOOL_OPTION_DEBUGINFO}@anchor{42} +@anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DEBUGINFO}@anchor{42} @deffn {C Macro} GCC_JIT_BOOL_OPTION_DEBUGINFO -If true, @pxref{15,,gcc_jit_context_compile()} will attempt to do the right +If true, @ref{15,,gcc_jit_context_compile()} will attempt to do the right thing so that if you attach a debugger to the process, it will be able to inspect variables and step through your code. -Note that you can't step through code unless you set up source +Note that you can’t step through code unless you set up source location information for the code (by creating and passing in -@pxref{3b,,gcc_jit_location} instances). +@ref{3b,,gcc_jit_location} instances). @end deffn @geindex GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE (C macro) -@anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}@anchor{66} +@anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE}@anchor{66} @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE -If true, @pxref{15,,gcc_jit_context_compile()} will dump its initial -"tree" representation of your code to stderr (before any +If true, @ref{15,,gcc_jit_context_compile()} will dump its initial +“tree” representation of your code to stderr (before any optimizations). -Here's some sample output (from the @cite{square} example): +Here’s some sample output (from the @cite{square} example): @example <statement_list 0x7f4875a62cc0 @@ -5404,15 +4871,13 @@ Here's some sample output (from the @cite{square} example): arg 1 <mult_expr 0x7f4875a72a50 type <integer_type 0x7f4875a645e8> arg 0 <parm_decl 0x7f4875a79000 i> arg 1 <parm_decl 0x7f4875a79000 i>>>>> @end example - -@noindent @end deffn @geindex GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE (C macro) -@anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE}@anchor{1c} +@anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE}@anchor{1c} @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE -If true, @pxref{15,,gcc_jit_context_compile()} will dump the "gimple" +If true, @ref{15,,gcc_jit_context_compile()} will dump the “gimple” representation of your code to stderr, before any optimizations are performed. The dump resembles C code: @@ -5426,15 +4891,13 @@ square (signed int i) return D.56; @} @end example - -@noindent @end deffn @geindex GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE (C macro) -@anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE}@anchor{1d} +@anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE}@anchor{1d} @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE -If true, @pxref{15,,gcc_jit_context_compile()} will dump the final +If true, @ref{15,,gcc_jit_context_compile()} will dump the final generated code to stderr, in the form of assembly language: @example @@ -5463,32 +4926,30 @@ square: .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.1-%@{gcc_release@})" .section .note.GNU-stack,"",@@progbits @end example - -@noindent @end deffn @geindex GCC_JIT_BOOL_OPTION_DUMP_SUMMARY (C macro) -@anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_SUMMARY}@anchor{67} +@anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_SUMMARY}@anchor{67} @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_SUMMARY -If true, @pxref{15,,gcc_jit_context_compile()} will print information to stderr +If true, @ref{15,,gcc_jit_context_compile()} will print information to stderr on the actions it is performing. @end deffn @geindex GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING (C macro) -@anchor{topics/contexts GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING}@anchor{68} +@anchor{topics/contexts c GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING}@anchor{68} @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING -If true, @pxref{15,,gcc_jit_context_compile()} will dump copious -amount of information on what it's doing to various +If true, @ref{15,,gcc_jit_context_compile()} will dump copious +amount of information on what it’s doing to various files within a temporary directory. Use -@pxref{69,,GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES} (see below) to +@ref{69,,GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES} (see below) to see the results. The files are intended to be human-readable, but the exact files and their formats are subject to change. @end deffn @geindex GCC_JIT_BOOL_OPTION_SELFCHECK_GC (C macro) -@anchor{topics/contexts GCC_JIT_BOOL_OPTION_SELFCHECK_GC}@anchor{6a} +@anchor{topics/contexts c GCC_JIT_BOOL_OPTION_SELFCHECK_GC}@anchor{6a} @deffn {C Macro} GCC_JIT_BOOL_OPTION_SELFCHECK_GC If true, libgccjit will aggressively run its garbage collector, to @@ -5498,16 +4959,16 @@ used when running the selftest suite. @end deffn @geindex GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES (C macro) -@anchor{topics/contexts GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES}@anchor{69} +@anchor{topics/contexts c GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES}@anchor{69} @deffn {C Macro} GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES -If true, the @pxref{8,,gcc_jit_context} will not clean up intermediate files +If true, the @ref{8,,gcc_jit_context} will not clean up intermediate files written to the filesystem, and will display their location on stderr. @end deffn @end deffn @geindex gcc_jit_context_set_bool_allow_unreachable_blocks (C function) -@anchor{topics/contexts gcc_jit_context_set_bool_allow_unreachable_blocks}@anchor{6b} +@anchor{topics/contexts c gcc_jit_context_set_bool_allow_unreachable_blocks}@anchor{6b} @deffn {C Function} void gcc_jit_context_set_bool_allow_unreachable_blocks (gcc_jit_context@w{ }*ctxt, int@w{ }bool_value) By default, libgccjit will issue an error about unreachable blocks @@ -5515,21 +4976,19 @@ within a function. This entrypoint can be used to disable that error. -This entrypoint was added in @pxref{6c,,LIBGCCJIT_ABI_2}; you can test for +This entrypoint was added in @ref{6c,,LIBGCCJIT_ABI_2}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks @end example - -@noindent @end deffn @geindex gcc_jit_context_set_bool_use_external_driver (C function) -@anchor{topics/contexts gcc_jit_context_set_bool_use_external_driver}@anchor{6d} +@anchor{topics/contexts c gcc_jit_context_set_bool_use_external_driver}@anchor{6d} @deffn {C Function} void gcc_jit_context_set_bool_use_external_driver (gcc_jit_context@w{ }*ctxt, int@w{ }bool_value) -libgccjit internally generates assembler, and uses "driver" code +libgccjit internally generates assembler, and uses “driver” code for converting it to other formats (e.g. shared libraries). By default, libgccjit will use an embedded copy of the driver @@ -5538,14 +4997,12 @@ code. This option can be used to instead invoke an external driver executable as a subprocess. -This entrypoint was added in @pxref{6e,,LIBGCCJIT_ABI_5}; you can test for +This entrypoint was added in @ref{6e,,LIBGCCJIT_ABI_5}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver @end example - -@noindent @end deffn @node Integer options,Additional command-line options,Boolean options,Options<2> @@ -5554,25 +5011,25 @@ its presence using @geindex gcc_jit_context_set_int_option (C function) -@anchor{topics/contexts gcc_jit_context_set_int_option}@anchor{1e} +@anchor{topics/contexts c gcc_jit_context_set_int_option}@anchor{1e} @deffn {C Function} void gcc_jit_context_set_int_option (gcc_jit_context@w{ }*ctxt, enum gcc_jit_int_option@w{ }opt, int@w{ }value) Set an integer option of the context. @geindex gcc_jit_int_option (C type) -@anchor{topics/contexts gcc_jit_int_option}@anchor{70} +@anchor{topics/contexts c gcc_jit_int_option}@anchor{70} @deffn {C Type} enum gcc_jit_int_option @end deffn There is just one integer option specified this way: @geindex GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL (C macro) -@anchor{topics/contexts GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}@anchor{1f} +@anchor{topics/contexts c GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}@anchor{1f} @deffn {C Macro} GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL How much to optimize the code. -Valid values are 0-3, corresponding to GCC's command-line options +Valid values are 0-3, corresponding to GCC’s command-line options -O0 through -O3. The default value is 0 (unoptimized). @@ -5585,12 +5042,12 @@ The default value is 0 (unoptimized). @geindex gcc_jit_context_add_command_line_option (C function) -@anchor{topics/contexts gcc_jit_context_add_command_line_option}@anchor{72} +@anchor{topics/contexts c gcc_jit_context_add_command_line_option}@anchor{72} @deffn {C Function} void gcc_jit_context_add_command_line_option (gcc_jit_context@w{ }*ctxt, const char@w{ }*optname) Add an arbitrary gcc command-line option to the context, for use -by @pxref{15,,gcc_jit_context_compile()} and -@pxref{4a,,gcc_jit_context_compile_to_file()}. +by @ref{15,,gcc_jit_context_compile()} and +@ref{4a,,gcc_jit_context_compile_to_file()}. The parameter @code{optname} must be non-NULL. The underlying buffer is copied, so that it does not need to outlive the call. @@ -5607,20 +5064,51 @@ gcc_jit_context_add_command_line_option (ctxt, "-ffast-math"); gcc_jit_context_add_command_line_option (ctxt, "-fverbose-asm"); @end example -@noindent - Note that only some options are likely to be meaningful; there is no -"frontend" within libgccjit, so typically only those affecting +“frontend” within libgccjit, so typically only those affecting optimization and code-generation are likely to be useful. -This entrypoint was added in @pxref{73,,LIBGCCJIT_ABI_1}; you can test for +This entrypoint was added in @ref{73,,LIBGCCJIT_ABI_1}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option @end example +@end deffn + +@geindex gcc_jit_context_add_driver_option (C function) +@anchor{topics/contexts c gcc_jit_context_add_driver_option}@anchor{74} +@deffn {C Function} void gcc_jit_context_add_driver_option (gcc_jit_context@w{ }*ctxt, const char@w{ }*optname) + +Add an arbitrary gcc driver option to the context, for use by +@ref{15,,gcc_jit_context_compile()} and +@ref{4a,,gcc_jit_context_compile_to_file()}. + +The parameter @code{optname} must be non-NULL. The underlying buffer is +copied, so that it does not need to outlive the call. + +Extra options added by @cite{gcc_jit_context_add_driver_option} are +applied @emph{after} all other options potentially overriding them. +Options from parent contexts are inherited by child contexts; options +from the parent are applied @emph{before} those from the child. + +For example: + +@example +gcc_jit_context_add_driver_option (ctxt, "-lm"); +gcc_jit_context_add_driver_option (ctxt, "-fuse-linker-plugin"); +@end example -@noindent +Note that only some options are likely to be meaningful; there is no +“frontend” within libgccjit, so typically only those affecting +assembler and linker are likely to be useful. + +This entrypoint was added in @ref{75,,LIBGCCJIT_ABI_11}; you can test for +its presence using + +@example +#ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option +@end example @end deffn @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @@ -5641,18 +5129,18 @@ its presence using @c <http://www.gnu.org/licenses/>. @node Objects,Types,Compilation contexts,Topic Reference -@anchor{topics/objects objects}@anchor{74}@anchor{topics/objects doc}@anchor{75} +@anchor{topics/objects doc}@anchor{76}@anchor{topics/objects objects}@anchor{77} @section Objects @geindex gcc_jit_object (C type) -@anchor{topics/objects gcc_jit_object}@anchor{e} +@anchor{topics/objects c gcc_jit_object}@anchor{e} @deffn {C Type} gcc_jit_object @end deffn Almost every entity in the API (with the exception of -@pxref{8,,gcc_jit_context *} and @pxref{16,,gcc_jit_result *}) is a -"contextual" object, a @pxref{e,,gcc_jit_object *} +@ref{8,,gcc_jit_context *} and @ref{16,,gcc_jit_result *}) is a +“contextual” object, a @ref{e,,gcc_jit_object *} A JIT object: @@ -5662,11 +5150,11 @@ A JIT object: @itemize * @item -is associated with a @pxref{8,,gcc_jit_context *}. +is associated with a @ref{8,,gcc_jit_context *}. @item is automatically cleaned up for you when its context is released so -you don't need to manually track and cleanup all objects, just the +you don’t need to manually track and cleanup all objects, just the contexts. @end itemize @end quotation @@ -5688,28 +5176,24 @@ looks like this: +- gcc_jit_case @end example -@noindent - There are casting methods for upcasting from subclasses to parent classes. -For example, @pxref{d,,gcc_jit_type_as_object()}: +For example, @ref{d,,gcc_jit_type_as_object()}: @example gcc_jit_object *obj = gcc_jit_type_as_object (int_type); @end example -@noindent - -The object "base class" has the following operations: +The object “base class” has the following operations: @geindex gcc_jit_object_get_context (C function) -@anchor{topics/objects gcc_jit_object_get_context}@anchor{76} +@anchor{topics/objects c gcc_jit_object_get_context}@anchor{78} @deffn {C Function} gcc_jit_context *gcc_jit_object_get_context (gcc_jit_object@w{ }*obj) -Which context is "obj" within? +Which context is “obj” within? @end deffn @geindex gcc_jit_object_get_debug_string (C function) -@anchor{topics/objects gcc_jit_object_get_debug_string}@anchor{f} +@anchor{topics/objects c gcc_jit_object_get_debug_string}@anchor{f} @deffn {C Function} const char *gcc_jit_object_get_debug_string (gcc_jit_object@w{ }*obj) Generate a human-readable description for the given object. @@ -5720,22 +5204,18 @@ For example, printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj)); @end example -@noindent - might give this text on stdout: @example obj: 4.0 * (float)i @end example -@noindent - @cartouche @quotation Note If you call this on an object, the @cite{const char *} buffer is allocated and generated on the first call for that object, and the buffer will have the same lifetime as the object i.e. it will exist until the -object's context is released. +object’s context is released. @end quotation @end cartouche @end deffn @@ -5758,19 +5238,19 @@ object's context is released. @c <http://www.gnu.org/licenses/>. @node Types,Expressions,Objects,Topic Reference -@anchor{topics/types doc}@anchor{77}@anchor{topics/types types}@anchor{78} +@anchor{topics/types doc}@anchor{79}@anchor{topics/types types}@anchor{7a} @section Types @geindex gcc_jit_type (C type) -@anchor{topics/types gcc_jit_type}@anchor{a} +@anchor{topics/types c gcc_jit_type}@anchor{a} @deffn {C Type} gcc_jit_type gcc_jit_type represents a type within the library. @end deffn @geindex gcc_jit_type_as_object (C function) -@anchor{topics/types gcc_jit_type_as_object}@anchor{d} +@anchor{topics/types c gcc_jit_type_as_object}@anchor{d} @deffn {C Function} gcc_jit_object *gcc_jit_type_as_object (gcc_jit_type@w{ }*type) Upcast a type to an object. @@ -5783,27 +5263,23 @@ Types can be created in several ways: @item fundamental types can be accessed using -@pxref{b,,gcc_jit_context_get_type()}: +@ref{b,,gcc_jit_context_get_type()}: @example gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, GCC_JIT_TYPE_INT); @end example -@noindent - -See @pxref{b,,gcc_jit_context_get_type()} for the available types. +See @ref{b,,gcc_jit_context_get_type()} for the available types. @item derived types can be accessed by using functions such as -@pxref{79,,gcc_jit_type_get_pointer()} and @pxref{7a,,gcc_jit_type_get_const()}: +@ref{7b,,gcc_jit_type_get_pointer()} and @ref{7c,,gcc_jit_type_get_const()}: @example gcc_jit_type *const_int_star = gcc_jit_type_get_pointer (gcc_jit_type_get_const (int_type)); gcc_jit_type *int_const_star = gcc_jit_type_get_const (gcc_jit_type_get_pointer (int_type)); @end example -@noindent - @item by creating structures (see below). @end itemize @@ -5818,12 +5294,12 @@ by creating structures (see below). @end menu @node Standard types,Pointers const and volatile,,Types -@anchor{topics/types standard-types}@anchor{7b} +@anchor{topics/types standard-types}@anchor{7d} @subsection Standard types @geindex gcc_jit_context_get_type (C function) -@anchor{topics/types gcc_jit_context_get_type}@anchor{b} +@anchor{topics/types c gcc_jit_context_get_type}@anchor{b} @deffn {C Function} gcc_jit_type *gcc_jit_context_get_type (gcc_jit_context@w{ }*ctxt, enum gcc_jit_types@w{ }type_) Access a specific type. The available types are: @@ -5844,7 +5320,7 @@ Meaning @tab -C's @code{void} type. +C’s @code{void} type. @item @@ -5852,7 +5328,7 @@ C's @code{void} type. @tab -C's @code{void *}. +C’s @code{void *}. @item @@ -5860,7 +5336,7 @@ C's @code{void *}. @tab -C++'s @code{bool} type; also C99's +C++’s @code{bool} type; also C99’s @code{_Bool} type, aka @code{bool} if using stdbool.h. @@ -5870,7 +5346,7 @@ using stdbool.h. @tab -C's @code{char} (of some signedness) +C’s @code{char} (of some signedness) @item @@ -5878,7 +5354,7 @@ C's @code{char} (of some signedness) @tab -C's @code{signed char} +C’s @code{signed char} @item @@ -5886,7 +5362,7 @@ C's @code{signed char} @tab -C's @code{unsigned char} +C’s @code{unsigned char} @item @@ -5894,7 +5370,7 @@ C's @code{unsigned char} @tab -C's @code{short} (signed) +C’s @code{short} (signed) @item @@ -5902,7 +5378,7 @@ C's @code{short} (signed) @tab -C's @code{unsigned short} +C’s @code{unsigned short} @item @@ -5910,7 +5386,7 @@ C's @code{unsigned short} @tab -C's @code{int} (signed) +C’s @code{int} (signed) @item @@ -5918,7 +5394,7 @@ C's @code{int} (signed) @tab -C's @code{unsigned int} +C’s @code{unsigned int} @item @@ -5926,7 +5402,7 @@ C's @code{unsigned int} @tab -C's @code{long} (signed) +C’s @code{long} (signed) @item @@ -5934,7 +5410,7 @@ C's @code{long} (signed) @tab -C's @code{unsigned long} +C’s @code{unsigned long} @item @@ -5942,7 +5418,7 @@ C's @code{unsigned long} @tab -C99's @code{long long} (signed) +C99’s @code{long long} (signed) @item @@ -5950,7 +5426,7 @@ C99's @code{long long} (signed) @tab -C99's @code{unsigned long long} +C99’s @code{unsigned long long} @item @@ -5984,7 +5460,7 @@ C type: @code{(const char *)} @tab -C's @code{size_t} type +C’s @code{size_t} type @item @@ -6000,7 +5476,7 @@ C type: @code{(FILE *)} @tab -C99's @code{_Complex float} +C99’s @code{_Complex float} @item @@ -6008,7 +5484,7 @@ C99's @code{_Complex float} @tab -C99's @code{_Complex double} +C99’s @code{_Complex double} @item @@ -6016,93 +5492,87 @@ C99's @code{_Complex double} @tab -C99's @code{_Complex long double} +C99’s @code{_Complex long double} @end multitable @end deffn @geindex gcc_jit_context_get_int_type (C function) -@anchor{topics/types gcc_jit_context_get_int_type}@anchor{7c} +@anchor{topics/types c gcc_jit_context_get_int_type}@anchor{7e} @deffn {C Function} gcc_jit_type * gcc_jit_context_get_int_type (gcc_jit_context@w{ }*ctxt, int@w{ }num_bytes, int@w{ }is_signed) Access the integer type of the given size. @end deffn @node Pointers const and volatile,Vector types,Standard types,Types -@anchor{topics/types pointers-const-and-volatile}@anchor{7d} +@anchor{topics/types pointers-const-and-volatile}@anchor{7f} @subsection Pointers, @cite{const}, and @cite{volatile} @geindex gcc_jit_type_get_pointer (C function) -@anchor{topics/types gcc_jit_type_get_pointer}@anchor{79} +@anchor{topics/types c gcc_jit_type_get_pointer}@anchor{7b} @deffn {C Function} gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type@w{ }*type) -Given type "T", get type "T*". +Given type “T”, get type “T*”. @end deffn @geindex gcc_jit_type_get_const (C function) -@anchor{topics/types gcc_jit_type_get_const}@anchor{7a} +@anchor{topics/types c gcc_jit_type_get_const}@anchor{7c} @deffn {C Function} gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type@w{ }*type) -Given type "T", get type "const T". +Given type “T”, get type “const T”. @end deffn @geindex gcc_jit_type_get_volatile (C function) -@anchor{topics/types gcc_jit_type_get_volatile}@anchor{7e} +@anchor{topics/types c gcc_jit_type_get_volatile}@anchor{80} @deffn {C Function} gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type@w{ }*type) -Given type "T", get type "volatile T". +Given type “T”, get type “volatile T”. @end deffn @geindex gcc_jit_context_new_array_type (C function) -@anchor{topics/types gcc_jit_context_new_array_type}@anchor{7f} +@anchor{topics/types c gcc_jit_context_new_array_type}@anchor{81} @deffn {C Function} gcc_jit_type * gcc_jit_context_new_array_type (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*element_type, int@w{ }num_elements) -Given type "T", get type "T[N]" (for a constant N). +Given non-@cite{void} type “T”, get type “T[N]” (for a constant N). @end deffn @geindex gcc_jit_type_get_aligned (C function) -@anchor{topics/types gcc_jit_type_get_aligned}@anchor{80} +@anchor{topics/types c gcc_jit_type_get_aligned}@anchor{82} @deffn {C Function} gcc_jit_type * gcc_jit_type_get_aligned (gcc_jit_type@w{ }*type, size_t@w{ }alignment_in_bytes) -Given type "T", get type: +Given non-@cite{void} type “T”, get type: @example T __attribute__ ((aligned (ALIGNMENT_IN_BYTES))) @end example -@noindent - The alignment must be a power of two. -This entrypoint was added in @pxref{81,,LIBGCCJIT_ABI_7}; you can test for +This entrypoint was added in @ref{83,,LIBGCCJIT_ABI_7}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned @end example - -@noindent @end deffn @node Vector types,Structures and unions,Pointers const and volatile,Types -@anchor{topics/types vector-types}@anchor{82} +@anchor{topics/types vector-types}@anchor{84} @subsection Vector types @geindex gcc_jit_type_get_vector (C function) -@anchor{topics/types gcc_jit_type_get_vector}@anchor{83} +@anchor{topics/types c gcc_jit_type_get_vector}@anchor{85} @deffn {C Function} gcc_jit_type * gcc_jit_type_get_vector (gcc_jit_type@w{ }*type, size_t@w{ }num_units) -Given type "T", get type: +Given type “T”, get type: @example T __attribute__ ((vector_size (sizeof(T) * num_units)) @end example -@noindent - T must be integral or floating point; num_units must be a power of two. This can be used to construct a vector type in which operations @@ -6116,8 +5586,6 @@ For example, assuming 4-byte @code{ints}, then: typedef int v4si __attribute__ ((vector_size (16))); @end example -@noindent - can be obtained using: @example @@ -6126,42 +5594,38 @@ gcc_jit_type *int_type = gcc_jit_context_get_type (ctxt, gcc_jit_type *v4si_type = gcc_jit_type_get_vector (int_type, 4); @end example -@noindent - -This API entrypoint was added in @pxref{84,,LIBGCCJIT_ABI_8}; you can test +This API entrypoint was added in @ref{86,,LIBGCCJIT_ABI_8}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_vector @end example -@noindent - Vector rvalues can be generated using -@pxref{85,,gcc_jit_context_new_rvalue_from_vector()}. +@ref{87,,gcc_jit_context_new_rvalue_from_vector()}. @end deffn @node Structures and unions,Function pointer types,Vector types,Types -@anchor{topics/types structures-and-unions}@anchor{86} +@anchor{topics/types structures-and-unions}@anchor{88} @subsection Structures and unions @geindex gcc_jit_struct (C type) -@anchor{topics/types gcc_jit_struct}@anchor{87} +@anchor{topics/types c gcc_jit_struct}@anchor{89} @deffn {C Type} gcc_jit_struct @end deffn A compound type analagous to a C @cite{struct}. @geindex gcc_jit_field (C type) -@anchor{topics/types gcc_jit_field}@anchor{88} +@anchor{topics/types c gcc_jit_field}@anchor{8a} @deffn {C Type} gcc_jit_field @end deffn -A field within a @pxref{87,,gcc_jit_struct}. +A field within a @ref{89,,gcc_jit_struct}. -You can model C @cite{struct} types by creating @pxref{87,,gcc_jit_struct *} and -@pxref{88,,gcc_jit_field} instances, in either order: +You can model C @cite{struct} types by creating @ref{89,,gcc_jit_struct *} and +@ref{8a,,gcc_jit_field} instances, in either order: @itemize * @@ -6173,8 +5637,6 @@ by creating the fields, then the structure. For example, to model: struct coord @{double x; double y; @}; @end example -@noindent - you could call: @example @@ -6187,8 +5649,6 @@ gcc_jit_struct *coord = gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields); @end example -@noindent - @item by creating the structure, then populating it with fields, typically to allow modelling self-referential structs such as: @@ -6197,8 +5657,6 @@ to allow modelling self-referential structs such as: struct node @{ int m_hash; struct node *m_next; @}; @end example -@noindent - like this: @example @@ -6213,30 +5671,55 @@ gcc_jit_field *field_next = gcc_jit_field *fields[2] = @{field_hash, field_next@}; gcc_jit_struct_set_fields (node, NULL, 2, fields); @end example - -@noindent @end itemize @geindex gcc_jit_context_new_field (C function) -@anchor{topics/types gcc_jit_context_new_field}@anchor{89} +@anchor{topics/types c gcc_jit_context_new_field}@anchor{8b} @deffn {C Function} gcc_jit_field * gcc_jit_context_new_field (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, const char@w{ }*name) Construct a new field, with the given type and name. +The parameter @code{type} must be non-@cite{void}. + The parameter @code{name} must be non-NULL. The call takes a copy of the underlying string, so it is valid to pass in a pointer to an on-stack buffer. @end deffn +@geindex gcc_jit_context_new_bitfield (C function) +@anchor{topics/types c gcc_jit_context_new_bitfield}@anchor{8c} +@deffn {C Function} gcc_jit_field * gcc_jit_context_new_bitfield (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, int@w{ }width, const char@w{ }*name) + +Construct a new bit field, with the given type width and name. + +The parameter @code{name} must be non-NULL. The call takes a copy of the +underlying string, so it is valid to pass in a pointer to an on-stack +buffer. + +The parameter @code{type} must be an integer type. + +The parameter @code{width} must be a positive integer that does not exceed the +size of @code{type}. + +This API entrypoint was added in LIBGCCJIT_ABI_12; you can test +for its presence using +.. code-block:: c + +@quotation + +#ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitfield +@end quotation +@end deffn + @geindex gcc_jit_field_as_object (C function) -@anchor{topics/types gcc_jit_field_as_object}@anchor{8a} +@anchor{topics/types c gcc_jit_field_as_object}@anchor{8d} @deffn {C Function} gcc_jit_object * gcc_jit_field_as_object (gcc_jit_field@w{ }*field) Upcast from field to object. @end deffn @geindex gcc_jit_context_new_struct_type (C function) -@anchor{topics/types gcc_jit_context_new_struct_type}@anchor{8b} +@anchor{topics/types c gcc_jit_context_new_struct_type}@anchor{8e} @deffn {C Function} gcc_jit_struct *gcc_jit_context_new_struct_type (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, const char@w{ }*name, int@w{ }num_fields, gcc_jit_field@w{ }**fields) @quotation @@ -6250,13 +5733,13 @@ on-stack buffer. @end deffn @geindex gcc_jit_context_new_opaque_struct (C function) -@anchor{topics/types gcc_jit_context_new_opaque_struct}@anchor{8c} +@anchor{topics/types c gcc_jit_context_new_opaque_struct}@anchor{8f} @deffn {C Function} gcc_jit_struct * gcc_jit_context_new_opaque_struct (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, const char@w{ }*name) Construct a new struct type, with the given name, but without specifying the fields. The fields can be omitted (in which case the size of the struct is not known), or later specified using -@pxref{8d,,gcc_jit_struct_set_fields()}. +@ref{90,,gcc_jit_struct_set_fields()}. The parameter @code{name} must be non-NULL. The call takes a copy of the underlying string, so it is valid to pass in a pointer to an @@ -6264,14 +5747,14 @@ on-stack buffer. @end deffn @geindex gcc_jit_struct_as_type (C function) -@anchor{topics/types gcc_jit_struct_as_type}@anchor{8e} +@anchor{topics/types c gcc_jit_struct_as_type}@anchor{91} @deffn {C Function} gcc_jit_type * gcc_jit_struct_as_type (gcc_jit_struct@w{ }*struct_type) Upcast from struct to type. @end deffn @geindex gcc_jit_struct_set_fields (C function) -@anchor{topics/types gcc_jit_struct_set_fields}@anchor{8d} +@anchor{topics/types c gcc_jit_struct_set_fields}@anchor{90} @deffn {C Function} void gcc_jit_struct_set_fields (gcc_jit_struct@w{ }*struct_type, gcc_jit_location@w{ }*loc, int@w{ }num_fields, gcc_jit_field@w{ }**fields) Populate the fields of a formerly-opaque struct type. @@ -6280,7 +5763,7 @@ This can only be called once on a given struct type. @end deffn @geindex gcc_jit_context_new_union_type (C function) -@anchor{topics/types gcc_jit_context_new_union_type}@anchor{8f} +@anchor{topics/types c gcc_jit_context_new_union_type}@anchor{92} @deffn {C Function} gcc_jit_type * gcc_jit_context_new_union_type (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, const char@w{ }*name, int@w{ }num_fields, gcc_jit_field@w{ }**fields) Construct a new union type, with the given name and fields. @@ -6364,19 +5847,16 @@ create_code (gcc_jit_context *ctxt, void *user_data) as_float)); @} - @end example - -@noindent @end deffn @node Function pointer types,,Structures and unions,Types -@anchor{topics/types function-pointer-types}@anchor{90} +@anchor{topics/types function-pointer-types}@anchor{93} @subsection Function pointer types Function pointer types can be created using -@pxref{91,,gcc_jit_context_new_function_ptr_type()}. +@ref{94,,gcc_jit_context_new_function_ptr_type()}. @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @@ -6396,7 +5876,7 @@ Function pointer types can be created using @c <http://www.gnu.org/licenses/>. @node Expressions,Creating and using functions,Types,Topic Reference -@anchor{topics/expressions expressions}@anchor{92}@anchor{topics/expressions doc}@anchor{93} +@anchor{topics/expressions doc}@anchor{95}@anchor{topics/expressions expressions}@anchor{96} @section Expressions @@ -6405,35 +5885,19 @@ Function pointer types can be created using * Lvalues:: * Working with pointers@comma{} structs and unions: Working with pointers structs and unions. -Rvalues - -* Simple expressions:: -* Vector expressions:: -* Unary Operations:: -* Binary Operations:: -* Comparisons:: -* Function calls:: -* Function pointers:: -* Type-coercion:: - -Lvalues - -* Global variables:: - @end menu - @node Rvalues,Lvalues,,Expressions -@anchor{topics/expressions rvalues}@anchor{94} +@anchor{topics/expressions rvalues}@anchor{97} @subsection Rvalues @geindex gcc_jit_rvalue (C type) -@anchor{topics/expressions gcc_jit_rvalue}@anchor{13} +@anchor{topics/expressions c gcc_jit_rvalue}@anchor{13} @deffn {C Type} gcc_jit_rvalue @end deffn -A @pxref{13,,gcc_jit_rvalue *} is an expression that can be computed. +A @ref{13,,gcc_jit_rvalue *} is an expression that can be computed. It can be simple, e.g.: @@ -6446,7 +5910,7 @@ It can be simple, e.g.: an integer value e.g. @cite{0} or @cite{42} @item -a string literal e.g. @cite{"Hello world"} +a string literal e.g. @cite{“Hello world”} @item a variable e.g. @cite{i}. These are also lvalues (see below). @@ -6478,14 +5942,14 @@ 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{95} +@anchor{topics/expressions c gcc_jit_rvalue_get_type}@anchor{98} @deffn {C Function} gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue@w{ }*rvalue) Get the type of this rvalue. @end deffn @geindex gcc_jit_rvalue_as_object (C function) -@anchor{topics/expressions gcc_jit_rvalue_as_object}@anchor{14} +@anchor{topics/expressions c gcc_jit_rvalue_as_object}@anchor{14} @deffn {C Function} gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue@w{ }*rvalue) Upcast the given rvalue to be an object. @@ -6504,12 +5968,12 @@ Upcast the given rvalue to be an object. @end menu @node Simple expressions,Vector expressions,,Rvalues -@anchor{topics/expressions simple-expressions}@anchor{96} +@anchor{topics/expressions simple-expressions}@anchor{99} @subsubsection Simple expressions @geindex gcc_jit_context_new_rvalue_from_int (C function) -@anchor{topics/expressions gcc_jit_context_new_rvalue_from_int}@anchor{30} +@anchor{topics/expressions c gcc_jit_context_new_rvalue_from_int}@anchor{30} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_int (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type, int@w{ }value) Given a numeric type (integer or floating point), build an rvalue for @@ -6517,7 +5981,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{97} +@anchor{topics/expressions c gcc_jit_context_new_rvalue_from_long}@anchor{9a} @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 @@ -6525,7 +5989,7 @@ the given constant @code{long} value. @end deffn @geindex gcc_jit_context_zero (C function) -@anchor{topics/expressions gcc_jit_context_zero}@anchor{2b} +@anchor{topics/expressions c gcc_jit_context_zero}@anchor{2b} @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type) Given a numeric type (integer or floating point), get the rvalue for @@ -6534,12 +5998,10 @@ zero. Essentially this is just a shortcut for: @example gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0) @end example - -@noindent @end deffn @geindex gcc_jit_context_one (C function) -@anchor{topics/expressions gcc_jit_context_one}@anchor{2f} +@anchor{topics/expressions c gcc_jit_context_one}@anchor{2f} @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type) Given a numeric type (integer or floating point), get the rvalue for @@ -6548,12 +6010,10 @@ one. Essentially this is just a shortcut for: @example gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1) @end example - -@noindent @end deffn @geindex gcc_jit_context_new_rvalue_from_double (C function) -@anchor{topics/expressions gcc_jit_context_new_rvalue_from_double}@anchor{31} +@anchor{topics/expressions c gcc_jit_context_new_rvalue_from_double}@anchor{31} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_double (gcc_jit_context@w{ }*ctxt, gcc_jit_type@w{ }*numeric_type, double@w{ }value) Given a numeric type (integer or floating point), build an rvalue for @@ -6561,14 +6021,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{98} +@anchor{topics/expressions c gcc_jit_context_new_rvalue_from_ptr}@anchor{9b} @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{99} +@anchor{topics/expressions c gcc_jit_context_null}@anchor{9c} @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 @@ -6577,12 +6037,10 @@ is just a shortcut for: @example gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL) @end example - -@noindent @end deffn @geindex gcc_jit_context_new_string_literal (C function) -@anchor{topics/expressions gcc_jit_context_new_string_literal}@anchor{9a} +@anchor{topics/expressions c gcc_jit_context_new_string_literal}@anchor{9d} @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 @@ -6594,45 +6052,45 @@ buffer. @end deffn @node Vector expressions,Unary Operations,Simple expressions,Rvalues -@anchor{topics/expressions vector-expressions}@anchor{9b} +@anchor{topics/expressions vector-expressions}@anchor{9e} @subsubsection Vector expressions @geindex gcc_jit_context_new_rvalue_from_vector (C function) -@anchor{topics/expressions gcc_jit_context_new_rvalue_from_vector}@anchor{85} +@anchor{topics/expressions c gcc_jit_context_new_rvalue_from_vector}@anchor{87} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_rvalue_from_vector (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*vec_type, size_t@w{ }num_elements, gcc_jit_rvalue@w{ }**elements) Build a vector rvalue from an array of elements. -"vec_type" should be a vector type, created using -@pxref{83,,gcc_jit_type_get_vector()}. +“vec_type” should be a vector type, created using +@ref{85,,gcc_jit_type_get_vector()}. -"num_elements" should match that of the vector type. +“num_elements” should match that of the vector type. -This entrypoint was added in @pxref{9c,,LIBGCCJIT_ABI_10}; you can test for +This entrypoint was added in @ref{9f,,LIBGCCJIT_ABI_10}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector @end example - -@noindent @end deffn @node Unary Operations,Binary Operations,Vector expressions,Rvalues -@anchor{topics/expressions unary-operations}@anchor{9d} +@anchor{topics/expressions unary-operations}@anchor{a0} @subsubsection Unary Operations @geindex gcc_jit_context_new_unary_op (C function) -@anchor{topics/expressions gcc_jit_context_new_unary_op}@anchor{9e} +@anchor{topics/expressions c gcc_jit_context_new_unary_op}@anchor{a1} @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. + +The parameter @code{result_type} must be a numeric type. @end deffn @geindex gcc_jit_unary_op (C type) -@anchor{topics/expressions gcc_jit_unary_op}@anchor{9f} +@anchor{topics/expressions c gcc_jit_unary_op}@anchor{a2} @deffn {C Type} enum gcc_jit_unary_op @end deffn @@ -6650,7 +6108,7 @@ C equivalent @item -@pxref{a0,,GCC_JIT_UNARY_OP_MINUS} +@ref{a3,,GCC_JIT_UNARY_OP_MINUS} @tab @@ -6658,7 +6116,7 @@ C equivalent @item -@pxref{a1,,GCC_JIT_UNARY_OP_BITWISE_NEGATE} +@ref{a4,,GCC_JIT_UNARY_OP_BITWISE_NEGATE} @tab @@ -6666,7 +6124,7 @@ C equivalent @item -@pxref{a2,,GCC_JIT_UNARY_OP_LOGICAL_NEGATE} +@ref{a5,,GCC_JIT_UNARY_OP_LOGICAL_NEGATE} @tab @@ -6674,7 +6132,7 @@ C equivalent @item -@pxref{a3,,GCC_JIT_UNARY_OP_ABS} +@ref{a6,,GCC_JIT_UNARY_OP_ABS} @tab @@ -6684,7 +6142,7 @@ C equivalent @geindex GCC_JIT_UNARY_OP_MINUS (C macro) -@anchor{topics/expressions GCC_JIT_UNARY_OP_MINUS}@anchor{a0} +@anchor{topics/expressions c GCC_JIT_UNARY_OP_MINUS}@anchor{a3} @deffn {C Macro} GCC_JIT_UNARY_OP_MINUS Negate an arithmetic value; analogous to: @@ -6693,29 +6151,25 @@ Negate an arithmetic value; analogous to: -(EXPR) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_UNARY_OP_BITWISE_NEGATE (C macro) -@anchor{topics/expressions GCC_JIT_UNARY_OP_BITWISE_NEGATE}@anchor{a1} +@anchor{topics/expressions c GCC_JIT_UNARY_OP_BITWISE_NEGATE}@anchor{a4} @deffn {C Macro} GCC_JIT_UNARY_OP_BITWISE_NEGATE -Bitwise negation of an integer value (one's complement); analogous +Bitwise negation of an integer value (one’s complement); analogous to: @example ~(EXPR) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_UNARY_OP_LOGICAL_NEGATE (C macro) -@anchor{topics/expressions GCC_JIT_UNARY_OP_LOGICAL_NEGATE}@anchor{a2} +@anchor{topics/expressions c GCC_JIT_UNARY_OP_LOGICAL_NEGATE}@anchor{a5} @deffn {C Macro} GCC_JIT_UNARY_OP_LOGICAL_NEGATE Logical negation of an arithmetic or pointer value; analogous to: @@ -6724,13 +6178,11 @@ Logical negation of an arithmetic or pointer value; analogous to: !(EXPR) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_UNARY_OP_ABS (C macro) -@anchor{topics/expressions GCC_JIT_UNARY_OP_ABS}@anchor{a3} +@anchor{topics/expressions c GCC_JIT_UNARY_OP_ABS}@anchor{a6} @deffn {C Macro} GCC_JIT_UNARY_OP_ABS Absolute value of an arithmetic expression; analogous to: @@ -6739,25 +6191,25 @@ Absolute value of an arithmetic expression; analogous to: abs (EXPR) @end example -@noindent - in C. @end deffn @node Binary Operations,Comparisons,Unary Operations,Rvalues -@anchor{topics/expressions binary-operations}@anchor{a4} +@anchor{topics/expressions binary-operations}@anchor{a7} @subsubsection Binary Operations @geindex gcc_jit_context_new_binary_op (C function) -@anchor{topics/expressions gcc_jit_context_new_binary_op}@anchor{12} +@anchor{topics/expressions c gcc_jit_context_new_binary_op}@anchor{12} @deffn {C Function} gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_binary_op@w{ }op, gcc_jit_type@w{ }*result_type, gcc_jit_rvalue@w{ }*a, gcc_jit_rvalue@w{ }*b) Build a binary operation out of two constituent rvalues. + +The parameter @code{result_type} must be a numeric type. @end deffn @geindex gcc_jit_binary_op (C type) -@anchor{topics/expressions gcc_jit_binary_op}@anchor{a5} +@anchor{topics/expressions c gcc_jit_binary_op}@anchor{a8} @deffn {C Type} enum gcc_jit_binary_op @end deffn @@ -6775,7 +6227,7 @@ C equivalent @item -@pxref{a6,,GCC_JIT_BINARY_OP_PLUS} +@ref{a9,,GCC_JIT_BINARY_OP_PLUS} @tab @@ -6783,7 +6235,7 @@ C equivalent @item -@pxref{a7,,GCC_JIT_BINARY_OP_MINUS} +@ref{aa,,GCC_JIT_BINARY_OP_MINUS} @tab @@ -6791,7 +6243,7 @@ C equivalent @item -@pxref{a8,,GCC_JIT_BINARY_OP_MULT} +@ref{ab,,GCC_JIT_BINARY_OP_MULT} @tab @@ -6799,7 +6251,7 @@ C equivalent @item -@pxref{a9,,GCC_JIT_BINARY_OP_DIVIDE} +@ref{ac,,GCC_JIT_BINARY_OP_DIVIDE} @tab @@ -6807,7 +6259,7 @@ C equivalent @item -@pxref{aa,,GCC_JIT_BINARY_OP_MODULO} +@ref{ad,,GCC_JIT_BINARY_OP_MODULO} @tab @@ -6815,7 +6267,7 @@ C equivalent @item -@pxref{ab,,GCC_JIT_BINARY_OP_BITWISE_AND} +@ref{ae,,GCC_JIT_BINARY_OP_BITWISE_AND} @tab @@ -6823,7 +6275,7 @@ C equivalent @item -@pxref{ac,,GCC_JIT_BINARY_OP_BITWISE_XOR} +@ref{af,,GCC_JIT_BINARY_OP_BITWISE_XOR} @tab @@ -6831,7 +6283,7 @@ C equivalent @item -@pxref{ad,,GCC_JIT_BINARY_OP_BITWISE_OR} +@ref{b0,,GCC_JIT_BINARY_OP_BITWISE_OR} @tab @@ -6839,7 +6291,7 @@ C equivalent @item -@pxref{ae,,GCC_JIT_BINARY_OP_LOGICAL_AND} +@ref{b1,,GCC_JIT_BINARY_OP_LOGICAL_AND} @tab @@ -6847,7 +6299,7 @@ C equivalent @item -@pxref{af,,GCC_JIT_BINARY_OP_LOGICAL_OR} +@ref{b2,,GCC_JIT_BINARY_OP_LOGICAL_OR} @tab @@ -6855,7 +6307,7 @@ C equivalent @item -@pxref{b0,,GCC_JIT_BINARY_OP_LSHIFT} +@ref{b3,,GCC_JIT_BINARY_OP_LSHIFT} @tab @@ -6863,7 +6315,7 @@ C equivalent @item -@pxref{b1,,GCC_JIT_BINARY_OP_RSHIFT} +@ref{b4,,GCC_JIT_BINARY_OP_RSHIFT} @tab @@ -6873,7 +6325,7 @@ C equivalent @geindex GCC_JIT_BINARY_OP_PLUS (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_PLUS}@anchor{a6} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_PLUS}@anchor{a9} @deffn {C Macro} GCC_JIT_BINARY_OP_PLUS Addition of arithmetic values; analogous to: @@ -6882,15 +6334,13 @@ Addition of arithmetic values; analogous to: (EXPR_A) + (EXPR_B) @end example -@noindent - in C. -For pointer addition, use @pxref{b2,,gcc_jit_context_new_array_access()}. +For pointer addition, use @ref{b5,,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{a7} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_MINUS}@anchor{aa} @deffn {C Macro} GCC_JIT_BINARY_OP_MINUS Subtraction of arithmetic values; analogous to: @@ -6899,13 +6349,11 @@ Subtraction of arithmetic values; analogous to: (EXPR_A) - (EXPR_B) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_BINARY_OP_MULT (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_MULT}@anchor{a8} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_MULT}@anchor{ab} @deffn {C Macro} GCC_JIT_BINARY_OP_MULT Multiplication of a pair of arithmetic values; analogous to: @@ -6914,13 +6362,11 @@ Multiplication of a pair of arithmetic values; analogous to: (EXPR_A) * (EXPR_B) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_BINARY_OP_DIVIDE (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_DIVIDE}@anchor{a9} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_DIVIDE}@anchor{ac} @deffn {C Macro} GCC_JIT_BINARY_OP_DIVIDE Quotient of division of arithmetic values; analogous to: @@ -6929,8 +6375,6 @@ Quotient of division of arithmetic values; analogous to: (EXPR_A) / (EXPR_B) @end example -@noindent - in C. The result type affects the kind of division: if the result type is @@ -6939,7 +6383,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{aa} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_MODULO}@anchor{ad} @deffn {C Macro} GCC_JIT_BINARY_OP_MODULO Remainder of division of arithmetic values; analogous to: @@ -6948,13 +6392,11 @@ Remainder of division of arithmetic values; analogous to: (EXPR_A) % (EXPR_B) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_BINARY_OP_BITWISE_AND (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_AND}@anchor{ab} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_BITWISE_AND}@anchor{ae} @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_AND Bitwise AND; analogous to: @@ -6963,13 +6405,11 @@ Bitwise AND; analogous to: (EXPR_A) & (EXPR_B) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_BINARY_OP_BITWISE_XOR (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_XOR}@anchor{ac} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_BITWISE_XOR}@anchor{af} @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_XOR Bitwise exclusive OR; analogous to: @@ -6978,13 +6418,11 @@ Bitwise exclusive OR; analogous to: (EXPR_A) ^ (EXPR_B) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_BINARY_OP_BITWISE_OR (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_BITWISE_OR}@anchor{ad} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_BITWISE_OR}@anchor{b0} @deffn {C Macro} GCC_JIT_BINARY_OP_BITWISE_OR Bitwise inclusive OR; analogous to: @@ -6993,13 +6431,11 @@ Bitwise inclusive OR; analogous to: (EXPR_A) | (EXPR_B) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_BINARY_OP_LOGICAL_AND (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_AND}@anchor{ae} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_LOGICAL_AND}@anchor{b1} @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_AND Logical AND; analogous to: @@ -7008,13 +6444,11 @@ Logical AND; analogous to: (EXPR_A) && (EXPR_B) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_BINARY_OP_LOGICAL_OR (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_LOGICAL_OR}@anchor{af} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_LOGICAL_OR}@anchor{b2} @deffn {C Macro} GCC_JIT_BINARY_OP_LOGICAL_OR Logical OR; analogous to: @@ -7023,13 +6457,11 @@ Logical OR; analogous to: (EXPR_A) || (EXPR_B) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_BINARY_OP_LSHIFT (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_LSHIFT}@anchor{b0} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_LSHIFT}@anchor{b3} @deffn {C Macro} GCC_JIT_BINARY_OP_LSHIFT Left shift; analogous to: @@ -7038,13 +6470,11 @@ Left shift; analogous to: (EXPR_A) << (EXPR_B) @end example -@noindent - in C. @end deffn @geindex GCC_JIT_BINARY_OP_RSHIFT (C macro) -@anchor{topics/expressions GCC_JIT_BINARY_OP_RSHIFT}@anchor{b1} +@anchor{topics/expressions c GCC_JIT_BINARY_OP_RSHIFT}@anchor{b4} @deffn {C Macro} GCC_JIT_BINARY_OP_RSHIFT Right shift; analogous to: @@ -7053,25 +6483,23 @@ Right shift; analogous to: (EXPR_A) >> (EXPR_B) @end example -@noindent - in C. @end deffn @node Comparisons,Function calls,Binary Operations,Rvalues -@anchor{topics/expressions comparisons}@anchor{b3} +@anchor{topics/expressions comparisons}@anchor{b6} @subsubsection Comparisons @geindex gcc_jit_context_new_comparison (C function) -@anchor{topics/expressions gcc_jit_context_new_comparison}@anchor{2c} +@anchor{topics/expressions c gcc_jit_context_new_comparison}@anchor{2c} @deffn {C Function} gcc_jit_rvalue * gcc_jit_context_new_comparison (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_comparison@w{ }op, gcc_jit_rvalue@w{ }*a, gcc_jit_rvalue@w{ }*b) 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{b4} +@anchor{topics/expressions c gcc_jit_comparison}@anchor{b7} @deffn {C Type} enum gcc_jit_comparison @end deffn @@ -7137,12 +6565,12 @@ C equivalent @node Function calls,Function pointers,Comparisons,Rvalues -@anchor{topics/expressions function-calls}@anchor{b5} +@anchor{topics/expressions function-calls}@anchor{b8} @subsubsection Function calls @geindex gcc_jit_context_new_call (C function) -@anchor{topics/expressions gcc_jit_context_new_call}@anchor{b6} +@anchor{topics/expressions c gcc_jit_context_new_call}@anchor{b9} @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 @@ -7150,15 +6578,15 @@ call to the function, with the result as an rvalue. @cartouche @quotation Note -@pxref{b6,,gcc_jit_context_new_call()} merely builds a -@pxref{13,,gcc_jit_rvalue} i.e. an expression that can be evaluated, +@ref{b9,,gcc_jit_context_new_call()} merely builds a +@ref{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 +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{b7,,gcc_jit_block_add_eval()}: +@ref{ba,,gcc_jit_block_add_eval()}: @example /* Add "(void)printf (arg0, arg1);". */ @@ -7170,58 +6598,54 @@ gcc_jit_block_add_eval ( printf_func, 2, args)); @end example - -@noindent @end quotation @end cartouche @end deffn @geindex gcc_jit_context_new_call_through_ptr (C function) -@anchor{topics/expressions gcc_jit_context_new_call_through_ptr}@anchor{b8} +@anchor{topics/expressions c gcc_jit_context_new_call_through_ptr}@anchor{bb} @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 (e.g. from -@pxref{91,,gcc_jit_context_new_function_ptr_type()}), and the given table of +@ref{94,,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{b6,,gcc_jit_context_new_call()} applies. +The same caveat as for @ref{b9,,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{b9} +@anchor{topics/expressions c gcc_jit_rvalue_set_bool_require_tail_call}@anchor{bc} @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{b6,,gcc_jit_context_new_call()} or -@pxref{b8,,gcc_jit_context_new_call_through_ptr()}, mark/clear the +Given an @ref{13,,gcc_jit_rvalue *} for a call created through +@ref{b9,,gcc_jit_context_new_call()} or +@ref{bb,,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. This may be useful when implementing functions that use the continuation-passing style (e.g. for functional programming -languages), in which every function "returns" by calling a -"continuation" function pointer. This call must be +languages), in which every function “returns” by calling a +“continuation” function pointer. This call must be 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{ba,,LIBGCCJIT_ABI_6}; you can test for +This entrypoint was added in @ref{bd,,LIBGCCJIT_ABI_6}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call @end example - -@noindent @end deffn @node Function pointers,Type-coercion,Function calls,Rvalues -@anchor{topics/expressions function-pointers}@anchor{bb} +@anchor{topics/expressions function-pointers}@anchor{be} @subsubsection Function pointers @@ -7233,24 +6657,24 @@ Function pointers can be obtained: @itemize * @item -from a @pxref{29,,gcc_jit_function} using -@pxref{bc,,gcc_jit_function_get_address()}, or +from a @ref{29,,gcc_jit_function} using +@ref{bf,,gcc_jit_function_get_address()}, or @item from an existing function using -@pxref{98,,gcc_jit_context_new_rvalue_from_ptr()}, +@ref{9b,,gcc_jit_context_new_rvalue_from_ptr()}, using a function pointer type obtained using -@pxref{91,,gcc_jit_context_new_function_ptr_type()}. +@ref{94,,gcc_jit_context_new_function_ptr_type()}. @end itemize @end quotation @node Type-coercion,,Function pointers,Rvalues -@anchor{topics/expressions type-coercion}@anchor{bd} +@anchor{topics/expressions type-coercion}@anchor{c0} @subsubsection Type-coercion @geindex gcc_jit_context_new_cast (C function) -@anchor{topics/expressions gcc_jit_context_new_cast}@anchor{be} +@anchor{topics/expressions c gcc_jit_context_new_cast}@anchor{c1} @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. @@ -7275,12 +6699,12 @@ 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{bf} +@anchor{topics/expressions lvalues}@anchor{c2} @subsection Lvalues @geindex gcc_jit_lvalue (C type) -@anchor{topics/expressions gcc_jit_lvalue}@anchor{24} +@anchor{topics/expressions c gcc_jit_lvalue}@anchor{24} @deffn {C Type} gcc_jit_lvalue @end deffn @@ -7289,21 +6713,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{c0} +@anchor{topics/expressions c gcc_jit_lvalue_as_object}@anchor{c3} @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{c1} +@anchor{topics/expressions c gcc_jit_lvalue_as_rvalue}@anchor{c4} @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{c2} +@anchor{topics/expressions c gcc_jit_lvalue_get_address}@anchor{c5} @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: @@ -7312,8 +6736,6 @@ Take the address of an lvalue; analogous to: &(EXPR) @end example -@noindent - in C. @end deffn @@ -7323,65 +6745,67 @@ in C. @end menu @node Global variables,,,Lvalues -@anchor{topics/expressions global-variables}@anchor{c3} +@anchor{topics/expressions global-variables}@anchor{c6} @subsubsection Global variables @geindex gcc_jit_context_new_global (C function) -@anchor{topics/expressions gcc_jit_context_new_global}@anchor{c4} +@anchor{topics/expressions c gcc_jit_context_new_global}@anchor{c7} @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. +The parameter @code{type} must be non-@cite{void}. + The parameter @code{name} must be non-NULL. The call takes a copy of the underlying string, so it is valid to pass in a pointer to an on-stack buffer. -The "kind" parameter determines the visibility of the "global" outside -of the @pxref{16,,gcc_jit_result}: +The “kind” parameter determines the visibility of the “global” outside +of the @ref{16,,gcc_jit_result}: @geindex gcc_jit_global_kind (C type) -@anchor{topics/expressions gcc_jit_global_kind}@anchor{c5} +@anchor{topics/expressions c gcc_jit_global_kind}@anchor{c8} @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{c6} +@anchor{topics/expressions c GCC_JIT_GLOBAL_EXPORTED}@anchor{c9} @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{c7,,gcc_jit_result_get_global()} (and this value is required for +@ref{ca,,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{c8} +@anchor{topics/expressions c GCC_JIT_GLOBAL_INTERNAL}@anchor{cb} @deffn {C Macro} GCC_JIT_GLOBAL_INTERNAL Global is defined by the client code, but is invisible -outside of it. Analogous to a "static" global within a .c file. +outside of it. Analogous to a “static” global within a .c file. Specifically, the variable will only be visible within this context and within child contexts. @end deffn @geindex GCC_JIT_GLOBAL_IMPORTED (C macro) -@anchor{topics/expressions GCC_JIT_GLOBAL_IMPORTED}@anchor{c9} +@anchor{topics/expressions c GCC_JIT_GLOBAL_IMPORTED}@anchor{cc} @deffn {C Macro} GCC_JIT_GLOBAL_IMPORTED -Global is not defined by the client code; we're merely -referring to it. Analogous to using an "extern" global from a +Global is not defined by the client code; we’re merely +referring to it. Analogous to using an “extern” global from a header file. @end deffn @end deffn @node Working with pointers structs and unions,,Lvalues,Expressions -@anchor{topics/expressions working-with-pointers-structs-and-unions}@anchor{ca} +@anchor{topics/expressions working-with-pointers-structs-and-unions}@anchor{cd} @subsection Working with pointers, structs and unions @geindex gcc_jit_rvalue_dereference (C function) -@anchor{topics/expressions gcc_jit_rvalue_dereference}@anchor{cb} +@anchor{topics/expressions c gcc_jit_rvalue_dereference}@anchor{ce} @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, @@ -7391,31 +6815,27 @@ getting an lvalue of type @code{T}. Analogous to: *(EXPR) @end example -@noindent - in C. @end deffn 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{cc} +@anchor{topics/expressions c gcc_jit_lvalue_access_field}@anchor{cf} @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, -getting an lvalue of the field's type. Analogous to: +getting an lvalue of the field’s type. Analogous to: @example (EXPR).field = ...; @end example -@noindent - in C. @end deffn @geindex gcc_jit_rvalue_access_field (C function) -@anchor{topics/expressions gcc_jit_rvalue_access_field}@anchor{cd} +@anchor{topics/expressions c gcc_jit_rvalue_access_field}@anchor{d0} @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 @@ -7425,13 +6845,11 @@ as an rvalue. Analogous to: (EXPR).field @end example -@noindent - in C. @end deffn @geindex gcc_jit_rvalue_dereference_field (C function) -@anchor{topics/expressions gcc_jit_rvalue_dereference_field}@anchor{ce} +@anchor{topics/expressions c gcc_jit_rvalue_dereference_field}@anchor{d1} @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 @@ -7441,13 +6859,11 @@ type, access the given field as an lvalue. Analogous to: (EXPR)->field @end example -@noindent - 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{b2} +@anchor{topics/expressions c gcc_jit_context_new_array_access}@anchor{b5} @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 @@ -7459,8 +6875,6 @@ Analogous to: PTR[INDEX] @end example -@noindent - in C (or, indeed, to @code{PTR + INDEX}). @end deffn @@ -7482,7 +6896,7 @@ in C (or, indeed, to @code{PTR + INDEX}). @c <http://www.gnu.org/licenses/>. @node Creating and using functions,Function pointers<2>,Expressions,Topic Reference -@anchor{topics/functions doc}@anchor{cf}@anchor{topics/functions creating-and-using-functions}@anchor{d0} +@anchor{topics/functions doc}@anchor{d2}@anchor{topics/functions creating-and-using-functions}@anchor{d3} @section Creating and using functions @@ -7495,24 +6909,26 @@ in C (or, indeed, to @code{PTR + INDEX}). @end menu @node Params,Functions,,Creating and using functions -@anchor{topics/functions params}@anchor{d1} +@anchor{topics/functions params}@anchor{d4} @subsection Params @geindex gcc_jit_param (C type) -@anchor{topics/functions gcc_jit_param}@anchor{25} +@anchor{topics/functions c gcc_jit_param}@anchor{25} @deffn {C Type} gcc_jit_param A @cite{gcc_jit_param} represents a parameter to a function. @end deffn @geindex gcc_jit_context_new_param (C function) -@anchor{topics/functions gcc_jit_context_new_param}@anchor{10} +@anchor{topics/functions c gcc_jit_context_new_param}@anchor{10} @deffn {C Function} gcc_jit_param * gcc_jit_context_new_param (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, const char@w{ }*name) In preparation for creating a function, create a new parameter of the given type and name. +The parameter @code{type} must be non-@cite{void}. + The parameter @code{name} must be non-NULL. The call takes a copy of the underlying string, so it is valid to pass in a pointer to an on-stack buffer. @@ -7522,47 +6938,47 @@ 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{d2} +@anchor{topics/functions c gcc_jit_param_as_lvalue}@anchor{d5} @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{d3} +@anchor{topics/functions c gcc_jit_param_as_rvalue}@anchor{d6} @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{d4} +@anchor{topics/functions c gcc_jit_param_as_object}@anchor{d7} @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{d5} +@anchor{topics/functions functions}@anchor{d8} @subsection Functions @geindex gcc_jit_function (C type) -@anchor{topics/functions gcc_jit_function}@anchor{29} +@anchor{topics/functions c gcc_jit_function}@anchor{29} @deffn {C Type} gcc_jit_function -A @cite{gcc_jit_function} represents a function - either one that we're -creating ourselves, or one that we're referencing. +A @cite{gcc_jit_function} represents a function - either one that we’re +creating ourselves, or one that we’re referencing. @end deffn @geindex gcc_jit_context_new_function (C function) -@anchor{topics/functions gcc_jit_context_new_function}@anchor{11} +@anchor{topics/functions c gcc_jit_context_new_function}@anchor{11} @deffn {C Function} gcc_jit_function * gcc_jit_context_new_function (gcc_jit_context@w{ }*ctxt, gcc_jit_location@w{ }*loc, enum gcc_jit_function_kind@w{ }kind, gcc_jit_type@w{ }*return_type, const char@w{ }*name, int@w{ }num_params, gcc_jit_param@w{ }**params, int@w{ }is_variadic) 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{d6} +@anchor{topics/functions c gcc_jit_function_kind}@anchor{d9} @deffn {C Type} enum gcc_jit_function_kind @end deffn @@ -7572,36 +6988,36 @@ values: @quotation @geindex GCC_JIT_FUNCTION_EXPORTED (C macro) -@anchor{topics/functions GCC_JIT_FUNCTION_EXPORTED}@anchor{d7} +@anchor{topics/functions c GCC_JIT_FUNCTION_EXPORTED}@anchor{da} @deffn {C Macro} GCC_JIT_FUNCTION_EXPORTED Function is defined by the client code and visible by name outside of the JIT. This value is required if you want to extract machine code -for this function from a @pxref{16,,gcc_jit_result} via -@pxref{17,,gcc_jit_result_get_code()}. +for this function from a @ref{16,,gcc_jit_result} via +@ref{17,,gcc_jit_result_get_code()}. @end deffn @geindex GCC_JIT_FUNCTION_INTERNAL (C macro) -@anchor{topics/functions GCC_JIT_FUNCTION_INTERNAL}@anchor{d8} +@anchor{topics/functions c GCC_JIT_FUNCTION_INTERNAL}@anchor{db} @deffn {C Macro} GCC_JIT_FUNCTION_INTERNAL Function is defined by the client code, but is invisible -outside of the JIT. Analogous to a "static" function. +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{d9} +@anchor{topics/functions c GCC_JIT_FUNCTION_IMPORTED}@anchor{dc} @deffn {C Macro} GCC_JIT_FUNCTION_IMPORTED -Function is not defined by the client code; we're merely -referring to it. Analogous to using an "extern" function from a +Function is not defined by the client code; we’re merely +referring to it. Analogous to using an “extern” function from a header file. @end deffn @geindex GCC_JIT_FUNCTION_ALWAYS_INLINE (C macro) -@anchor{topics/functions GCC_JIT_FUNCTION_ALWAYS_INLINE}@anchor{da} +@anchor{topics/functions c GCC_JIT_FUNCTION_ALWAYS_INLINE}@anchor{dd} @deffn {C Macro} GCC_JIT_FUNCTION_ALWAYS_INLINE Function is only ever inlined into other functions, and is @@ -7622,50 +7038,52 @@ buffer. @end deffn @geindex gcc_jit_context_get_builtin_function (C function) -@anchor{topics/functions gcc_jit_context_get_builtin_function}@anchor{db} +@anchor{topics/functions c gcc_jit_context_get_builtin_function}@anchor{de} @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{dc} +@anchor{topics/functions c gcc_jit_function_as_object}@anchor{df} @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{dd} +@anchor{topics/functions c gcc_jit_function_get_param}@anchor{e0} @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). @end deffn @geindex gcc_jit_function_dump_to_dot (C function) -@anchor{topics/functions gcc_jit_function_dump_to_dot}@anchor{33} +@anchor{topics/functions c gcc_jit_function_dump_to_dot}@anchor{33} @deffn {C Function} void gcc_jit_function_dump_to_dot (gcc_jit_function@w{ }*func, const char@w{ }*path) Emit the function in graphviz format to the given path. @end deffn @geindex gcc_jit_function_new_local (C function) -@anchor{topics/functions gcc_jit_function_new_local}@anchor{26} +@anchor{topics/functions c gcc_jit_function_new_local}@anchor{26} @deffn {C Function} gcc_jit_lvalue * gcc_jit_function_new_local (gcc_jit_function@w{ }*func, gcc_jit_location@w{ }*loc, gcc_jit_type@w{ }*type, const char@w{ }*name) Create a new local variable within the function, of the given type and name. +The parameter @code{type} must be non-@cite{void}. + The parameter @code{name} must be non-NULL. The call takes a copy of the underlying string, so it is valid to pass in a pointer to an on-stack buffer. @end deffn @node Blocks,Statements,Functions,Creating and using functions -@anchor{topics/functions blocks}@anchor{de} +@anchor{topics/functions blocks}@anchor{e1} @subsection Blocks @geindex gcc_jit_block (C type) -@anchor{topics/functions gcc_jit_block}@anchor{28} +@anchor{topics/functions c gcc_jit_block}@anchor{28} @deffn {C Type} gcc_jit_block A @cite{gcc_jit_block} represents a basic block within a function i.e. a @@ -7679,12 +7097,12 @@ Each basic block that you create within a function must be terminated, either with a conditional, a jump, a return, or a switch. -It's legal to have multiple basic blocks that return within +It’s legal to have multiple basic blocks that return within one function. @end deffn @geindex gcc_jit_function_new_block (C function) -@anchor{topics/functions gcc_jit_function_new_block}@anchor{df} +@anchor{topics/functions c gcc_jit_function_new_block}@anchor{e2} @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 @@ -7701,47 +7119,43 @@ for (pc = 0; pc < fn->fn_num_ops; pc++) state.op_blocks[pc] = gcc_jit_function_new_block (state.fn, buf); @} @end example - -@noindent @end deffn @geindex gcc_jit_block_as_object (C function) -@anchor{topics/functions gcc_jit_block_as_object}@anchor{e0} +@anchor{topics/functions c gcc_jit_block_as_object}@anchor{e3} @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{e1} +@anchor{topics/functions c gcc_jit_block_get_function}@anchor{e4} @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{e2} +@anchor{topics/functions statements}@anchor{e5} @subsection Statements @geindex gcc_jit_block_add_eval (C function) -@anchor{topics/functions gcc_jit_block_add_eval}@anchor{b7} +@anchor{topics/functions c gcc_jit_block_add_eval}@anchor{ba} @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 -(e.g. a function call that "returns" void). +(e.g. a function call that “returns” void). This is equivalent to this C code: @example (void)expression; @end example - -@noindent @end deffn @geindex gcc_jit_block_add_assignment (C function) -@anchor{topics/functions gcc_jit_block_add_assignment}@anchor{2a} +@anchor{topics/functions c gcc_jit_block_add_assignment}@anchor{2a} @deffn {C Function} void gcc_jit_block_add_assignment (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_lvalue@w{ }*lvalue, gcc_jit_rvalue@w{ }*rvalue) Add evaluation of an rvalue, assigning the result to the given @@ -7752,18 +7166,16 @@ This is roughly equivalent to this C code: @example lvalue = rvalue; @end example - -@noindent @end deffn @geindex gcc_jit_block_add_assignment_op (C function) -@anchor{topics/functions gcc_jit_block_add_assignment_op}@anchor{2e} +@anchor{topics/functions c gcc_jit_block_add_assignment_op}@anchor{2e} @deffn {C Function} void gcc_jit_block_add_assignment_op (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_lvalue@w{ }*lvalue, enum gcc_jit_binary_op@w{ }op, gcc_jit_rvalue@w{ }*rvalue) Add evaluation of an rvalue, using the result to modify an lvalue. -This is analogous to "+=" and friends: +This is analogous to “+=” and friends: @example lvalue += rvalue; @@ -7771,8 +7183,6 @@ lvalue *= rvalue; lvalue /= rvalue; @end example -@noindent - etc. For example: @example @@ -7783,19 +7193,17 @@ gcc_jit_block_add_assignment_op ( GCC_JIT_BINARY_OP_PLUS, gcc_jit_context_one (ctxt, int_type)); @end example - -@noindent @end deffn @geindex gcc_jit_block_add_comment (C function) -@anchor{topics/functions gcc_jit_block_add_comment}@anchor{3d} +@anchor{topics/functions c gcc_jit_block_add_comment}@anchor{3d} @deffn {C Function} void gcc_jit_block_add_comment (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, const char@w{ }*text) Add a no-op textual comment to the internal representation of the code. It will be optimized away, but will be visible in the dumps -seen via @pxref{66,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE} -and @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE}, -and thus may be of use when debugging how your project's internal +seen via @ref{66,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE} +and @ref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE}, +and thus may be of use when debugging how your project’s internal representation gets converted to the libgccjit IR. The parameter @code{text} must be non-NULL. It is copied, so the input @@ -7808,12 +7216,10 @@ snprintf (buf, sizeof (buf), pc, opcode_names[op->op_opcode]); gcc_jit_block_add_comment (block, loc, buf); @end example - -@noindent @end deffn @geindex gcc_jit_block_end_with_conditional (C function) -@anchor{topics/functions gcc_jit_block_end_with_conditional}@anchor{2d} +@anchor{topics/functions c gcc_jit_block_end_with_conditional}@anchor{2d} @deffn {C Function} void gcc_jit_block_end_with_conditional (gcc_jit_block@w{ }*block, gcc_jit_location@w{ }*loc, gcc_jit_rvalue@w{ }*boolval, gcc_jit_block@w{ }*on_true, gcc_jit_block@w{ }*on_false) Terminate a block by adding evaluation of an rvalue, branching on the @@ -7828,13 +7234,11 @@ else goto on_false; @end example -@noindent - 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{e3} +@anchor{topics/functions c gcc_jit_block_end_with_jump}@anchor{e6} @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. @@ -7844,12 +7248,10 @@ This is roughly equivalent to this C code: @example goto target; @end example - -@noindent @end deffn @geindex gcc_jit_block_end_with_return (C function) -@anchor{topics/functions gcc_jit_block_end_with_return}@anchor{e4} +@anchor{topics/functions c gcc_jit_block_end_with_return}@anchor{e7} @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. @@ -7859,28 +7261,24 @@ This is roughly equivalent to this C code: @example return expression; @end example - -@noindent @end deffn @geindex gcc_jit_block_end_with_void_return (C function) -@anchor{topics/functions gcc_jit_block_end_with_void_return}@anchor{e5} +@anchor{topics/functions c gcc_jit_block_end_with_void_return}@anchor{e8} @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 -with "void" return type. +with “void” return type. This is equivalent to this C code: @example return; @end example - -@noindent @end deffn @geindex gcc_jit_block_end_with_switch (C function) -@anchor{topics/functions gcc_jit_block_end_with_switch}@anchor{e6} +@anchor{topics/functions c gcc_jit_block_end_with_switch}@anchor{e9} @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 @@ -7907,8 +7305,6 @@ switch (expr) @} @end example -@noindent - @code{block}, @code{expr}, @code{default_block} and @code{cases} must all be non-NULL. @@ -7928,40 +7324,38 @@ The API entrypoints relating to switch statements and cases: @itemize * @item -@pxref{e6,,gcc_jit_block_end_with_switch()} +@ref{e9,,gcc_jit_block_end_with_switch()} @item -@pxref{e7,,gcc_jit_case_as_object()} +@ref{ea,,gcc_jit_case_as_object()} @item -@pxref{e8,,gcc_jit_context_new_case()} +@ref{eb,,gcc_jit_context_new_case()} @end itemize @end quotation -were added in @pxref{e9,,LIBGCCJIT_ABI_3}; you can test for their presence +were added in @ref{ec,,LIBGCCJIT_ABI_3}; you can test for their presence using @example #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS @end example -@noindent - @geindex gcc_jit_case (C type) -@anchor{topics/functions gcc_jit_case}@anchor{ea} +@anchor{topics/functions c gcc_jit_case}@anchor{ed} @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{e8,,gcc_jit_context_new_case()}. +is created within a particular @ref{8,,gcc_jit_context} using +@ref{eb,,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{e8} +@anchor{topics/functions c gcc_jit_context_new_case}@anchor{eb} @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. @@ -7973,13 +7367,13 @@ statement. @end deffn @geindex gcc_jit_case_as_object (C function) -@anchor{topics/functions gcc_jit_case_as_object}@anchor{e7} +@anchor{topics/functions c gcc_jit_case_as_object}@anchor{ea} @deffn {C Function} gcc_jit_object * gcc_jit_case_as_object (gcc_jit_case@w{ }*case_) Upcast from a case to an object. @end deffn -Here's an example of creating a switch statement: +Here’s an example of creating a switch statement: @quotation @@ -8083,10 +7477,7 @@ create_code (gcc_jit_context *ctxt, void *user_data) gcc_jit_context_new_rvalue_from_int (ctxt, t_int, 10)); @} - @end example - -@noindent @end quotation @end deffn @@ -8108,41 +7499,39 @@ create_code (gcc_jit_context *ctxt, void *user_data) @c <http://www.gnu.org/licenses/>. @node Function pointers<2>,Source Locations,Creating and using functions,Topic Reference -@anchor{topics/function-pointers doc}@anchor{eb}@anchor{topics/function-pointers function-pointers}@anchor{ec} +@anchor{topics/function-pointers doc}@anchor{ee}@anchor{topics/function-pointers function-pointers}@anchor{ef} @section Function pointers You can generate calls that use a function pointer via -@pxref{b8,,gcc_jit_context_new_call_through_ptr()}. +@ref{bb,,gcc_jit_context_new_call_through_ptr()}. -To do requires a @pxref{13,,gcc_jit_rvalue} of the correct function pointer type. +To do requires a @ref{13,,gcc_jit_rvalue} of the correct function pointer type. -Function pointers for a @pxref{29,,gcc_jit_function} can be obtained -via @pxref{bc,,gcc_jit_function_get_address()}. +Function pointers for a @ref{29,,gcc_jit_function} can be obtained +via @ref{bf,,gcc_jit_function_get_address()}. @geindex gcc_jit_function_get_address (C function) -@anchor{topics/function-pointers gcc_jit_function_get_address}@anchor{bc} +@anchor{topics/function-pointers c gcc_jit_function_get_address}@anchor{bf} @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{ed,,LIBGCCJIT_ABI_9}; you can test +This entrypoint was added in @ref{f0,,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{98,,gcc_jit_context_new_rvalue_from_ptr()}, using a function pointer -type obtained using @pxref{91,,gcc_jit_context_new_function_ptr_type()}. +to it in @ref{13,,gcc_jit_rvalue} form using +@ref{9b,,gcc_jit_context_new_rvalue_from_ptr()}, using a function pointer +type obtained using @ref{94,,gcc_jit_context_new_function_ptr_type()}. -Here's an example of creating a function pointer type corresponding to C's +Here’s an example of creating a function pointer type corresponding to C’s @code{void (*) (int, int, int)}: @example @@ -8163,14 +7552,14 @@ gcc_jit_type *fn_ptr_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{91} +@anchor{topics/function-pointers c gcc_jit_context_new_function_ptr_type}@anchor{94} @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 +Generate a @ref{a,,gcc_jit_type} for a function pointer with the given return type and parameters. + +Each of @cite{param_types} must be non-@cite{void}; @cite{return_type} may be @cite{void}. @end deffn @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @@ -8191,12 +7580,12 @@ given return type and parameters. @c <http://www.gnu.org/licenses/>. @node Source Locations,Compiling a context,Function pointers<2>,Topic Reference -@anchor{topics/locations source-locations}@anchor{ee}@anchor{topics/locations doc}@anchor{ef} +@anchor{topics/locations doc}@anchor{f1}@anchor{topics/locations source-locations}@anchor{f2} @section Source Locations @geindex gcc_jit_location (C type) -@anchor{topics/locations gcc_jit_location}@anchor{3b} +@anchor{topics/locations c gcc_jit_location}@anchor{3b} @deffn {C Type} gcc_jit_location A @cite{gcc_jit_location} encapsulates a source code location, so that @@ -8207,10 +7596,10 @@ single-step through your language. @cite{gcc_jit_location} instances are optional: you can always pass NULL to any API entrypoint accepting one. -You can construct them using @pxref{41,,gcc_jit_context_new_location()}. +You can construct them using @ref{41,,gcc_jit_context_new_location()}. -You need to enable @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the -@pxref{8,,gcc_jit_context} for these locations to actually be usable by +You need to enable @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the +@ref{8,,gcc_jit_context} for these locations to actually be usable by the debugger: @example @@ -8219,12 +7608,10 @@ gcc_jit_context_set_bool_option ( GCC_JIT_BOOL_OPTION_DEBUGINFO, 1); @end example - -@noindent @end deffn @geindex gcc_jit_context_new_location (C function) -@anchor{topics/locations gcc_jit_context_new_location}@anchor{41} +@anchor{topics/locations c gcc_jit_context_new_location}@anchor{41} @deffn {C Function} gcc_jit_location * gcc_jit_context_new_location (gcc_jit_context@w{ }*ctxt, const char@w{ }*filename, int@w{ }line, int@w{ }column) Create a @cite{gcc_jit_location} instance representing the given source @@ -8241,21 +7628,19 @@ on-stack buffer. @end menu @node Faking it,,,Source Locations -@anchor{topics/locations faking-it}@anchor{f0} +@anchor{topics/locations faking-it}@anchor{f3} @subsection Faking it -If you don't have source code for your internal representation, but need +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{5a,,gcc_jit_context_dump_to_file()}: +your context using @ref{5a,,gcc_jit_context_dump_to_file()}: @example gcc_jit_context_dump_to_file (ctxt, "/tmp/something.c", 1 /* update_locations */); @end example -@noindent - This will dump C-like code to the given path. If the @cite{update_locations} argument is true, this will also set up @cite{gcc_jit_location} information throughout the context, pointing at the dump file as if it were a source @@ -8279,13 +7664,13 @@ file, giving you @emph{something} you can step through in the debugger. @c <http://www.gnu.org/licenses/>. @node Compiling a context,ABI and API compatibility,Source Locations,Topic Reference -@anchor{topics/compilation compiling-a-context}@anchor{f1}@anchor{topics/compilation doc}@anchor{f2} +@anchor{topics/compilation doc}@anchor{f4}@anchor{topics/compilation compiling-a-context}@anchor{f5} @section Compiling a context -Once populated, a @pxref{8,,gcc_jit_context *} can be compiled to -machine code, either in-memory via @pxref{15,,gcc_jit_context_compile()} or -to disk via @pxref{4a,,gcc_jit_context_compile_to_file()}. +Once populated, a @ref{8,,gcc_jit_context *} can be compiled to +machine code, either in-memory via @ref{15,,gcc_jit_context_compile()} or +to disk via @ref{4a,,gcc_jit_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 @@ -8298,24 +7683,24 @@ 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{f3} +@anchor{topics/compilation in-memory-compilation}@anchor{f6} @subsection In-memory compilation @geindex gcc_jit_context_compile (C function) -@anchor{topics/compilation gcc_jit_context_compile}@anchor{15} +@anchor{topics/compilation c gcc_jit_context_compile}@anchor{15} @deffn {C Function} gcc_jit_result * gcc_jit_context_compile (gcc_jit_context@w{ }*ctxt) This calls into GCC and builds the code, returning a @cite{gcc_jit_result *}. If the result is non-NULL, the caller becomes responsible for -calling @pxref{39,,gcc_jit_result_release()} on it once they're done +calling @ref{39,,gcc_jit_result_release()} on it once they’re done with it. @end deffn @geindex gcc_jit_result (C type) -@anchor{topics/compilation gcc_jit_result}@anchor{16} +@anchor{topics/compilation c gcc_jit_result}@anchor{16} @deffn {C Type} gcc_jit_result A @cite{gcc_jit_result} encapsulates the result of compiling a context @@ -8324,16 +7709,16 @@ that are within the result. @end deffn @geindex gcc_jit_result_get_code (C function) -@anchor{topics/compilation gcc_jit_result_get_code}@anchor{17} +@anchor{topics/compilation c gcc_jit_result_get_code}@anchor{17} @deffn {C Function} void * gcc_jit_result_get_code (gcc_jit_result@w{ }*result, const char@w{ }*funcname) Locate a given function within the built machine code. 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{d7,,GCC_JIT_FUNCTION_EXPORTED}: +@cite{result}’s context (or a parent context) via a call to +@ref{11,,gcc_jit_context_new_function()} with @cite{kind} +@ref{da,,GCC_JIT_FUNCTION_EXPORTED}: @example gcc_jit_context_new_function (ctxt, @@ -8347,8 +7732,6 @@ gcc_jit_context_new_function (ctxt, /* etc */); @end example -@noindent - If such a function is not found (or @cite{result} or @cite{funcname} are @code{NULL}), an error message will be emitted on stderr and @code{NULL} will be returned. @@ -8357,22 +7740,22 @@ If the function is found, the result will need to be cast to a function pointer of the correct type before it can be called. Note that the resulting machine code becomes invalid after -@pxref{39,,gcc_jit_result_release()} is called on the -@pxref{16,,gcc_jit_result *}; attempting to call it after that may lead +@ref{39,,gcc_jit_result_release()} is called on the +@ref{16,,gcc_jit_result *}; attempting to call it after that may lead to a segmentation fault. @end deffn @geindex gcc_jit_result_get_global (C function) -@anchor{topics/compilation gcc_jit_result_get_global}@anchor{c7} +@anchor{topics/compilation c gcc_jit_result_get_global}@anchor{ca} @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. 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{c4,,gcc_jit_context_new_global()} with @cite{kind} -@pxref{c6,,GCC_JIT_GLOBAL_EXPORTED}. +@cite{result}’s context (or a parent context) via a call to +@ref{c7,,gcc_jit_context_new_global()} with @cite{kind} +@ref{c9,,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. @@ -8391,8 +7774,6 @@ gcc_jit_lvalue *exported_global = "foo"); @end example -@noindent - we can access it like this: @example @@ -8400,48 +7781,46 @@ int *ptr_to_foo = (int *)gcc_jit_result_get_global (result, "foo"); @end example -@noindent - If such a global is not found (or @cite{result} or @cite{name} are @code{NULL}), an error message will be emitted on stderr and @code{NULL} will be returned. Note that the resulting address becomes invalid after -@pxref{39,,gcc_jit_result_release()} is called on the -@pxref{16,,gcc_jit_result *}; attempting to use it after that may lead +@ref{39,,gcc_jit_result_release()} is called on the +@ref{16,,gcc_jit_result *}; attempting to use it after that may lead to a segmentation fault. @end deffn @geindex gcc_jit_result_release (C function) -@anchor{topics/compilation gcc_jit_result_release}@anchor{39} +@anchor{topics/compilation c gcc_jit_result_release}@anchor{39} @deffn {C Function} void gcc_jit_result_release (gcc_jit_result@w{ }*result) -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 +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{c7,,gcc_jit_result_get_global()} on it. +by calling @ref{17,,gcc_jit_result_get_code()} or +@ref{ca,,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{f4} +@anchor{topics/compilation ahead-of-time-compilation}@anchor{f7} @subsection 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{4a,,gcc_jit_context_compile_to_file()} +compilers, via the @ref{4a,,gcc_jit_context_compile_to_file()} API entrypoint. @geindex gcc_jit_context_compile_to_file (C function) -@anchor{topics/compilation gcc_jit_context_compile_to_file}@anchor{4a} +@anchor{topics/compilation c gcc_jit_context_compile_to_file}@anchor{4a} @deffn {C Function} void gcc_jit_context_compile_to_file (gcc_jit_context@w{ }*ctxt, enum gcc_jit_output_kind@w{ }output_kind, const char@w{ }*output_path) -Compile the @pxref{8,,gcc_jit_context *} to a file of the given +Compile the @ref{8,,gcc_jit_context *} to a file of the given kind. @end deffn -@pxref{4a,,gcc_jit_context_compile_to_file()} ignores the suffix of +@ref{4a,,gcc_jit_context_compile_to_file()} ignores the suffix of @code{output_path}, and insteads uses the given @code{enum gcc_jit_output_kind} to decide what to do. @@ -8453,7 +7832,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{f5} +@anchor{topics/compilation c gcc_jit_output_kind}@anchor{f8} @deffn {C Type} enum gcc_jit_output_kind @end deffn @@ -8471,7 +7850,7 @@ Typical suffix @item -@pxref{f6,,GCC_JIT_OUTPUT_KIND_ASSEMBLER} +@ref{f9,,GCC_JIT_OUTPUT_KIND_ASSEMBLER} @tab @@ -8479,7 +7858,7 @@ Typical suffix @item -@pxref{f7,,GCC_JIT_OUTPUT_KIND_OBJECT_FILE} +@ref{fa,,GCC_JIT_OUTPUT_KIND_OBJECT_FILE} @tab @@ -8487,7 +7866,7 @@ Typical suffix @item -@pxref{f8,,GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY} +@ref{fb,,GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY} @tab @@ -8495,7 +7874,7 @@ Typical suffix @item -@pxref{f9,,GCC_JIT_OUTPUT_KIND_EXECUTABLE} +@ref{fc,,GCC_JIT_OUTPUT_KIND_EXECUTABLE} @tab @@ -8505,21 +7884,21 @@ None, or .exe @geindex GCC_JIT_OUTPUT_KIND_ASSEMBLER (C macro) -@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_ASSEMBLER}@anchor{f6} +@anchor{topics/compilation c GCC_JIT_OUTPUT_KIND_ASSEMBLER}@anchor{f9} @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{f7} +@anchor{topics/compilation c GCC_JIT_OUTPUT_KIND_OBJECT_FILE}@anchor{fa} @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{f8} +@anchor{topics/compilation c GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY}@anchor{fb} @deffn {C Macro} GCC_JIT_OUTPUT_KIND_DYNAMIC_LIBRARY Compile the context to a dynamic library. @@ -8529,7 +7908,7 @@ against. @end deffn @geindex GCC_JIT_OUTPUT_KIND_EXECUTABLE (C macro) -@anchor{topics/compilation GCC_JIT_OUTPUT_KIND_EXECUTABLE}@anchor{f9} +@anchor{topics/compilation c GCC_JIT_OUTPUT_KIND_EXECUTABLE}@anchor{fc} @deffn {C Macro} GCC_JIT_OUTPUT_KIND_EXECUTABLE Compile the context to an executable. @@ -8556,7 +7935,7 @@ against. @c <http://www.gnu.org/licenses/>. @node ABI and API compatibility,Performance,Compiling a context,Topic Reference -@anchor{topics/compatibility abi-and-api-compatibility}@anchor{fa}@anchor{topics/compatibility doc}@anchor{fb} +@anchor{topics/compatibility doc}@anchor{fd}@anchor{topics/compatibility abi-and-api-compatibility}@anchor{fe} @section ABI and API compatibility @@ -8578,7 +7957,7 @@ it. For ABI compatiblity, we avoid bumping the SONAME, and instead use symbol versioning to tag each symbol, so that a binary linked against libgccjit.so is tagged according to the symbols that it uses. -For example, @pxref{72,,gcc_jit_context_add_command_line_option()} was added in +For example, @ref{72,,gcc_jit_context_add_command_line_option()} was added in @code{LIBGCCJIT_ABI_1}. If a client program uses it, this can be detected from metadata by using @code{objdump}: @@ -8592,8 +7971,6 @@ Version References: required from libc.so.6: @end example -@noindent - You can see the symbol tags provided by libgccjit.so using @code{objdump}: @example @@ -8607,30 +7984,51 @@ Version definitions: [...snip...] @end example -@noindent - @menu +* Programmatically checking version:: * ABI symbol tags:: -ABI symbol tags +@end menu -* LIBGCCJIT_ABI_0:: -* LIBGCCJIT_ABI_1:: -* LIBGCCJIT_ABI_2:: -* LIBGCCJIT_ABI_3:: -* LIBGCCJIT_ABI_4:: -* LIBGCCJIT_ABI_5:: -* LIBGCCJIT_ABI_6:: -* LIBGCCJIT_ABI_7:: -* LIBGCCJIT_ABI_8:: -* LIBGCCJIT_ABI_9:: -* LIBGCCJIT_ABI_10:: +@node Programmatically checking version,ABI symbol tags,,ABI and API compatibility +@anchor{topics/compatibility programmatically-checking-version}@anchor{ff} +@subsection Programmatically checking version -@end menu +Client code can programmatically check libgccjit version using: + +@geindex gcc_jit_version_major (C function) +@anchor{topics/compatibility c gcc_jit_version_major}@anchor{100} +@deffn {C Function} int gcc_jit_version_major (void) + +Return libgccjit major version. This is analogous to __GNUC__ in C code. +@end deffn + +@geindex gcc_jit_version_minor (C function) +@anchor{topics/compatibility c gcc_jit_version_minor}@anchor{101} +@deffn {C Function} int gcc_jit_version_minor (void) + +Return libgccjit minor version. This is analogous to +__GNUC_MINOR__ in C code. +@end deffn + +@geindex gcc_jit_version_patchlevel (C function) +@anchor{topics/compatibility c gcc_jit_version_patchlevel}@anchor{102} +@deffn {C Function} int gcc_jit_version_patchlevel (void) + +Return libgccjit patchlevel version. This is analogous to +__GNUC_PATCHLEVEL__ in C code. +@end deffn -@node ABI symbol tags,,,ABI and API compatibility -@anchor{topics/compatibility abi-symbol-tags}@anchor{fc} +@cartouche +@quotation Note +These entry points has been added with @code{LIBGCCJIT_ABI_13} +(see below). +@end quotation +@end cartouche + +@node ABI symbol tags,,Programmatically checking version,ABI and API compatibility +@anchor{topics/compatibility abi-symbol-tags}@anchor{103} @subsection ABI symbol tags @@ -8650,11 +8048,14 @@ Newer releases use the following tags. * LIBGCCJIT_ABI_8:: * LIBGCCJIT_ABI_9:: * LIBGCCJIT_ABI_10:: +* LIBGCCJIT_ABI_11:: +* LIBGCCJIT_ABI_12:: +* LIBGCCJIT_ABI_13:: @end menu @node LIBGCCJIT_ABI_0,LIBGCCJIT_ABI_1,,ABI symbol tags -@anchor{topics/compatibility libgccjit-abi-0}@anchor{fd}@anchor{topics/compatibility id1}@anchor{fe} +@anchor{topics/compatibility id1}@anchor{104}@anchor{topics/compatibility libgccjit-abi-0}@anchor{105} @subsubsection @code{LIBGCCJIT_ABI_0} @@ -8666,23 +8067,23 @@ 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{ff} +@anchor{topics/compatibility id2}@anchor{106}@anchor{topics/compatibility libgccjit-abi-1}@anchor{73} @subsubsection @code{LIBGCCJIT_ABI_1} @code{LIBGCCJIT_ABI_1} covers the addition of -@pxref{72,,gcc_jit_context_add_command_line_option()} +@ref{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{100} +@anchor{topics/compatibility id3}@anchor{107}@anchor{topics/compatibility libgccjit-abi-2}@anchor{6c} @subsubsection @code{LIBGCCJIT_ABI_2} @code{LIBGCCJIT_ABI_2} covers the addition of -@pxref{6b,,gcc_jit_context_set_bool_allow_unreachable_blocks()} +@ref{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{e9}@anchor{topics/compatibility id4}@anchor{101} +@anchor{topics/compatibility id4}@anchor{108}@anchor{topics/compatibility libgccjit-abi-3}@anchor{ec} @subsubsection @code{LIBGCCJIT_ABI_3} @@ -8695,18 +8096,18 @@ entrypoints: @itemize * @item -@pxref{e6,,gcc_jit_block_end_with_switch()} +@ref{e9,,gcc_jit_block_end_with_switch()} @item -@pxref{e7,,gcc_jit_case_as_object()} +@ref{ea,,gcc_jit_case_as_object()} @item -@pxref{e8,,gcc_jit_context_new_case()} +@ref{eb,,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{102}@anchor{topics/compatibility libgccjit-abi-4}@anchor{103} +@anchor{topics/compatibility id5}@anchor{109}@anchor{topics/compatibility libgccjit-abi-4}@anchor{10a} @subsubsection @code{LIBGCCJIT_ABI_4} @@ -8719,75 +8120,115 @@ entrypoints: @itemize * @item -@pxref{104,,gcc_jit_context_get_timer()} +@ref{10b,,gcc_jit_context_get_timer()} @item -@pxref{105,,gcc_jit_context_set_timer()} +@ref{10c,,gcc_jit_context_set_timer()} @item -@pxref{106,,gcc_jit_timer_new()} +@ref{10d,,gcc_jit_timer_new()} @item -@pxref{107,,gcc_jit_timer_release()} +@ref{10e,,gcc_jit_timer_release()} @item -@pxref{108,,gcc_jit_timer_push()} +@ref{10f,,gcc_jit_timer_push()} @item -@pxref{109,,gcc_jit_timer_pop()} +@ref{110,,gcc_jit_timer_pop()} @item -@pxref{10a,,gcc_jit_timer_print()} +@ref{111,,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{10b}@anchor{topics/compatibility libgccjit-abi-5}@anchor{6e} +@anchor{topics/compatibility id6}@anchor{112}@anchor{topics/compatibility libgccjit-abi-5}@anchor{6e} @subsubsection @code{LIBGCCJIT_ABI_5} @code{LIBGCCJIT_ABI_5} covers the addition of -@pxref{6d,,gcc_jit_context_set_bool_use_external_driver()} +@ref{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{10c}@anchor{topics/compatibility libgccjit-abi-6}@anchor{ba} +@anchor{topics/compatibility id7}@anchor{113}@anchor{topics/compatibility libgccjit-abi-6}@anchor{bd} @subsubsection @code{LIBGCCJIT_ABI_6} @code{LIBGCCJIT_ABI_6} covers the addition of -@pxref{b9,,gcc_jit_rvalue_set_bool_require_tail_call()} +@ref{bc,,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{10d} +@anchor{topics/compatibility id8}@anchor{114}@anchor{topics/compatibility libgccjit-abi-7}@anchor{83} @subsubsection @code{LIBGCCJIT_ABI_7} @code{LIBGCCJIT_ABI_7} covers the addition of -@pxref{80,,gcc_jit_type_get_aligned()} +@ref{82,,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{10e} +@anchor{topics/compatibility id9}@anchor{115}@anchor{topics/compatibility libgccjit-abi-8}@anchor{86} @subsubsection @code{LIBGCCJIT_ABI_8} @code{LIBGCCJIT_ABI_8} covers the addition of -@pxref{83,,gcc_jit_type_get_vector()} +@ref{85,,gcc_jit_type_get_vector()} @node LIBGCCJIT_ABI_9,LIBGCCJIT_ABI_10,LIBGCCJIT_ABI_8,ABI symbol tags -@anchor{topics/compatibility id10}@anchor{10f}@anchor{topics/compatibility libgccjit-abi-9}@anchor{ed} +@anchor{topics/compatibility id10}@anchor{116}@anchor{topics/compatibility libgccjit-abi-9}@anchor{f0} @subsubsection @code{LIBGCCJIT_ABI_9} @code{LIBGCCJIT_ABI_9} covers the addition of -@pxref{bc,,gcc_jit_function_get_address()} +@ref{bf,,gcc_jit_function_get_address()} -@node LIBGCCJIT_ABI_10,,LIBGCCJIT_ABI_9,ABI symbol tags -@anchor{topics/compatibility id11}@anchor{110}@anchor{topics/compatibility libgccjit-abi-10}@anchor{9c} +@node LIBGCCJIT_ABI_10,LIBGCCJIT_ABI_11,LIBGCCJIT_ABI_9,ABI symbol tags +@anchor{topics/compatibility id11}@anchor{117}@anchor{topics/compatibility libgccjit-abi-10}@anchor{9f} @subsubsection @code{LIBGCCJIT_ABI_10} @code{LIBGCCJIT_ABI_10} covers the addition of -@pxref{85,,gcc_jit_context_new_rvalue_from_vector()} +@ref{87,,gcc_jit_context_new_rvalue_from_vector()} + +@node LIBGCCJIT_ABI_11,LIBGCCJIT_ABI_12,LIBGCCJIT_ABI_10,ABI symbol tags +@anchor{topics/compatibility id12}@anchor{118}@anchor{topics/compatibility libgccjit-abi-11}@anchor{75} +@subsubsection @code{LIBGCCJIT_ABI_11} + + +@code{LIBGCCJIT_ABI_11} covers the addition of +@ref{74,,gcc_jit_context_add_driver_option()} + +@node LIBGCCJIT_ABI_12,LIBGCCJIT_ABI_13,LIBGCCJIT_ABI_11,ABI symbol tags +@anchor{topics/compatibility libgccjit-abi-12}@anchor{119} +@subsubsection @code{LIBGCCJIT_ABI_12} + + +@code{LIBGCCJIT_ABI_12} covers the addition of +@ref{8c,,gcc_jit_context_new_bitfield()} + +@node LIBGCCJIT_ABI_13,,LIBGCCJIT_ABI_12,ABI symbol tags +@anchor{topics/compatibility libgccjit-abi-13}@anchor{11a} +@subsubsection @code{LIBGCCJIT_ABI_13} + + +@code{LIBGCCJIT_ABI_13} covers the addition of version functions via API +entrypoints: + +@quotation + + +@itemize * + +@item +@ref{100,,gcc_jit_version_major()} + +@item +@ref{101,,gcc_jit_version_minor()} + +@item +@ref{102,,gcc_jit_version_patchlevel()} +@end itemize +@end quotation @c Copyright (C) 2015-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @@ -8807,7 +8248,7 @@ entrypoints: @c <http://www.gnu.org/licenses/>. @node Performance,,ABI and API compatibility,Topic Reference -@anchor{topics/performance performance}@anchor{111}@anchor{topics/performance doc}@anchor{112} +@anchor{topics/performance doc}@anchor{11b}@anchor{topics/performance performance}@anchor{11c} @section Performance @@ -8817,24 +8258,24 @@ entrypoints: @end menu @node The timing API,,,Performance -@anchor{topics/performance the-timing-api}@anchor{113} +@anchor{topics/performance the-timing-api}@anchor{11d} @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{114,,gcc_jit_timer} instance, which will +You can create a @ref{11e,,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 +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 will account the time spent accordingly. -You can also asssociate a timer with a @pxref{8,,gcc_jit_context}, in +You can also asssociate a timer with a @ref{8,,gcc_jit_context}, in which case the time spent inside compilation will be subdivided. For example, the following code uses a timer, recording client items -"create_code", "compile", and "running code": +“create_code”, “compile”, and “running code”: @example /* Create a timer. */ @@ -8883,8 +8324,6 @@ gcc_jit_timer_print (timer, stderr); gcc_jit_timer_release (timer); @end example -@noindent - giving output like this, showing the internal GCC items at the top, then client items, then the total: @@ -8921,12 +8360,10 @@ Client items: TOTAL : 2.00 0.18 6.12 21444 kB @end example -@noindent - 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{115} +@anchor{topics/performance c LIBGCCJIT_HAVE_TIMING_API}@anchor{11f} @deffn {C Macro} LIBGCCJIT_HAVE_TIMING_API The timer API was added to libgccjit in GCC 6. @@ -8940,111 +8377,95 @@ gcc_jit_timer *t = gcc_jit_timer_new (); gcc_jit_context_set_timer (ctxt, t); #endif @end example - -@noindent @end deffn @geindex gcc_jit_timer (C type) -@anchor{topics/performance gcc_jit_timer}@anchor{114} +@anchor{topics/performance c gcc_jit_timer}@anchor{11e} @deffn {C Type} gcc_jit_timer @end deffn @geindex gcc_jit_timer_new (C function) -@anchor{topics/performance gcc_jit_timer_new}@anchor{106} +@anchor{topics/performance c gcc_jit_timer_new}@anchor{10d} @deffn {C Function} gcc_jit_timer * gcc_jit_timer_new (void) -Create a @pxref{114,,gcc_jit_timer} instance, and start timing: +Create a @ref{11e,,gcc_jit_timer} instance, and start timing: @example gcc_jit_timer *t = gcc_jit_timer_new (); @end example -@noindent - -This API entrypoint was added in @pxref{103,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @ref{10a,,LIBGCCJIT_ABI_4}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_TIMING_API @end example - -@noindent @end deffn @geindex gcc_jit_timer_release (C function) -@anchor{topics/performance gcc_jit_timer_release}@anchor{107} +@anchor{topics/performance c gcc_jit_timer_release}@anchor{10e} @deffn {C Function} void gcc_jit_timer_release (gcc_jit_timer@w{ }*timer) -Release a @pxref{114,,gcc_jit_timer} instance: +Release a @ref{11e,,gcc_jit_timer} instance: @example gcc_jit_timer_release (t); @end example -@noindent - This should be called exactly once on a timer. -This API entrypoint was added in @pxref{103,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @ref{10a,,LIBGCCJIT_ABI_4}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_TIMING_API @end example - -@noindent @end deffn @geindex gcc_jit_context_set_timer (C function) -@anchor{topics/performance gcc_jit_context_set_timer}@anchor{105} +@anchor{topics/performance c gcc_jit_context_set_timer}@anchor{10c} @deffn {C Function} void gcc_jit_context_set_timer (gcc_jit_context@w{ }*ctxt, gcc_jit_timer@w{ }*timer) -Associate a @pxref{114,,gcc_jit_timer} instance with a context: +Associate a @ref{11e,,gcc_jit_timer} instance with a context: @example gcc_jit_context_set_timer (ctxt, t); @end example -@noindent - A timer instance can be shared between multiple -@pxref{8,,gcc_jit_context} instances. +@ref{8,,gcc_jit_context} instances. 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{103,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @ref{10a,,LIBGCCJIT_ABI_4}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_TIMING_API @end example - -@noindent @end deffn @geindex gcc_jit_context_get_timer (C function) -@anchor{topics/performance gcc_jit_context_get_timer}@anchor{104} +@anchor{topics/performance c gcc_jit_context_get_timer}@anchor{10b} @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{103,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @ref{10a,,LIBGCCJIT_ABI_4}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_TIMING_API @end example - -@noindent @end deffn @geindex gcc_jit_timer_push (C function) -@anchor{topics/performance gcc_jit_timer_push}@anchor{108} +@anchor{topics/performance c gcc_jit_timer_push}@anchor{10f} @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: +Push the given item onto the timer’s stack: @example gcc_jit_timer_push (t, "running code"); @@ -9052,52 +8473,44 @@ run_the_code (ctxt, result); gcc_jit_timer_pop (t, "running code"); @end example -@noindent - -This API entrypoint was added in @pxref{103,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @ref{10a,,LIBGCCJIT_ABI_4}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_TIMING_API @end example - -@noindent @end deffn @geindex gcc_jit_timer_pop (C function) -@anchor{topics/performance gcc_jit_timer_pop}@anchor{109} +@anchor{topics/performance c gcc_jit_timer_pop}@anchor{110} @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. +Pop the top item from the timer’s stack. -If "item_name" is provided, it must match that of the top item. +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{103,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @ref{10a,,LIBGCCJIT_ABI_4}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_TIMING_API @end example - -@noindent @end deffn @geindex gcc_jit_timer_print (C function) -@anchor{topics/performance gcc_jit_timer_print}@anchor{10a} +@anchor{topics/performance c gcc_jit_timer_print}@anchor{111} @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{103,,LIBGCCJIT_ABI_4}; you can test +This API entrypoint was added in @ref{10a,,LIBGCCJIT_ABI_4}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_TIMING_API @end example - -@noindent @end deffn @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @@ -9118,7 +8531,7 @@ for its presence using @c <http://www.gnu.org/licenses/>. @node C++ bindings for libgccjit,Internals,Topic Reference,Top -@anchor{cp/index c-bindings-for-libgccjit}@anchor{116}@anchor{cp/index doc}@anchor{117} +@anchor{cp/index doc}@anchor{120}@anchor{cp/index c-bindings-for-libgccjit}@anchor{121} @chapter C++ bindings for libgccjit @@ -9128,12 +8541,12 @@ inside programs and libraries. The C++ bindings consist of a single header file @code{libgccjit++.h}. -This is a collection of "thin" wrapper classes around the C API. +This is a collection of “thin” wrapper classes around the C API. Everything is an inline function, implemented in terms of the C API, so there is nothing extra to link against. -Note that libgccjit is currently of "Alpha" quality; -the APIs are not yet set in stone, and they shouldn't be used in +Note that libgccjit is currently of “Alpha” quality; +the APIs are not yet set in stone, and they shouldn’t be used in production yet. Contents: @@ -9159,117 +8572,10 @@ Contents: * Tutorial: Tutorial<2>. * Topic Reference: Topic Reference<2>. -Tutorial - -* Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>. -* Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>. -* Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>. -* Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>. - -Tutorial part 2: Creating a trivial machine code function - -* Options: Options<3>. -* Full example: Full example<3>. - -Tutorial part 3: Loops and variables - -* Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>. -* Control flow: Control flow<2>. -* Visualizing the control flow graph: Visualizing the control flow graph<2>. -* Full example: Full example<4>. - -Tutorial part 4: Adding JIT-compilation to a toy interpreter - -* Our toy interpreter: Our toy interpreter<2>. -* Compiling to machine code: Compiling to machine code<2>. -* Setting things up: Setting things up<2>. -* Populating the function: Populating the function<2>. -* Verifying the control flow graph: Verifying the control flow graph<2>. -* Compiling the context: Compiling the context<2>. -* Single-stepping through the generated code: Single-stepping through the generated code<2>. -* Examining the generated code: Examining the generated code<2>. -* Putting it all together: Putting it all together<2>. -* Behind the curtain; How does our code get optimized?: Behind the curtain How does our code get optimized?<2>. - -Behind the curtain: How does our code get optimized? - -* Optimizing away stack manipulation: Optimizing away stack manipulation<2>. -* Elimination of tail recursion: Elimination of tail recursion<2>. - -Topic Reference - -* Compilation contexts: Compilation contexts<2>. -* Objects: Objects<2>. -* Types: Types<2>. -* Expressions: Expressions<2>. -* Creating and using functions: Creating and using functions<2>. -* Source Locations: Source Locations<2>. -* Compiling a context: Compiling a context<2>. - -Compilation contexts - -* Lifetime-management: Lifetime-management<2>. -* Thread-safety: Thread-safety<2>. -* Error-handling: Error-handling<3>. -* Debugging: Debugging<2>. -* Options: Options<4>. - -Options - -* String Options: String Options<2>. -* Boolean options: Boolean options<2>. -* Integer options: Integer options<2>. -* Additional command-line options: Additional command-line options<2>. - -Types - -* Standard types: Standard types<2>. -* Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>. -* Vector types: Vector types<2>. -* Structures and unions: Structures and unions<2>. - -Expressions - -* Rvalues: Rvalues<2>. -* Lvalues: Lvalues<2>. -* Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>. - -Rvalues - -* Simple expressions: Simple expressions<2>. -* Vector expressions: Vector expressions<2>. -* Unary Operations: Unary Operations<2>. -* Binary Operations: Binary Operations<2>. -* Comparisons: Comparisons<2>. -* Function calls: Function calls<2>. -* Function pointers: Function pointers<3>. -* Type-coercion: Type-coercion<2>. - -Lvalues - -* Global variables: Global variables<2>. - -Creating and using functions - -* Params: Params<2>. -* Functions: Functions<2>. -* Blocks: Blocks<2>. -* Statements: Statements<2>. - -Source Locations - -* Faking it: Faking it<2>. - -Compiling a context - -* In-memory compilation: In-memory compilation<2>. -* Ahead-of-time compilation: Ahead-of-time compilation<2>. - @end menu - @node Tutorial<2>,Topic Reference<2>,,C++ bindings for libgccjit -@anchor{cp/intro/index doc}@anchor{118}@anchor{cp/intro/index tutorial}@anchor{119} +@anchor{cp/intro/index doc}@anchor{122}@anchor{cp/intro/index tutorial}@anchor{123} @section Tutorial @@ -9291,25 +8597,25 @@ Compiling a context @c <http://www.gnu.org/licenses/>. @menu -* Tutorial part 1; "Hello world": Tutorial part 1 "Hello world"<2>. +* Tutorial part 1; “Hello world”: Tutorial part 1 “Hello world”<2>. * Tutorial part 2; Creating a trivial machine code function: Tutorial part 2 Creating a trivial machine code function<2>. * Tutorial part 3; Loops and variables: Tutorial part 3 Loops and variables<2>. * Tutorial part 4; Adding JIT-compilation to a toy interpreter: Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>. @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{11a}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{11b} -@subsection Tutorial part 1: "Hello world" +@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{124}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{125} +@subsection Tutorial part 1: “Hello world” -Before we look at the details of the API, let's look at building and +Before we look at the details of the API, let’s look at building and running programs that use the library. -Here's a toy "hello world" program that uses the library's C++ API to +Here’s a toy “hello world” program that uses the library’s C++ API to synthesize a call to @cite{printf} and uses it to write a message to stdout. -Don't worry about the content of the program for now; we'll cover +Don’t worry about the content of the program for now; we’ll cover the details in later parts of this tutorial. @quotation @@ -9422,10 +8728,7 @@ main (int argc, char **argv) gcc_jit_result_release (result); return 0; @} - @end example - -@noindent @end quotation Copy the above to @cite{tut01-hello-world.cc}. @@ -9440,8 +8743,6 @@ $ gcc \ -lgccjit @end example -@noindent - You should then be able to run the built program: @example @@ -9449,8 +8750,6 @@ $ ./tut01-hello-world hello world @end example -@noindent - @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @c @@ -9468,8 +8767,8 @@ hello world @c along with this program. If not, see @c <http://www.gnu.org/licenses/>. -@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{11c}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{11d} +@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{126}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{127} @subsection Tutorial part 2: Creating a trivial machine code function @@ -9482,9 +8781,7 @@ int square (int i) @} @end example -@noindent - -How can we construct this at run-time using libgccjit's C++ API? +How can we construct this at run-time using libgccjit’s C++ API? First we need to include the relevant header: @@ -9492,47 +8789,39 @@ First we need to include the relevant header: #include <libgccjit++.h> @end example -@noindent - 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 *}. +@ref{128,,gccjit;;context}, which is a thin C++ wrapper around the C API’s +@ref{8,,gcc_jit_context *}. -Create one using @pxref{11e,,gccjit;;context;;acquire()}: +Create one using @ref{129,,gccjit;;context;;acquire()}: @example gccjit::context ctxt; ctxt = gccjit::context::acquire (); @end example -@noindent - 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{11f,,gccjit;;context;;get_type()}: +all of the expressions are of the C @cite{int} type, so let’s obtain this from +the context, as a @ref{12a,,gccjit;;type}, using +@ref{12b,,gccjit;;context;;get_type()}: @example gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT); @end example -@noindent +@ref{12a,,gccjit;;type} is an example of a “contextual” object: every +entity in the API is associated with a @ref{128,,gccjit;;context}. -@code{gccjit::type} is an example of a "contextual" object: every -entity in the API is associated with a @code{gccjit::context}. - -Memory management is easy: all such "contextual" objects are automatically +Memory management is easy: all such “contextual” objects are automatically cleaned up for you when the context is released, using -@pxref{120,,gccjit;;context;;release()}: +@ref{12c,,gccjit;;context;;release()}: @example ctxt.release (); @end example -@noindent - -so you don't need to manually track and cleanup all objects, just the +so you don’t need to manually track and cleanup all objects, just the contexts. All of the C++ classes in the API are thin wrappers around pointers to @@ -9553,38 +8842,30 @@ The C++ class hierarchy within the @code{gccjit} namespace looks like this: +- param @end example -@noindent - -One thing you can do with a @code{gccjit::object} is +One thing you can do with a @ref{12d,,gccjit;;object} is to ask it for a human-readable description as a @code{std::string}, using -@pxref{121,,gccjit;;object;;get_debug_string()}: +@ref{12e,,gccjit;;object;;get_debug_string()}: @example printf ("obj: %s\n", obj.get_debug_string ().c_str ()); @end example -@noindent - giving this text on stdout: @example obj: int @end example -@noindent - This is invaluable when debugging. -Let's create the function. To do so, we first need to construct +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{122,,gccjit;;context;;new_param()}: +using @ref{12f,,gccjit;;context;;new_param()}: @example gccjit::param param_i = ctxt.new_param (int_type, "i"); @end example -@noindent - and we can then make a vector of all of the params of the function, in this case just one: @@ -9593,8 +8874,6 @@ std::vector<gccjit::param> params; params.push_back (param_i); @end example -@noindent - Now we can create the function, using @code{gccjit::context::new_function()}: @@ -9607,8 +8886,6 @@ gccjit::function func = 0); @end example -@noindent - To define the code within the function, we must create basic blocks containing statements. @@ -9621,12 +8898,10 @@ Our function has no control-flow, so we just need one basic block: gccjit::block block = func.new_block (); @end example -@noindent - Our basic block is relatively simple: it immediately terminates by returning the value of an expression. -We can build the expression using @pxref{123,,gccjit;;context;;new_binary_op()}: +We can build the expression using @ref{130,,gccjit;;context;;new_binary_op()}: @example gccjit::rvalue expr = @@ -9635,27 +8910,21 @@ gccjit::rvalue expr = param_i, param_i); @end example -@noindent - -A @code{gccjit::rvalue} is another example of a -@code{gccjit::object} subclass. As before, we can print it with -@pxref{121,,gccjit;;object;;get_debug_string()}. +A @ref{131,,gccjit;;rvalue} is another example of a +@ref{12d,,gccjit;;object} subclass. As before, we can print it with +@ref{12e,,gccjit;;object;;get_debug_string()}. @example printf ("expr: %s\n", expr.get_debug_string ().c_str ()); @end example -@noindent - giving this output: @example expr: i * i @end example -@noindent - -Note that @code{gccjit::rvalue} provides numerous overloaded operators +Note that @ref{131,,gccjit;;rvalue} provides numerous overloaded operators which can be used to dramatically reduce the amount of typing needed. We can build the above binary operation more directly with this one-liner: @@ -9663,9 +8932,7 @@ We can build the above binary operation more directly with this one-liner: gccjit::rvalue expr = param_i * param_i; @end example -@noindent - -Creating the expression in itself doesn't do anything; we have to add +Creating the expression in itself doesn’t do anything; we have to add this expression to a statement within the block. In this case, we use it to build a return statement, which terminates the basic block: @@ -9673,21 +8940,17 @@ to build a return statement, which terminates the basic block: block.end_with_return (expr); @end example -@noindent - -OK, we've populated the context. We can now compile it using -@pxref{124,,gccjit;;context;;compile()}: +OK, we’ve populated the context. We can now compile it using +@ref{132,,gccjit;;context;;compile()}: @example gcc_jit_result *result; result = ctxt.compile (); @end example -@noindent +and get a @ref{16,,gcc_jit_result *}. -and get a @pxref{16,,gcc_jit_result *}. - -We can now use @pxref{17,,gcc_jit_result_get_code()} to look up a specific +We can now use @ref{17,,gcc_jit_result_get_code()} to look up a specific machine code routine within the result, in this case, the function we created above. @@ -9700,8 +8963,6 @@ if (!fn_ptr) @} @end example -@noindent - We can now cast the pointer to an appropriate function pointer type, and then call it: @@ -9711,14 +8972,10 @@ fn_type square = (fn_type)fn_ptr; printf ("result: %d", square (5)); @end example -@noindent - @example result: 25 @end example -@noindent - @menu * Options: Options<3>. * Full example: Full example<3>. @@ -9726,19 +8983,19 @@ 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{125} +@anchor{cp/intro/tutorial02 options}@anchor{133} @subsubsection Options -To get more information on what's going on, you can set debugging flags -on the context using @pxref{126,,gccjit;;context;;set_bool_option()}. +To get more information on what’s going on, you can set debugging flags +on the context using @ref{134,,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 @c it's probably more of use to implementors than to users) -Setting @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a -C-like representation to stderr when you compile (GCC's "GIMPLE" +Setting @ref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE} will dump a +C-like representation to stderr when you compile (GCC’s “GIMPLE” representation): @example @@ -9746,8 +9003,6 @@ ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1); result = ctxt.compile (); @end example -@noindent - @example square (signed int i) @{ @@ -9759,10 +9014,8 @@ square (signed int i) @} @end example -@noindent - We can see the generated machine code in assembler form (on stderr) by -setting @pxref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context +setting @ref{1d,,GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE} on the context before compiling: @example @@ -9770,8 +9023,6 @@ ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1); result = ctxt.compile (); @end example -@noindent - @example .file "fake.c" .text @@ -9799,19 +9050,15 @@ square: .section .note.GNU-stack,"",@@progbits @end example -@noindent - -By default, no optimizations are performed, the equivalent of GCC's +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{127,,gccjit;;context;;set_int_option()} with -@pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: +@ref{135,,gccjit;;context;;set_int_option()} with +@ref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: @example ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3); @end example -@noindent - @example .file "fake.c" .text @@ -9832,16 +9079,14 @@ square: .section .note.GNU-stack,"",@@progbits @end example -@noindent - 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{128} +@anchor{cp/intro/tutorial02 full-example}@anchor{136} @subsubsection Full example -Here's what the above looks like as a complete program: +Here’s what the above looks like as a complete program: @quotation @@ -9941,10 +9186,7 @@ main (int argc, char **argv) gcc_jit_result_release (result); return 0; @} - @end example - -@noindent @end quotation Building and running it: @@ -9960,8 +9202,6 @@ $ ./tut02-square result: 25 @end example -@noindent - @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @c @@ -9980,7 +9220,7 @@ result: 25 @c <http://www.gnu.org/licenses/>. @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{129}@anchor{cp/intro/tutorial03 doc}@anchor{12a} +@anchor{cp/intro/tutorial03 doc}@anchor{137}@anchor{cp/intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{138} @subsection Tutorial part 3: Loops and variables @@ -9997,14 +9237,12 @@ int loop_test (int n) return sum; @} @end example - -@noindent @end quotation This example demonstrates some more features of libgccjit, with local variables and a loop. -To break this down into libgccjit terms, it's usually easier to reword +To break this down into libgccjit terms, it’s usually easier to reword the @cite{for} loop as a @cite{while} loop, giving: @quotation @@ -10022,11 +9260,9 @@ int loop_test (int n) return sum; @} @end example - -@noindent @end quotation -Here's what the final control flow graph will look like: +Here’s what the final control flow graph will look like: @quotation @@ -10040,7 +9276,7 @@ Here's what the final control flow graph will look like: @end quotation As before, we include the libgccjit++ header and make a -@code{gccjit::context}. +@ref{128,,gccjit;;context}. @example #include <libgccjit++.h> @@ -10051,8 +9287,6 @@ void test (void) ctxt = gccjit::context::acquire (); @end example -@noindent - The function works with the C @cite{int} type. In the previous tutorial we acquired this via @@ -10061,16 +9295,12 @@ In the previous tutorial we acquired this via gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_INT); @end example -@noindent - though we could equally well make it work on, say, @cite{double}: @example gccjit::type the_type = ctxt.get_type (ctxt, GCC_JIT_TYPE_DOUBLE); @end example -@noindent - For integer types we can use @code{gccjit::context::get_int_type} to directly bind a specific type: @@ -10078,9 +9308,7 @@ to directly bind a specific type: gccjit::type the_type = ctxt.get_int_type <int> (); @end example -@noindent - -Let's build the function: +Let’s build the function: @example gcc_jit_param n = ctxt.new_param (the_type, "n"); @@ -10093,8 +9321,6 @@ gccjit::function func = params, 0); @end example -@noindent - @menu * Expressions; lvalues and rvalues: Expressions lvalues and rvalues<2>. * Control flow: Control flow<2>. @@ -10104,18 +9330,18 @@ 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{12b} +@anchor{cp/intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{139} @subsubsection Expressions: lvalues and rvalues -The base class of expression is the @code{gccjit::rvalue}, +The base class of expression is the @ref{131,,gccjit;;rvalue}, representing an expression that can be on the @emph{right}-hand side of an assignment: a value that can be computed somehow, and assigned @emph{to} a storage area (such as a variable). It has a specific -@code{gccjit::type}. +@ref{12a,,gccjit;;type}. -Anothe important class is @code{gccjit::lvalue}. -A @code{gccjit::lvalue}. is something that can of the @emph{left}-hand +Anothe important class is @ref{13a,,gccjit;;lvalue}. +A @ref{13a,,gccjit;;lvalue}. is something that can of the @emph{left}-hand side of an assignment: a storage area (such as a variable). In other words, every assignment can be thought of as: @@ -10124,21 +9350,17 @@ In other words, every assignment can be thought of as: LVALUE = RVALUE; @end example -@noindent - -Note that @code{gccjit::lvalue} is a subclass of -@code{gccjit::rvalue}, where in an assignment of the form: +Note that @ref{13a,,gccjit;;lvalue} is a subclass of +@ref{131,,gccjit;;rvalue}, where in an assignment of the form: @example LVALUE_A = LVALUE_B; @end example -@noindent - the @cite{LVALUE_B} implies reading the current value of that storage area, assigning it into the @cite{LVALUE_A}. -So far the only expressions we've seen are from the previous tutorial: +So far the only expressions we’ve seen are from the previous tutorial: @enumerate @@ -10159,9 +9381,7 @@ gccjit::rvalue expr = gccjit::rvalue expr = param_i * param_i; @end example -@noindent - -which is a @code{gccjit::rvalue}, and +which is a @ref{131,,gccjit;;rvalue}, and @end quotation @@ -10169,15 +9389,15 @@ which is a @code{gccjit::rvalue}, and @item the various function parameters: @cite{param_i} and @cite{param_n}, instances of -@code{gccjit::param}, which is a subclass of @code{gccjit::lvalue} -(and, in turn, of @code{gccjit::rvalue}): +@ref{13b,,gccjit;;param}, which is a subclass of @ref{13a,,gccjit;;lvalue} +(and, in turn, of @ref{131,,gccjit;;rvalue}): we can both read from and write to function parameters within the body of a function. @end enumerate Our new example has a new kind of expression: we have two local variables. We create them by calling -@pxref{12c,,gccjit;;function;;new_local()}, supplying a type and a name: +@ref{13c,,gccjit;;function;;new_local()}, supplying a type and a name: @example /* Build locals: */ @@ -10185,9 +9405,7 @@ gccjit::lvalue i = func.new_local (the_type, "i"); gccjit::lvalue sum = func.new_local (the_type, "sum"); @end example -@noindent - -These are instances of @code{gccjit::lvalue} - they can be read from +These are instances of @ref{13a,,gccjit;;lvalue} - they can be read from and written to. Note that there is no precanned way to create @emph{and} initialize a variable @@ -10197,13 +9415,11 @@ like in C: int i = 0; @end example -@noindent - 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{12d} +@anchor{cp/intro/tutorial03 control-flow}@anchor{13d} @subsubsection Control flow @@ -10226,8 +9442,8 @@ the body of the loop after the loop terminates (@cite{return sum}) @end enumerate -so we create these as @code{gccjit::block} instances within the -@code{gccjit::function}: +so we create these as @ref{13e,,gccjit;;block} instances within the +@ref{13f,,gccjit;;function}: @example gccjit::block b_initial = func.new_block ("initial"); @@ -10236,14 +9452,12 @@ gccjit::block b_loop_body = func.new_block ("loop_body"); gccjit::block b_after_loop = func.new_block ("after_loop"); @end example -@noindent - 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{12e,,gccjit;;block;;add_assignment()} to add -an assignment statement, and using @pxref{12f,,gccjit;;context;;zero()} to get +@ref{140,,gccjit;;block;;add_assignment()} to add +an assignment statement, and using @ref{141,,gccjit;;context;;zero()} to get the constant value @cite{0} for the relevant type for the right-hand side of the assignment: @@ -10255,22 +9469,18 @@ b_initial.add_assignment (sum, ctxt.zero (the_type)); b_initial.add_assignment (i, ctxt.zero (the_type)); @end example -@noindent - We can then terminate the entry block by jumping to the conditional: @example b_initial.end_with_jump (b_loop_cond); @end example -@noindent - The conditional block is equivalent to the line @cite{while (i < n)} from our 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}. +@ref{131,,gccjit;;rvalue}, in this case the comparison of @cite{i} and @cite{n}. -We could build the comparison using @pxref{130,,gccjit;;context;;new_comparison()}: +We could build the comparison using @ref{142,,gccjit;;context;;new_comparison()}: @example gccjit::rvalue guard = @@ -10278,10 +9488,8 @@ gccjit::rvalue guard = i, n); @end example -@noindent - -and can then use this to add @cite{b_loop_cond}'s sole statement, via -@pxref{131,,gccjit;;block;;end_with_conditional()}: +and can then use this to add @cite{b_loop_cond}’s sole statement, via +@ref{143,,gccjit;;block;;end_with_conditional()}: @example b_loop_cond.end_with_conditional (guard, @@ -10289,17 +9497,13 @@ b_loop_cond.end_with_conditional (guard, b_loop_body); // on_false @end example -@noindent - -However @code{gccjit::rvalue} has overloaded operators for this, so we +However @ref{131,,gccjit;;rvalue} has overloaded operators for this, so we express the conditional as @example gccjit::rvalue guard = (i >= n); @end example -@noindent - and hence we can write the block more concisely as: @example @@ -10309,13 +9513,11 @@ b_loop_cond.end_with_conditional ( b_loop_body); // on_false @end example -@noindent - 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{132,,gccjit;;block;;add_assignment_op()} to handle these operations: +lvalue is modified “in-place”. We use +@ref{144,,gccjit;;block;;add_assignment_op()} to handle these operations: @example /* sum += i * i */ @@ -10324,10 +9526,8 @@ b_loop_body.add_assignment_op (sum, i * i); @end example -@noindent - The @cite{i++} can be thought of as @cite{i += 1}, and can thus be handled in -a similar way. We use @pxref{2f,,gcc_jit_context_one()} to get the constant +a similar way. We use @ref{2f,,gcc_jit_context_one()} to get the constant value @cite{1} (for the relevant type) for the right-hand side of the assignment. @@ -10338,12 +9538,10 @@ b_loop_body.add_assignment_op (i, ctxt.one (the_type)); @end example -@noindent - @cartouche @quotation Note For numeric constants other than 0 or 1, we could use -@pxref{133,,gccjit;;context;;new_rvalue()}, which has overloads +@ref{145,,gccjit;;context;;new_rvalue()}, which has overloads for both @code{int} and @code{double}. @end quotation @end cartouche @@ -10354,8 +9552,6 @@ The loop body completes by jumping back to the conditional: b_loop_body.end_with_jump (b_loop_cond); @end example -@noindent - Finally, we populate the @cite{b_after_loop} block, reached when the loop conditional is false. We want to generate the equivalent of: @@ -10363,8 +9559,6 @@ conditional is false. We want to generate the equivalent of: return sum; @end example -@noindent - so the block is just one statement: @example @@ -10372,18 +9566,16 @@ so the block is just one statement: b_after_loop.end_with_return (sum); @end example -@noindent - @cartouche @quotation Note You can intermingle block creation with statement creation, but given that the terminator statements generally include references -to other blocks, I find it's clearer to create all the blocks, +to other blocks, I find it’s clearer to create all the blocks, @emph{then} all the statements. @end quotation @end cartouche -We've finished populating the function. As before, we can now compile it +We’ve finished populating the function. As before, we can now compile it to machine code: @example @@ -10410,28 +9602,22 @@ if (!loop_test) printf ("result: %d", loop_test (10)); @end example -@noindent - @example result: 285 @end example -@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{134} +@anchor{cp/intro/tutorial03 visualizing-the-control-flow-graph}@anchor{146} @subsubsection Visualizing the control flow graph You can see the control flow graph of a function using -@pxref{135,,gccjit;;function;;dump_to_dot()}: +@ref{147,,gccjit;;function;;dump_to_dot()}: @example func.dump_to_dot ("/tmp/sum-of-squares.dot"); @end example -@noindent - giving a .dot file in GraphViz format. You can convert this to an image using @cite{dot}: @@ -10440,8 +9626,6 @@ You can convert this to an image using @cite{dot}: $ dot -Tpng /tmp/sum-of-squares.dot -o /tmp/sum-of-squares.png @end example -@noindent - or use a viewer (my preferred one is xdot.py; see @indicateurl{https://github.com/jrfonseca/xdot.py}; on Fedora you can install it with @cite{yum install python-xdot}): @@ -10458,7 +9642,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{136} +@anchor{cp/intro/tutorial03 full-example}@anchor{148} @subsubsection Full example @@ -10602,10 +9786,7 @@ main (int argc, char **argv) gcc_jit_result_release (result); return 0; @} - @end example - -@noindent @end quotation Building and running it: @@ -10621,8 +9802,6 @@ $ ./tut03-sum-of-squares loop_test returned: 285 @end example -@noindent - @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @c @@ -10641,11 +9820,11 @@ loop_test returned: 285 @c <http://www.gnu.org/licenses/>. @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{137}@anchor{cp/intro/tutorial04 doc}@anchor{138} +@anchor{cp/intro/tutorial04 doc}@anchor{149}@anchor{cp/intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{14a} @subsection Tutorial part 4: Adding JIT-compilation to a toy interpreter -In this example we construct a "toy" interpreter, and add JIT-compilation +In this example we construct a “toy” interpreter, and add JIT-compilation to it. @menu @@ -10663,11 +9842,11 @@ 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{139} +@anchor{cp/intro/tutorial04 our-toy-interpreter}@anchor{14b} @subsubsection Our toy interpreter -It's a stack-based interpreter, and is intended as a (very simple) example +It’s a stack-based interpreter, and is intended as a (very simple) example of the kind of bytecode interpreter seen in dynamic languages such as Python, Ruby etc. @@ -10692,7 +9871,7 @@ Functions can only take one parameter. Functions have a stack of @cite{int} values. @item -We'll implement function call within the interpreter by calling a +We’ll implement function call within the interpreter by calling a function in our implementation, rather than implementing our own frame stack. @@ -10898,7 +10077,7 @@ nonzero, jump to Programs can be interpreted, disassembled, and compiled to machine code. -The interpreter reads @code{.toy} scripts. Here's what a simple recursive +The interpreter reads @code{.toy} scripts. Here’s what a simple recursive factorial program looks like, the script @code{factorial.toy}. The parser ignores lines beginning with a @cite{#}. @@ -10955,10 +10134,7 @@ BINARY_MULT # 9: RETURN - @end example - -@noindent @end quotation The interpreter is a simple infinite loop with a big @code{switch} statement @@ -11064,14 +10240,11 @@ toyvm_function::interpret (int arg, FILE *trace) #undef POP @} - @end example - -@noindent @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{13a} +@anchor{cp/intro/tutorial04 compiling-to-machine-code}@anchor{14c} @subsubsection Compiling to machine code @@ -11083,20 +10256,17 @@ then directly executed in-process: @example typedef int (*toyvm_compiled_func) (int); - @end example - -@noindent @end quotation -Our compiler isn't very sophisticated; it takes the implementation of +Our compiler isn’t very sophisticated; it takes the implementation of each opcode above, and maps it directly to the operations supported by the libgccjit API. How should we handle the stack? In theory we could calculate what the stack depth will be at each opcode, and optimize away the stack -manipulation "by hand". We'll see below that libgccjit is able to do -this for us, so we'll implement stack manipulation +manipulation “by hand”. We’ll see below that libgccjit is able to do +this for us, so we’ll implement stack manipulation in a direct way, by creating a @code{stack} array and @code{stack_depth} variables, local within the generated function, equivalent to this C code: @@ -11105,9 +10275,7 @@ int stack_depth; int stack[MAX_STACK_DEPTH]; @end example -@noindent - -We'll also have local variables @code{x} and @code{y} for use when implementing +We’ll also have local variables @code{x} and @code{y} for use when implementing the opcodes, equivalent to this: @example @@ -11115,8 +10283,6 @@ int x; int y; @end example -@noindent - This means our compiler has the following state: @quotation @@ -11144,14 +10310,11 @@ This means our compiler has the following state: gccjit::block initial_block; gccjit::block op_blocks[MAX_OPS]; - @end example - -@noindent @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{13b} +@anchor{cp/intro/tutorial04 setting-things-up}@anchor{14d} @subsubsection Setting things up @@ -11169,10 +10332,7 @@ compilation_state::create_types () bool_type = ctxt.get_type (GCC_JIT_TYPE_BOOL); stack_type = ctxt.new_array_type (int_type, MAX_STACK_DEPTH); - @end example - -@noindent @end quotation along with extracting a useful @cite{int} constant: @@ -11184,13 +10344,10 @@ along with extracting a useful @cite{int} constant: @} - @end example - -@noindent @end quotation -We'll implement push and pop in terms of the @code{stack} array and +We’ll implement push and pop in terms of the @code{stack} array and @code{stack_depth}. Here are helper functions for adding statements to a block, implementing pushing and popping values: @@ -11243,14 +10400,11 @@ compilation_state::add_pop (gccjit::block block, loc); @} - @end example - -@noindent @end quotation We will support single-stepping through the generated code in the -debugger, so we need to create @code{gccjit::location} instances, one +debugger, so we need to create @ref{14e,,gccjit;;location} instances, one per operation in the source code. These will reference the lines of e.g. @code{factorial.toy}. @@ -11271,13 +10425,10 @@ compilation_state::create_locations () @} @} - @end example - -@noindent @end quotation -Let's create the function itself. As usual, we create its parameter +Let’s create the function itself. As usual, we create its parameter first, then use the parameter to create the function: @quotation @@ -11296,10 +10447,7 @@ compilation_state::create_function (const char *funcname) params, 0, op_locs[0]); - @end example - -@noindent @end quotation We create the locals within the function. @@ -11312,18 +10460,15 @@ We create the locals within the function. x = fn.new_local (int_type, "x"); y = fn.new_local (int_type, "y"); - @end example - -@noindent @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{13c} +@anchor{cp/intro/tutorial04 populating-the-function}@anchor{14f} @subsubsection Populating the function -There's some one-time initialization, and the API treats the first block +There’s some one-time initialization, and the API treats the first block you create as the entrypoint of the function, so we need to create that block first: @@ -11332,10 +10477,7 @@ block first: @example initial_block = fn.new_block ("initial"); - @end example - -@noindent @end quotation We can now create blocks for each of the operations. Most of these will @@ -11351,13 +10493,10 @@ be consolidated into larger blocks when the optimizer runs. op_blocks[pc] = fn.new_block (buf); @} - @end example - -@noindent @end quotation -Now that we have a block it can jump to when it's done, we can populate +Now that we have a block it can jump to when it’s done, we can populate the initial block: @quotation @@ -11378,10 +10517,7 @@ the initial block: initial_block.end_with_jump (op_blocks[0], op_locs[0]); - @end example - -@noindent @end quotation We can now populate the blocks for the individual operations. We loop @@ -11402,16 +10538,13 @@ through them, adding instructions to their blocks: toyvm_op *op; op = &toyvmfn.fn_ops[pc]; - @end example - -@noindent @end quotation -We're going to have another big @code{switch} statement for implementing +We’re going to have another big @code{switch} statement for implementing the opcodes, this time for compiling them, rather than interpreting -them. It's helpful to have macros for implementing push and pop, so that -we can make the @code{switch} statement that's coming up look as much as +them. It’s helpful to have macros for implementing push and pop, so that +we can make the @code{switch} statement that’s coming up look as much as possible like the one above within the interpreter: @example @@ -11427,16 +10560,13 @@ possible like the one above within the interpreter: #define PUSH_Y() \ PUSH_RVALUE (y) - @end example -@noindent - @cartouche @quotation Note A particularly clever implementation would have an @emph{identical} @code{switch} statement shared by the interpreter and the compiler, with -some preprocessor "magic". We're not doing that here, for the sake +some preprocessor “magic”. We’re not doing that here, for the sake of simplicity. @end quotation @end cartouche @@ -11447,7 +10577,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{13d,,gccjit;;block;;add_comment()} to add descriptive comments +@ref{150,,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}: @@ -11457,10 +10587,7 @@ the generated IR for, say @code{factorial}: block.add_comment (opcode_names[op->op_opcode], loc); - @end example - -@noindent @end quotation We can now write the big @code{switch} statement that implements the @@ -11569,10 +10696,7 @@ individual opcodes, populating the relevant block with statements: assert(0); @} /* end of switch on opcode */ - @end example - -@noindent @end quotation Every block must be terminated, via a call to one of the @@ -11587,30 +10711,25 @@ to the next block. && op->op_opcode != RETURN) block.end_with_jump (next_block, loc); - @end example - -@noindent @end quotation 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{13e} +@anchor{cp/intro/tutorial04 verifying-the-control-flow-graph}@anchor{151} @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{135,,gccjit;;function;;dump_to_dot()}: +using @ref{147,,gccjit;;function;;dump_to_dot()}: @example fn.dump_to_dot ("/tmp/factorial.dot"); @end example -@noindent - and viewing the result. Note how the label names, comments, and variable names show up in the dump, to make it easier to spot errors in our compiler. @@ -11627,7 +10746,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{13f} +@anchor{cp/intro/tutorial04 compiling-the-context}@anchor{152} @subsubsection Compiling the context @@ -11662,11 +10781,8 @@ private: gcc_jit_result *m_result; @}; - @end example -@noindent - @example compilation_result compiler_result = fn->compile (); @@ -11677,18 +10793,15 @@ private: printf ("compiler result: %d\n", code (atoi (argv[2]))); - @end example - -@noindent @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{140} +@anchor{cp/intro/tutorial04 single-stepping-through-the-generated-code}@anchor{153} @subsubsection Single-stepping through the generated code -It's possible to debug the generated code. To do this we need to both: +It’s possible to debug the generated code. To do this we need to both: @quotation @@ -11698,20 +10811,18 @@ 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{141,,gccjit;;context;;new_location()} and using the +calling @ref{154,,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{126,,gccjit;;context;;set_bool_option()}: +@ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the +@ref{128,,gccjit;;context} via +@ref{134,,gccjit;;context;;set_bool_option()}: @example ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1); @end example - -@noindent @end itemize @end quotation @@ -11728,9 +10839,7 @@ Breakpoint 1, factorial (arg=10) at factorial.toy:14 14 DUP @end example -@noindent - -We've set up location information, which references @code{factorial.toy}. +We’ve set up location information, which references @code{factorial.toy}. This allows us to use e.g. @code{list} to see where we are in the script: @example @@ -11747,8 +10856,6 @@ This allows us to use e.g. @code{list} to see where we are in the script: 18 PUSH_CONST 2 @end example -@noindent - and to step through the function, examining the data: @example @@ -11762,46 +10869,40 @@ $5 = @{10, 10, 2, 0, -7152, 32767, 0, 0@} $6 = 3 @end example -@noindent - -You'll see that the parts of the @code{stack} array that haven't been +You’ll see that the parts of the @code{stack} array that haven’t been touched yet are uninitialized. @cartouche @quotation Note Turning on optimizations may lead to unpredictable results when stepping through the generated code: the execution may appear to -"jump around" the source code. This is analogous to turning up the +“jump around” the source code. This is analogous to turning up the optimization level in a regular compiler. @end quotation @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{142} +@anchor{cp/intro/tutorial04 examining-the-generated-code}@anchor{155} @subsubsection Examining the generated code How good is the optimized code? We can turn up optimizations, by calling -@pxref{127,,gccjit;;context;;set_int_option()} with -@pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: +@ref{135,,gccjit;;context;;set_int_option()} with +@ref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}: @example ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 3); @end example -@noindent - -One of GCC's internal representations is called "gimple". A dump of the +One of GCC’s internal representations is called “gimple”. A dump of the initial gimple representation of the code can be seen by setting: @example ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE, 1); @end example -@noindent - With optimization on and source locations displayed, this gives: @c We'll use "c" for gimple dumps @@ -11845,8 +10946,6 @@ factorial (signed int arg) /* etc */ @end example -@noindent - You can see the generated machine code in assembly form via: @example @@ -11854,8 +10953,6 @@ ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE, 1); result = ctxt.compile (); @end example -@noindent - which shows that (on this x86_64 box) the compiler has unrolled the loop and is using MMX instructions to perform several multiplications simultaneously: @@ -11905,8 +11002,6 @@ factorial: # etc - edited for brevity @end example -@noindent - This is clearly overkill for a function that will likely overflow the @code{int} type before the vectorization is worthwhile - but then again, this is a toy example. @@ -11917,8 +11012,6 @@ Turning down the optimization level to 2: ctxt.set_int_option (GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL, 2); @end example -@noindent - yields this code, which is simple enough to quote in its entirety: @example @@ -11960,13 +11053,11 @@ factorial: .section .note.GNU-stack,"",@@progbits @end example -@noindent - 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{143} +@anchor{cp/intro/tutorial04 putting-it-all-together}@anchor{156} @subsubsection Putting it all together @@ -11996,10 +11087,8 @@ interpreter result: 55 compiler result: 55 @end example -@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{144} +@anchor{cp/intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{157} @subsubsection Behind the curtain: How does our code get optimized? @@ -12013,14 +11102,12 @@ state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING, 1); state.ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES, 1); @end example -@noindent - -This will dump detailed information about the compiler's state to a +This will dump detailed information about the compiler’s state to a directory under @code{/tmp}, and keep it from being cleaned up. The precise names and their formats of these files is subject to change. Higher optimization levels lead to more files. -Here's what I saw (edited for brevity; there were almost 200 files): +Here’s what I saw (edited for brevity; there were almost 200 files): @example intermediate files written to /tmp/libgccjit-KPQbGw @@ -12038,8 +11125,6 @@ fake.c.016t.ssa # etc @end example -@noindent - The gimple code is converted into Static Single Assignment form, with annotations for use when generating the debuginfo: @@ -12047,8 +11132,6 @@ with annotations for use when generating the debuginfo: $ less /tmp/libgccjit-KPQbGw/fake.c.016t.ssa @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -12090,18 +11173,14 @@ initial: /* etc; edited for brevity */ @end example -@noindent - We can perhaps better see the code by turning off -@pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG} +@ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} to suppress all those @code{DEBUG} statements, giving: @example $ less /tmp/libgccjit-1Hywc0/fake.c.016t.ssa @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -12187,10 +11266,8 @@ instr9: @} @end example -@noindent - -Note in the above how all the @code{gccjit::block} instances we -created have been consolidated into just 3 blocks in GCC's internal +Note in the above how all the @ref{13e,,gccjit;;block} instances we +created have been consolidated into just 3 blocks in GCC’s internal representation: @code{initial}, @code{instr4} and @code{instr9}. @menu @@ -12200,11 +11277,11 @@ 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{145} +@anchor{cp/intro/tutorial04 optimizing-away-stack-manipulation}@anchor{158} @subsubsection Optimizing away stack manipulation -Recall our simple implementation of stack operations. Let's examine +Recall our simple implementation of stack operations. Let’s examine how the stack operations are optimized away. After a pass of constant-propagation, the depth of the stack at each @@ -12214,8 +11291,6 @@ opcode can be determined at compile-time: $ less /tmp/libgccjit-1Hywc0/fake.c.021t.ccp1 @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -12276,20 +11351,16 @@ instr9: @} @end example -@noindent - Note how, in the above, all those @code{stack_depth} values are now just -constants: we're accessing specific stack locations at each opcode. +constants: we’re accessing specific stack locations at each opcode. -The "esra" pass ("Early Scalar Replacement of Aggregates") breaks -out our "stack" array into individual elements: +The “esra” pass (“Early Scalar Replacement of Aggregates”) breaks +out our “stack” array into individual elements: @example $ less /tmp/libgccjit-1Hywc0/fake.c.024t.esra @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -12365,8 +11436,6 @@ instr9: @} @end example -@noindent - Hence at this point, all those pushes and pops of the stack are now simply assignments to specific temporary variables. @@ -12377,8 +11446,6 @@ optimized away: $ less /tmp/libgccjit-1Hywc0/fake.c.026t.copyprop1 @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -12422,8 +11489,6 @@ instr9: @} @end example -@noindent - Later on, another pass finally eliminated @code{stack_depth} local and the unused parts of the @cite{stack`} array altogether: @@ -12431,8 +11496,6 @@ unused parts of the @cite{stack`} array altogether: $ less /tmp/libgccjit-1Hywc0/fake.c.036t.release_ssa @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -12477,10 +11540,8 @@ instr9: @} @end example -@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{146} +@anchor{cp/intro/tutorial04 elimination-of-tail-recursion}@anchor{159} @subsubsection Elimination of tail recursion @@ -12492,8 +11553,6 @@ an iteration: $ less /tmp/libgccjit-1Hywc0/fake.c.030t.tailr1 @end example -@noindent - @example ;; Function factorial (factorial, funcdef_no=0, decl_uid=53, symbol_order=0) @@ -12547,8 +11606,6 @@ instr9: @} @end example -@noindent - @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @c Originally contributed by David Malcolm <dmalcolm@redhat.com> @c @@ -12567,7 +11624,7 @@ instr9: @c <http://www.gnu.org/licenses/>. @node Topic Reference<2>,,Tutorial<2>,C++ bindings for libgccjit -@anchor{cp/topics/index doc}@anchor{147}@anchor{cp/topics/index topic-reference}@anchor{148} +@anchor{cp/topics/index doc}@anchor{15a}@anchor{cp/topics/index topic-reference}@anchor{15b} @section Topic Reference @@ -12597,88 +11654,28 @@ instr9: * Source Locations: Source Locations<2>. * Compiling a context: Compiling a context<2>. -Compilation contexts - -* Lifetime-management: Lifetime-management<2>. -* Thread-safety: Thread-safety<2>. -* Error-handling: Error-handling<3>. -* Debugging: Debugging<2>. -* Options: Options<4>. - -Options - -* String Options: String Options<2>. -* Boolean options: Boolean options<2>. -* Integer options: Integer options<2>. -* Additional command-line options: Additional command-line options<2>. - -Types - -* Standard types: Standard types<2>. -* Pointers@comma{} const@comma{} and volatile: Pointers const and volatile<2>. -* Vector types: Vector types<2>. -* Structures and unions: Structures and unions<2>. - -Expressions - -* Rvalues: Rvalues<2>. -* Lvalues: Lvalues<2>. -* Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>. - -Rvalues - -* Simple expressions: Simple expressions<2>. -* Vector expressions: Vector expressions<2>. -* Unary Operations: Unary Operations<2>. -* Binary Operations: Binary Operations<2>. -* Comparisons: Comparisons<2>. -* Function calls: Function calls<2>. -* Function pointers: Function pointers<3>. -* Type-coercion: Type-coercion<2>. - -Lvalues - -* Global variables: Global variables<2>. - -Creating and using functions - -* Params: Params<2>. -* Functions: Functions<2>. -* Blocks: Blocks<2>. -* Statements: Statements<2>. - -Source Locations - -* Faking it: Faking it<2>. - -Compiling a context - -* In-memory compilation: In-memory compilation<2>. -* Ahead-of-time compilation: Ahead-of-time compilation<2>. - @end menu - @node Compilation contexts<2>,Objects<2>,,Topic Reference<2> -@anchor{cp/topics/contexts compilation-contexts}@anchor{149}@anchor{cp/topics/contexts doc}@anchor{14a} +@anchor{cp/topics/contexts doc}@anchor{15c}@anchor{cp/topics/contexts compilation-contexts}@anchor{15d} @subsection Compilation contexts @geindex gccjit;;context (C++ class) -@anchor{cp/topics/contexts gccjit context}@anchor{14b} +@anchor{cp/topics/contexts _CPPv4N6gccjit7contextE}@anchor{128}@anchor{cp/topics/contexts _CPPv3N6gccjit7contextE}@anchor{15e}@anchor{cp/topics/contexts _CPPv2N6gccjit7contextE}@anchor{15f}@anchor{cp/topics/contexts gccjit context}@anchor{160} @deffn {C++ Class} gccjit::context @end deffn -The top-level of the C++ API is the @pxref{14b,,gccjit;;context} type. +The top-level of the C++ API is the @ref{128,,gccjit;;context} type. -A @pxref{14b,,gccjit;;context} instance encapsulates the state of a +A @ref{128,,gccjit;;context} instance encapsulates the state of a compilation. You can set up options on it, and add types, functions and code. -Invoking @pxref{124,,gccjit;;context;;compile()} on it gives you a -@pxref{16,,gcc_jit_result *}. +Invoking @ref{132,,gccjit;;context;;compile()} on it gives you a +@ref{16,,gcc_jit_result *}. -It is a thin wrapper around the C API's @pxref{8,,gcc_jit_context *}. +It is a thin wrapper around the C API’s @ref{8,,gcc_jit_context *}. @menu * Lifetime-management: Lifetime-management<2>. @@ -12690,7 +11687,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{14c} +@anchor{cp/topics/contexts lifetime-management}@anchor{161} @subsubsection Lifetime-management @@ -12699,36 +11696,34 @@ 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{11e} -@deffn {C++ Function} gccjit::context gccjit::context::acquire () +@anchor{cp/topics/contexts _CPPv4N6gccjit7context7acquireEv}@anchor{129}@anchor{cp/topics/contexts _CPPv3N6gccjit7context7acquireEv}@anchor{162}@anchor{cp/topics/contexts _CPPv2N6gccjit7context7acquireEv}@anchor{163}@anchor{cp/topics/contexts gccjit context acquire}@anchor{164} +@deffn {C++ Function} gccjit::@ref{128,,context} gccjit::@ref{128,,context}::acquire () -This function acquires a new @pxref{14b,,gccjit;;context} instance, +This function acquires a new @ref{128,,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{120} -@deffn {C++ Function} void gccjit::context::release () +@anchor{cp/topics/contexts _CPPv4N6gccjit7context7releaseEv}@anchor{12c}@anchor{cp/topics/contexts _CPPv3N6gccjit7context7releaseEv}@anchor{165}@anchor{cp/topics/contexts _CPPv2N6gccjit7context7releaseEv}@anchor{166}@anchor{cp/topics/contexts gccjit context release}@anchor{167} +@deffn {C++ Function} void gccjit::@ref{128,,context}::release () This function releases all resources associated with the given context. Both the context itself and all of its @code{gccjit::object *} instances are cleaned up. It should be called exactly once on a given context. -It is invalid to use the context or any of its "contextual" objects +It is invalid to use the context or any of its “contextual” objects after calling this. @example ctxt.release (); @end example - -@noindent @end deffn @geindex gccjit;;context;;new_child_context (C++ function) -@anchor{cp/topics/contexts gccjit context new_child_context}@anchor{14d} -@deffn {C++ Function} gccjit::context gccjit::context::new_child_context () +@anchor{cp/topics/contexts _CPPv4N6gccjit7context17new_child_contextEv}@anchor{168}@anchor{cp/topics/contexts _CPPv3N6gccjit7context17new_child_contextEv}@anchor{169}@anchor{cp/topics/contexts _CPPv2N6gccjit7context17new_child_contextEv}@anchor{16a}@anchor{cp/topics/contexts gccjit context new_child_context}@anchor{16b} +@deffn {C++ Function} gccjit::@ref{128,,context} gccjit::@ref{128,,context}::new_child_context () Given an existing JIT context, create a child context. @@ -12754,29 +11749,29 @@ JIT-compiling just one function or loop, but can reference types and helper functions created within the parent context. Contexts can be arbitrarily nested, provided the above rules are -followed, but it's probably not worth going above 2 or 3 levels, and +followed, but it’s probably not worth going above 2 or 3 levels, and 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{14e} +@anchor{cp/topics/contexts thread-safety}@anchor{16c} @subsubsection Thread-safety -Instances of @pxref{14b,,gccjit;;context} created via -@pxref{11e,,gccjit;;context;;acquire()} are independent from each other: +Instances of @ref{128,,gccjit;;context} created via +@ref{129,,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{14d,,gccjit;;context;;new_child_context()} are +Contexts created via @ref{168,,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, -and if you're using multiple threads you should provide your own locking +ultimate ancestor into independent “family trees”. Only one thread +within a process may use a given “family tree” of such contexts at once, +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{14f} +@anchor{cp/topics/contexts error-handling}@anchor{16d} @subsubsection Error-handling @@ -12785,15 +11780,15 @@ around entire such context partitions. You can only compile and get code from a context if no errors occur. In general, if an error occurs when using an API entrypoint, it returns -NULL. You don't have to check everywhere for NULL results, since the +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{150,,gccjit;;context;;get_first_error()}. +@ref{16e,,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{150} -@deffn {C++ Function} const char* gccjit::context::get_first_error (gccjit::context* ctxt) +@anchor{cp/topics/contexts _CPPv4N6gccjit7context15get_first_errorEPN6gccjit7contextE}@anchor{16e}@anchor{cp/topics/contexts _CPPv3N6gccjit7context15get_first_errorEPN6gccjit7contextE}@anchor{16f}@anchor{cp/topics/contexts _CPPv2N6gccjit7context15get_first_errorEPN6gccjit7contextE}@anchor{170}@anchor{cp/topics/contexts gccjit context get_first_error__gccjit contextP}@anchor{171} +@deffn {C++ Function} const char *gccjit::@ref{128,,context}::get_first_error (gccjit::context *ctxt) Returns the first error message that occurred on the context. @@ -12804,18 +11799,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{151} +@anchor{cp/topics/contexts debugging}@anchor{172} @subsubsection Debugging @geindex gccjit;;context;;dump_to_file (C++ function) -@anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{152} -@deffn {C++ Function} void gccjit::context::dump_to_file (const std::string& path, int update_locations) +@anchor{cp/topics/contexts _CPPv4N6gccjit7context12dump_to_fileERKNSt6stringEi}@anchor{173}@anchor{cp/topics/contexts _CPPv3N6gccjit7context12dump_to_fileERKNSt6stringEi}@anchor{174}@anchor{cp/topics/contexts _CPPv2N6gccjit7context12dump_to_fileERKNSt6stringEi}@anchor{175}@anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{176} +@deffn {C++ Function} void gccjit::@ref{128,,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. +describing what’s been set up on the context. -If "update_locations" is true, then also set up @pxref{153,,gccjit;;location} +If “update_locations” is true, then also set up @ref{14e,,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 @@ -12823,11 +11818,11 @@ 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{154} -@deffn {C++ Function} void gccjit::context::dump_reproducer_to_file (gcc_jit_context* ctxt, const char* path) +@anchor{cp/topics/contexts _CPPv4N6gccjit7context23dump_reproducer_to_fileEP15gcc_jit_contextPKc}@anchor{177}@anchor{cp/topics/contexts _CPPv3N6gccjit7context23dump_reproducer_to_fileEP15gcc_jit_contextPKc}@anchor{178}@anchor{cp/topics/contexts _CPPv2N6gccjit7context23dump_reproducer_to_fileEP15gcc_jit_contextPKc}@anchor{179}@anchor{cp/topics/contexts gccjit context dump_reproducer_to_file__gcc_jit_contextP cCP}@anchor{17a} +@deffn {C++ Function} void gccjit::@ref{128,,context}::dump_reproducer_to_file (gcc_jit_context *ctxt, const char *path) This is a thin wrapper around the C API -@pxref{5d,,gcc_jit_context_dump_reproducer_to_file()}, and hence works the +@ref{5d,,gcc_jit_context_dump_reproducer_to_file()}, and hence works the same way. Note that the generated source is C code, not C++; this might be of use @@ -12835,7 +11830,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{155} +@anchor{cp/topics/contexts options}@anchor{17b} @subsubsection Options @@ -12848,63 +11843,61 @@ 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{156} +@anchor{cp/topics/contexts string-options}@anchor{17c} @subsubsection String Options @geindex gccjit;;context;;set_str_option (C++ function) -@anchor{cp/topics/contexts gccjit context set_str_option__enum cCP}@anchor{157} -@deffn {C++ Function} void gccjit::context::set_str_option (enum gcc_jit_str_option, const char* value) +@anchor{cp/topics/contexts _CPPv4N6gccjit7context14set_str_optionE18gcc_jit_str_optionPKc}@anchor{17d}@anchor{cp/topics/contexts _CPPv3N6gccjit7context14set_str_optionE18gcc_jit_str_optionPKc}@anchor{17e}@anchor{cp/topics/contexts _CPPv2N6gccjit7context14set_str_optionE18gcc_jit_str_optionPKc}@anchor{17f}@anchor{cp/topics/contexts gccjit context set_str_option__gcc_jit_str_option cCP}@anchor{180} +@deffn {C++ Function} void gccjit::@ref{128,,context}::set_str_option (enum gcc_jit_str_option, const char *value) Set a string option of the context. This is a thin wrapper around the C API -@pxref{61,,gcc_jit_context_set_str_option()}; the options have the same +@ref{61,,gcc_jit_context_set_str_option()}; the options have the same meaning. @end deffn @node Boolean options<2>,Integer options<2>,String Options<2>,Options<4> -@anchor{cp/topics/contexts boolean-options}@anchor{158} +@anchor{cp/topics/contexts boolean-options}@anchor{181} @subsubsection Boolean options @geindex gccjit;;context;;set_bool_option (C++ function) -@anchor{cp/topics/contexts gccjit context set_bool_option__enum i}@anchor{126} -@deffn {C++ Function} void gccjit::context::set_bool_option (enum gcc_jit_bool_option, int value) +@anchor{cp/topics/contexts _CPPv4N6gccjit7context15set_bool_optionE19gcc_jit_bool_optioni}@anchor{134}@anchor{cp/topics/contexts _CPPv3N6gccjit7context15set_bool_optionE19gcc_jit_bool_optioni}@anchor{182}@anchor{cp/topics/contexts _CPPv2N6gccjit7context15set_bool_optionE19gcc_jit_bool_optioni}@anchor{183}@anchor{cp/topics/contexts gccjit context set_bool_option__gcc_jit_bool_option i}@anchor{184} +@deffn {C++ Function} void gccjit::@ref{128,,context}::set_bool_option (enum gcc_jit_bool_option, int value) Set a boolean option of the context. This is a thin wrapper around the C API -@pxref{1b,,gcc_jit_context_set_bool_option()}; the options have the same +@ref{1b,,gcc_jit_context_set_bool_option()}; the options have the same 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{159} -@deffn {C++ Function} void gccjit::context::set_bool_allow_unreachable_blocks (int bool_value) +@anchor{cp/topics/contexts _CPPv4N6gccjit7context33set_bool_allow_unreachable_blocksEi}@anchor{185}@anchor{cp/topics/contexts _CPPv3N6gccjit7context33set_bool_allow_unreachable_blocksEi}@anchor{186}@anchor{cp/topics/contexts _CPPv2N6gccjit7context33set_bool_allow_unreachable_blocksEi}@anchor{187}@anchor{cp/topics/contexts gccjit context set_bool_allow_unreachable_blocks__i}@anchor{188} +@deffn {C++ Function} void gccjit::@ref{128,,context}::set_bool_allow_unreachable_blocks (int bool_value) By default, libgccjit will issue an error about unreachable blocks within a function. This entrypoint can be used to disable that error; it is a thin wrapper around the C API -@pxref{6b,,gcc_jit_context_set_bool_allow_unreachable_blocks()}. +@ref{6b,,gcc_jit_context_set_bool_allow_unreachable_blocks()}. -This entrypoint was added in @pxref{6c,,LIBGCCJIT_ABI_2}; you can test for +This entrypoint was added in @ref{6c,,LIBGCCJIT_ABI_2}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks @end example - -@noindent @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{15a} -@deffn {C++ Function} void gccjit::context::set_bool_use_external_driver (int bool_value) +@anchor{cp/topics/contexts _CPPv4N6gccjit7context28set_bool_use_external_driverEi}@anchor{189}@anchor{cp/topics/contexts _CPPv3N6gccjit7context28set_bool_use_external_driverEi}@anchor{18a}@anchor{cp/topics/contexts _CPPv2N6gccjit7context28set_bool_use_external_driverEi}@anchor{18b}@anchor{cp/topics/contexts gccjit context set_bool_use_external_driver__i}@anchor{18c} +@deffn {C++ Function} void gccjit::@ref{128,,context}::set_bool_use_external_driver (int bool_value) -libgccjit internally generates assembler, and uses "driver" code +libgccjit internally generates assembler, and uses “driver” code for converting it to other formats (e.g. shared libraries). By default, libgccjit will use an embedded copy of the driver @@ -12912,57 +11905,53 @@ code. This option can be used to instead invoke an external driver executable as a subprocess; it is a thin wrapper around the C API -@pxref{6d,,gcc_jit_context_set_bool_use_external_driver()}. +@ref{6d,,gcc_jit_context_set_bool_use_external_driver()}. -This entrypoint was added in @pxref{6e,,LIBGCCJIT_ABI_5}; you can test for +This entrypoint was added in @ref{6e,,LIBGCCJIT_ABI_5}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver @end example - -@noindent @end deffn @node Integer options<2>,Additional command-line options<2>,Boolean options<2>,Options<4> -@anchor{cp/topics/contexts integer-options}@anchor{15b} +@anchor{cp/topics/contexts integer-options}@anchor{18d} @subsubsection Integer options @geindex gccjit;;context;;set_int_option (C++ function) -@anchor{cp/topics/contexts gccjit context set_int_option__enum i}@anchor{127} -@deffn {C++ Function} void gccjit::context::set_int_option (enum gcc_jit_int_option, int value) +@anchor{cp/topics/contexts _CPPv4N6gccjit7context14set_int_optionE18gcc_jit_int_optioni}@anchor{135}@anchor{cp/topics/contexts _CPPv3N6gccjit7context14set_int_optionE18gcc_jit_int_optioni}@anchor{18e}@anchor{cp/topics/contexts _CPPv2N6gccjit7context14set_int_optionE18gcc_jit_int_optioni}@anchor{18f}@anchor{cp/topics/contexts gccjit context set_int_option__gcc_jit_int_option i}@anchor{190} +@deffn {C++ Function} void gccjit::@ref{128,,context}::set_int_option (enum gcc_jit_int_option, int value) Set an integer option of the context. This is a thin wrapper around the C API -@pxref{1e,,gcc_jit_context_set_int_option()}; the options have the same +@ref{1e,,gcc_jit_context_set_int_option()}; the options have the same meaning. @end deffn @node Additional command-line options<2>,,Integer options<2>,Options<4> -@anchor{cp/topics/contexts additional-command-line-options}@anchor{15c} +@anchor{cp/topics/contexts additional-command-line-options}@anchor{191} @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{15d} -@deffn {C++ Function} void gccjit::context::add_command_line_option (const char* optname) +@anchor{cp/topics/contexts _CPPv4N6gccjit7context23add_command_line_optionEPKc}@anchor{192}@anchor{cp/topics/contexts _CPPv3N6gccjit7context23add_command_line_optionEPKc}@anchor{193}@anchor{cp/topics/contexts _CPPv2N6gccjit7context23add_command_line_optionEPKc}@anchor{194}@anchor{cp/topics/contexts gccjit context add_command_line_option__cCP}@anchor{195} +@deffn {C++ Function} void gccjit::@ref{128,,context}::add_command_line_option (const char *optname) Add an arbitrary gcc command-line option to the context for use when compiling. This is a thin wrapper around the C API -@pxref{72,,gcc_jit_context_add_command_line_option()}. +@ref{72,,gcc_jit_context_add_command_line_option()}. -This entrypoint was added in @pxref{73,,LIBGCCJIT_ABI_1}; you can test for +This entrypoint was added in @ref{73,,LIBGCCJIT_ABI_1}; you can test for its presence using @example #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option @end example - -@noindent @end deffn @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @@ -12983,18 +11972,18 @@ its presence using @c <http://www.gnu.org/licenses/>. @node Objects<2>,Types<2>,Compilation contexts<2>,Topic Reference<2> -@anchor{cp/topics/objects objects}@anchor{15e}@anchor{cp/topics/objects doc}@anchor{15f} +@anchor{cp/topics/objects doc}@anchor{196}@anchor{cp/topics/objects objects}@anchor{197} @subsection Objects @geindex gccjit;;object (C++ class) -@anchor{cp/topics/objects gccjit object}@anchor{160} +@anchor{cp/topics/objects _CPPv4N6gccjit6objectE}@anchor{12d}@anchor{cp/topics/objects _CPPv3N6gccjit6objectE}@anchor{198}@anchor{cp/topics/objects _CPPv2N6gccjit6objectE}@anchor{199}@anchor{cp/topics/objects gccjit object}@anchor{19a} @deffn {C++ Class} gccjit::object @end deffn Almost every entity in the API (with the exception of -@pxref{14b,,gccjit;;context} and @pxref{16,,gcc_jit_result *}) is a -"contextual" object, a @pxref{160,,gccjit;;object}. +@ref{128,,gccjit;;context} and @ref{16,,gcc_jit_result *}) is a +“contextual” object, a @ref{12d,,gccjit;;object}. A JIT object: @@ -13004,11 +11993,11 @@ A JIT object: @itemize * @item -is associated with a @pxref{14b,,gccjit;;context}. +is associated with a @ref{128,,gccjit;;context}. @item is automatically cleaned up for you when its context is released so -you don't need to manually track and cleanup all objects, just the +you don’t need to manually track and cleanup all objects, just the contexts. @end itemize @end quotation @@ -13029,20 +12018,18 @@ The C++ class hierarchy within the @code{gccjit} namespace looks like this: +- case_ @end example -@noindent - -The @pxref{160,,gccjit;;object} base class has the following operations: +The @ref{12d,,gccjit;;object} base class has the following operations: @geindex gccjit;;object;;get_context (C++ function) -@anchor{cp/topics/objects gccjit object get_contextC}@anchor{161} -@deffn {C++ Function} gccjit::context gccjit::object::get_context () const +@anchor{cp/topics/objects _CPPv4NK6gccjit6object11get_contextEv}@anchor{19b}@anchor{cp/topics/objects _CPPv3NK6gccjit6object11get_contextEv}@anchor{19c}@anchor{cp/topics/objects _CPPv2NK6gccjit6object11get_contextEv}@anchor{19d}@anchor{cp/topics/objects gccjit object get_contextC}@anchor{19e} +@deffn {C++ Function} gccjit::@ref{128,,context} gccjit::@ref{12d,,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{121} -@deffn {C++ Function} std::string gccjit::object::get_debug_string () const +@anchor{cp/topics/objects _CPPv4NK6gccjit6object16get_debug_stringEv}@anchor{12e}@anchor{cp/topics/objects _CPPv3NK6gccjit6object16get_debug_stringEv}@anchor{19f}@anchor{cp/topics/objects _CPPv2NK6gccjit6object16get_debug_stringEv}@anchor{1a0}@anchor{cp/topics/objects gccjit object get_debug_stringC}@anchor{1a1} +@deffn {C++ Function} std::string gccjit::@ref{12d,,object}::get_debug_string () const Generate a human-readable description for the given object. @@ -13052,15 +12039,11 @@ For example, printf ("obj: %s\n", obj.get_debug_string ().c_str ()); @end example -@noindent - might give this text on stdout: @example obj: 4.0 * (float)i @end example - -@noindent @end deffn @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @@ -13081,16 +12064,16 @@ obj: 4.0 * (float)i @c <http://www.gnu.org/licenses/>. @node Types<2>,Expressions<2>,Objects<2>,Topic Reference<2> -@anchor{cp/topics/types doc}@anchor{162}@anchor{cp/topics/types types}@anchor{163} +@anchor{cp/topics/types doc}@anchor{1a2}@anchor{cp/topics/types types}@anchor{1a3} @subsection Types @geindex gccjit;;type (C++ class) -@anchor{cp/topics/types gccjit type}@anchor{164} +@anchor{cp/topics/types _CPPv4N6gccjit4typeE}@anchor{12a}@anchor{cp/topics/types _CPPv3N6gccjit4typeE}@anchor{1a4}@anchor{cp/topics/types _CPPv2N6gccjit4typeE}@anchor{1a5}@anchor{cp/topics/types gccjit type}@anchor{1a6} @deffn {C++ Class} gccjit::type gccjit::type represents a type within the library. It is a subclass -of @pxref{160,,gccjit;;object}. +of @ref{12d,,gccjit;;object}. @end deffn Types can be created in several ways: @@ -13100,35 +12083,29 @@ Types can be created in several ways: @item fundamental types can be accessed using -@pxref{11f,,gccjit;;context;;get_type()}: +@ref{12b,,gccjit;;context;;get_type()}: @example gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT); @end example -@noindent - or using the @code{gccjit::context::get_int_type} template: @example gccjit::type t = ctxt.get_int_type <unsigned short> (); @end example -@noindent - -See @pxref{b,,gcc_jit_context_get_type()} for the available types. +See @ref{b,,gcc_jit_context_get_type()} for the available types. @item derived types can be accessed by using functions such as -@pxref{165,,gccjit;;type;;get_pointer()} and @pxref{166,,gccjit;;type;;get_const()}: +@ref{1a7,,gccjit;;type;;get_pointer()} and @ref{1a8,,gccjit;;type;;get_const()}: @example gccjit::type const_int_star = int_type.get_const ().get_pointer (); gccjit::type int_const_star = int_type.get_pointer ().get_const (); @end example -@noindent - @item by creating structures (see below). @end itemize @@ -13142,28 +12119,28 @@ 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{167} +@anchor{cp/topics/types standard-types}@anchor{1a9} @subsubsection Standard types @geindex gccjit;;context;;get_type (C++ function) -@anchor{cp/topics/types gccjit context get_type__enum}@anchor{11f} -@deffn {C++ Function} gccjit::type gccjit::context::get_type (enum gcc_jit_types) +@anchor{cp/topics/types _CPPv4N6gccjit7context8get_typeE13gcc_jit_types}@anchor{12b}@anchor{cp/topics/types _CPPv3N6gccjit7context8get_typeE13gcc_jit_types}@anchor{1aa}@anchor{cp/topics/types _CPPv2N6gccjit7context8get_typeE13gcc_jit_types}@anchor{1ab}@anchor{cp/topics/types gccjit context get_type__gcc_jit_types}@anchor{1ac} +@deffn {C++ Function} gccjit::@ref{12a,,type} gccjit::@ref{128,,context}::get_type (enum gcc_jit_types) Access a specific type. This is a thin wrapper around -@pxref{b,,gcc_jit_context_get_type()}; the parameter has the same meaning. +@ref{b,,gcc_jit_context_get_type()}; the parameter has the same meaning. @end deffn @geindex gccjit;;context;;get_int_type (C++ function) -@anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{168} -@deffn {C++ Function} gccjit::type gccjit::context::get_int_type (size_t num_bytes, int is_signed) +@anchor{cp/topics/types _CPPv4N6gccjit7context12get_int_typeE6size_ti}@anchor{1ad}@anchor{cp/topics/types _CPPv3N6gccjit7context12get_int_typeE6size_ti}@anchor{1ae}@anchor{cp/topics/types _CPPv2N6gccjit7context12get_int_typeE6size_ti}@anchor{1af}@anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{1b0} +@deffn {C++ Function} gccjit::@ref{12a,,type} gccjit::@ref{128,,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<T> (C++ function) -@anchor{cp/topics/types gccjit context get_int_type T}@anchor{169} -@deffn {C++ Function} gccjit::type gccjit::context::get_int_type<T> () +@anchor{cp/topics/types _CPPv4IEN6gccjit7context12get_int_typeI1TEEN6gccjit4typeEv}@anchor{1b1}@anchor{cp/topics/types _CPPv3IEN6gccjit7context12get_int_typeI1TEEv}@anchor{1b2}@anchor{cp/topics/types _CPPv2IEN6gccjit7context12get_int_typeI1TEEv}@anchor{1b3} +@deffn {C++ Function} template<>gccjit::@ref{12a,,type} gccjit::@ref{128,,context}::get_int_type<T> () Access the given integer type. For example, you could map the @code{unsigned short} type into a gccjit::type via: @@ -13171,105 +12148,99 @@ Access the given integer type. For example, you could map the @example gccjit::type t = ctxt.get_int_type <unsigned short> (); @end example - -@noindent @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{16a} +@anchor{cp/topics/types pointers-const-and-volatile}@anchor{1b4} @subsubsection Pointers, @cite{const}, and @cite{volatile} @geindex gccjit;;type;;get_pointer (C++ function) -@anchor{cp/topics/types gccjit type get_pointer}@anchor{165} -@deffn {C++ Function} gccjit::type gccjit::type::get_pointer () +@anchor{cp/topics/types _CPPv4N6gccjit4type11get_pointerEv}@anchor{1a7}@anchor{cp/topics/types _CPPv3N6gccjit4type11get_pointerEv}@anchor{1b5}@anchor{cp/topics/types _CPPv2N6gccjit4type11get_pointerEv}@anchor{1b6}@anchor{cp/topics/types gccjit type get_pointer}@anchor{1b7} +@deffn {C++ Function} gccjit::@ref{12a,,type} gccjit::@ref{12a,,type}::get_pointer () -Given type "T", get type "T*". +Given type “T”, get type “T*”. @end deffn @geindex gccjit;;type;;get_const (C++ function) -@anchor{cp/topics/types gccjit type get_const}@anchor{166} -@deffn {C++ Function} gccjit::type gccjit::type::get_const () +@anchor{cp/topics/types _CPPv4N6gccjit4type9get_constEv}@anchor{1a8}@anchor{cp/topics/types _CPPv3N6gccjit4type9get_constEv}@anchor{1b8}@anchor{cp/topics/types _CPPv2N6gccjit4type9get_constEv}@anchor{1b9}@anchor{cp/topics/types gccjit type get_const}@anchor{1ba} +@deffn {C++ Function} gccjit::@ref{12a,,type} gccjit::@ref{12a,,type}::get_const () -Given type "T", get type "const T". +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{16b} -@deffn {C++ Function} gccjit::type gccjit::type::get_volatile () +@anchor{cp/topics/types _CPPv4N6gccjit4type12get_volatileEv}@anchor{1bb}@anchor{cp/topics/types _CPPv3N6gccjit4type12get_volatileEv}@anchor{1bc}@anchor{cp/topics/types _CPPv2N6gccjit4type12get_volatileEv}@anchor{1bd}@anchor{cp/topics/types gccjit type get_volatile}@anchor{1be} +@deffn {C++ Function} gccjit::@ref{12a,,type} gccjit::@ref{12a,,type}::get_volatile () -Given type "T", get type "volatile T". +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{16c} -@deffn {C++ Function} gccjit::type gccjit::type::get_aligned (size_t alignment_in_bytes) +@anchor{cp/topics/types _CPPv4N6gccjit4type11get_alignedE6size_t}@anchor{1bf}@anchor{cp/topics/types _CPPv3N6gccjit4type11get_alignedE6size_t}@anchor{1c0}@anchor{cp/topics/types _CPPv2N6gccjit4type11get_alignedE6size_t}@anchor{1c1}@anchor{cp/topics/types gccjit type get_aligned__s}@anchor{1c2} +@deffn {C++ Function} gccjit::@ref{12a,,type} gccjit::@ref{12a,,type}::get_aligned (size_t alignment_in_bytes) -Given type "T", get type: +Given type “T”, get type: @example T __attribute__ ((aligned (ALIGNMENT_IN_BYTES))) @end example -@noindent - 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{16d} -@deffn {C++ Function} gccjit::type gccjit::context::new_array_type (gccjit::type element_type, int num_elements, gccjit::location loc) +@anchor{cp/topics/types _CPPv4N6gccjit7context14new_array_typeEN6gccjit4typeEiN6gccjit8locationE}@anchor{1c3}@anchor{cp/topics/types _CPPv3N6gccjit7context14new_array_typeEN6gccjit4typeEiN6gccjit8locationE}@anchor{1c4}@anchor{cp/topics/types _CPPv2N6gccjit7context14new_array_typeEN6gccjit4typeEiN6gccjit8locationE}@anchor{1c5}@anchor{cp/topics/types gccjit context new_array_type__gccjit type i gccjit location}@anchor{1c6} +@deffn {C++ Function} gccjit::@ref{12a,,type} gccjit::@ref{128,,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). -Param "loc" is optional. +Given type “T”, get type “T[N]” (for a constant N). +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{16e} +@anchor{cp/topics/types vector-types}@anchor{1c7} @subsubsection Vector types @geindex gccjit;;type;;get_vector (C++ function) -@anchor{cp/topics/types gccjit type get_vector__s}@anchor{16f} -@deffn {C++ Function} gccjit::type gccjit::type::get_vector (size_t num_units) +@anchor{cp/topics/types _CPPv4N6gccjit4type10get_vectorE6size_t}@anchor{1c8}@anchor{cp/topics/types _CPPv3N6gccjit4type10get_vectorE6size_t}@anchor{1c9}@anchor{cp/topics/types _CPPv2N6gccjit4type10get_vectorE6size_t}@anchor{1ca}@anchor{cp/topics/types gccjit type get_vector__s}@anchor{1cb} +@deffn {C++ Function} gccjit::@ref{12a,,type} gccjit::@ref{12a,,type}::get_vector (size_t num_units) -Given type "T", get type: +Given type “T”, get type: @example T __attribute__ ((vector_size (sizeof(T) * num_units)) @end example -@noindent - 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{170} +@anchor{cp/topics/types structures-and-unions}@anchor{1cc} @subsubsection Structures and unions @geindex gccjit;;struct_ (C++ class) -@anchor{cp/topics/types gccjit struct_}@anchor{171} +@anchor{cp/topics/types _CPPv4N6gccjit7struct_E}@anchor{1cd}@anchor{cp/topics/types _CPPv3N6gccjit7struct_E}@anchor{1ce}@anchor{cp/topics/types _CPPv2N6gccjit7struct_E}@anchor{1cf}@anchor{cp/topics/types gccjit struct_}@anchor{1d0} @deffn {C++ Class} gccjit::struct_ @end deffn A compound type analagous to a C @cite{struct}. -@pxref{171,,gccjit;;struct_} is a subclass of @pxref{164,,gccjit;;type} (and thus -of @pxref{160,,gccjit;;object} in turn). +@ref{1cd,,gccjit;;struct_} is a subclass of @ref{12a,,gccjit;;type} (and thus +of @ref{12d,,gccjit;;object} in turn). @geindex gccjit;;field (C++ class) -@anchor{cp/topics/types gccjit field}@anchor{172} +@anchor{cp/topics/types _CPPv4N6gccjit5fieldE}@anchor{1d1}@anchor{cp/topics/types _CPPv3N6gccjit5fieldE}@anchor{1d2}@anchor{cp/topics/types _CPPv2N6gccjit5fieldE}@anchor{1d3}@anchor{cp/topics/types gccjit field}@anchor{1d4} @deffn {C++ Class} gccjit::field @end deffn -A field within a @pxref{171,,gccjit;;struct_}. +A field within a @ref{1cd,,gccjit;;struct_}. -@pxref{172,,gccjit;;field} is a subclass of @pxref{160,,gccjit;;object}. +@ref{1d1,,gccjit;;field} is a subclass of @ref{12d,,gccjit;;object}. -You can model C @cite{struct} types by creating @pxref{171,,gccjit;;struct_} and -@pxref{172,,gccjit;;field} instances, in either order: +You can model C @cite{struct} types by creating @ref{1cd,,gccjit;;struct_} and +@ref{1d1,,gccjit;;field} instances, in either order: @itemize * @@ -13281,8 +12252,6 @@ by creating the fields, then the structure. For example, to model: struct coord @{double x; double y; @}; @end example -@noindent - you could call: @example @@ -13294,8 +12263,6 @@ fields.push_back (field_y); gccjit::struct_ coord = ctxt.new_struct_type ("coord", fields); @end example -@noindent - @item by creating the structure, then populating it with fields, typically to allow modelling self-referential structs such as: @@ -13304,8 +12271,6 @@ to allow modelling self-referential structs such as: struct node @{ int m_hash; struct node *m_next; @}; @end example -@noindent - like this: @example @@ -13318,22 +12283,20 @@ fields.push_back (field_hash); fields.push_back (field_next); node.set_fields (fields); @end example - -@noindent @end itemize @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{173} -@deffn {C++ Function} gccjit::field gccjit::context::new_field (gccjit::type type, const char* name, gccjit::location loc) +@anchor{cp/topics/types _CPPv4N6gccjit7context9new_fieldEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{1d5}@anchor{cp/topics/types _CPPv3N6gccjit7context9new_fieldEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{1d6}@anchor{cp/topics/types _CPPv2N6gccjit7context9new_fieldEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{1d7}@anchor{cp/topics/types gccjit context new_field__gccjit type cCP gccjit location}@anchor{1d8} +@deffn {C++ Function} gccjit::@ref{1d1,,field} gccjit::@ref{128,,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{174} -@deffn {C++ Function} gccjit::struct_ gccjit::context::new_struct_type (const std::string& name, std::vector<field>& fields, gccjit::location loc) +@anchor{cp/topics/types _CPPv4N6gccjit7context15new_struct_typeERKNSt6stringERNSt6vectorI5fieldEEN6gccjit8locationE}@anchor{1d9}@anchor{cp/topics/types _CPPv3N6gccjit7context15new_struct_typeERKNSt6stringERNSt6vectorI5fieldEEN6gccjit8locationE}@anchor{1da}@anchor{cp/topics/types _CPPv2N6gccjit7context15new_struct_typeERKNSt6stringERNSt6vectorI5fieldEEN6gccjit8locationE}@anchor{1db}@anchor{cp/topics/types gccjit context new_struct_type__ssCR std vector field R gccjit location}@anchor{1dc} +@deffn {C++ Function} gccjit::@ref{1cd,,struct_} gccjit::@ref{128,,context}::new_struct_type (const std::string &name, std::vector<field> &fields, gccjit::location loc) @quotation @@ -13342,13 +12305,13 @@ 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{175} -@deffn {C++ Function} gccjit::struct_ gccjit::context::new_opaque_struct (const std::string& name, gccjit::location loc) +@anchor{cp/topics/types _CPPv4N6gccjit7context17new_opaque_structERKNSt6stringEN6gccjit8locationE}@anchor{1dd}@anchor{cp/topics/types _CPPv3N6gccjit7context17new_opaque_structERKNSt6stringEN6gccjit8locationE}@anchor{1de}@anchor{cp/topics/types _CPPv2N6gccjit7context17new_opaque_structERKNSt6stringEN6gccjit8locationE}@anchor{1df}@anchor{cp/topics/types gccjit context new_opaque_struct__ssCR gccjit location}@anchor{1e0} +@deffn {C++ Function} gccjit::@ref{1cd,,struct_} gccjit::@ref{128,,context}::new_opaque_struct (const std::string &name, gccjit::location loc) Construct a new struct type, with the given name, but without specifying the fields. The fields can be omitted (in which case the size of the struct is not known), or later specified using -@pxref{8d,,gcc_jit_struct_set_fields()}. +@ref{90,,gcc_jit_struct_set_fields()}. @end deffn @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @@ -13369,7 +12332,7 @@ size of the struct is not known), or later specified using @c <http://www.gnu.org/licenses/>. @node Expressions<2>,Creating and using functions<2>,Types<2>,Topic Reference<2> -@anchor{cp/topics/expressions expressions}@anchor{176}@anchor{cp/topics/expressions doc}@anchor{177} +@anchor{cp/topics/expressions doc}@anchor{1e1}@anchor{cp/topics/expressions expressions}@anchor{1e2} @subsection Expressions @@ -13378,37 +12341,21 @@ size of the struct is not known), or later specified using * Lvalues: Lvalues<2>. * Working with pointers@comma{} structs and unions: Working with pointers structs and unions<2>. -Rvalues - -* Simple expressions: Simple expressions<2>. -* Vector expressions: Vector expressions<2>. -* Unary Operations: Unary Operations<2>. -* Binary Operations: Binary Operations<2>. -* Comparisons: Comparisons<2>. -* Function calls: Function calls<2>. -* Function pointers: Function pointers<3>. -* Type-coercion: Type-coercion<2>. - -Lvalues - -* Global variables: Global variables<2>. - @end menu - @node Rvalues<2>,Lvalues<2>,,Expressions<2> -@anchor{cp/topics/expressions rvalues}@anchor{178} +@anchor{cp/topics/expressions rvalues}@anchor{1e3} @subsubsection Rvalues @geindex gccjit;;rvalue (C++ class) -@anchor{cp/topics/expressions gccjit rvalue}@anchor{179} +@anchor{cp/topics/expressions _CPPv4N6gccjit6rvalueE}@anchor{131}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalueE}@anchor{1e4}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalueE}@anchor{1e5}@anchor{cp/topics/expressions gccjit rvalue}@anchor{1e6} @deffn {C++ Class} gccjit::rvalue @end deffn -A @pxref{179,,gccjit;;rvalue} is an expression that can be computed. It is a -subclass of @pxref{160,,gccjit;;object}, and is a thin wrapper around -@pxref{13,,gcc_jit_rvalue *} from the C API. +A @ref{131,,gccjit;;rvalue} is an expression that can be computed. It is a +subclass of @ref{12d,,gccjit;;object}, and is a thin wrapper around +@ref{13,,gcc_jit_rvalue *} from the C API. It can be simple, e.g.: @@ -13421,7 +12368,7 @@ It can be simple, e.g.: an integer value e.g. @cite{0} or @cite{42} @item -a string literal e.g. @cite{"Hello world"} +a string literal e.g. @cite{“Hello world”} @item a variable e.g. @cite{i}. These are also lvalues (see below). @@ -13453,8 +12400,8 @@ 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{17a} -@deffn {C++ Function} gccjit::type gccjit::rvalue::get_type () +@anchor{cp/topics/expressions _CPPv4N6gccjit6rvalue8get_typeEv}@anchor{1e7}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalue8get_typeEv}@anchor{1e8}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalue8get_typeEv}@anchor{1e9}@anchor{cp/topics/expressions gccjit rvalue get_type}@anchor{1ea} +@deffn {C++ Function} gccjit::@ref{12a,,type} gccjit::@ref{131,,rvalue}::get_type () Get the type of this rvalue. @end deffn @@ -13472,29 +12419,29 @@ Get the type of this rvalue. @end menu @node Simple expressions<2>,Vector expressions<2>,,Rvalues<2> -@anchor{cp/topics/expressions simple-expressions}@anchor{17b} +@anchor{cp/topics/expressions simple-expressions}@anchor{1eb} @subsubsection Simple expressions @geindex gccjit;;context;;new_rvalue (C++ function) -@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{133} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, int value) const +@anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeEi}@anchor{145}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeEi}@anchor{1ec}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeEi}@anchor{1ed}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{1ee} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,context}::new_rvalue (gccjit::type numeric_type, int value) const Given a numeric type (integer or floating point), build an rvalue for 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{17c} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, long value) const +@anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeEl}@anchor{1ef}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeEl}@anchor{1f0}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeEl}@anchor{1f1}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type lC}@anchor{1f2} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,context}::new_rvalue (gccjit::type numeric_type, long value) const Given a numeric type (integer or floating point), build an rvalue for the given constant @code{long} value. @end deffn @geindex gccjit;;context;;zero (C++ function) -@anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{12f} -@deffn {C++ Function} gccjit::rvalue gccjit::context::zero (gccjit::type numeric_type) const +@anchor{cp/topics/expressions _CPPv4NK6gccjit7context4zeroEN6gccjit4typeE}@anchor{141}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context4zeroEN6gccjit4typeE}@anchor{1f3}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context4zeroEN6gccjit4typeE}@anchor{1f4}@anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{1f5} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,context}::zero (gccjit::type numeric_type) const Given a numeric type (integer or floating point), get the rvalue for zero. Essentially this is just a shortcut for: @@ -13502,13 +12449,11 @@ zero. Essentially this is just a shortcut for: @example ctxt.new_rvalue (numeric_type, 0) @end example - -@noindent @end deffn @geindex gccjit;;context;;one (C++ function) -@anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{17d} -@deffn {C++ Function} gccjit::rvalue gccjit::context::one (gccjit::type numeric_type) const +@anchor{cp/topics/expressions _CPPv4NK6gccjit7context3oneEN6gccjit4typeE}@anchor{1f6}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context3oneEN6gccjit4typeE}@anchor{1f7}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context3oneEN6gccjit4typeE}@anchor{1f8}@anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{1f9} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,context}::one (gccjit::type numeric_type) const Given a numeric type (integer or floating point), get the rvalue for one. Essentially this is just a shortcut for: @@ -13516,41 +12461,39 @@ one. Essentially this is just a shortcut for: @example ctxt.new_rvalue (numeric_type, 1) @end example - -@noindent @end deffn @geindex gccjit;;context;;new_rvalue (C++ function) -@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{17e} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, double value) const +@anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeEd}@anchor{1fa}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeEd}@anchor{1fb}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeEd}@anchor{1fc}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{1fd} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,context}::new_rvalue (gccjit::type numeric_type, double value) const Given a numeric type (integer or floating point), build an rvalue for 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{17f} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type pointer_type, void* value) const +@anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeEPv}@anchor{1fe}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeEPv}@anchor{1ff}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeEPv}@anchor{200}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type voidPC}@anchor{201} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{180} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (const std::string& value) const +@anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueERKNSt6stringE}@anchor{202}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueERKNSt6stringE}@anchor{203}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueERKNSt6stringE}@anchor{204}@anchor{cp/topics/expressions gccjit context new_rvalue__ssCRC}@anchor{205} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,context}::new_rvalue (const std::string &value) const Generate an rvalue of type @code{GCC_JIT_TYPE_CONST_CHAR_PTR} for the given string. This is akin to a string literal. @end deffn @node Vector expressions<2>,Unary Operations<2>,Simple expressions<2>,Rvalues<2> -@anchor{cp/topics/expressions vector-expressions}@anchor{181} +@anchor{cp/topics/expressions vector-expressions}@anchor{206} @subsubsection Vector expressions @geindex gccjit;;context;;new_rvalue (C++ function) -@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type std vector gccjit rvalue C}@anchor{182} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type vector_type, std::vector<gccjit::rvalue> elements) const +@anchor{cp/topics/expressions _CPPv4NK6gccjit7context10new_rvalueEN6gccjit4typeENSt6vectorIN6gccjit6rvalueEEE}@anchor{207}@anchor{cp/topics/expressions _CPPv3NK6gccjit7context10new_rvalueEN6gccjit4typeENSt6vectorIN6gccjit6rvalueEEE}@anchor{208}@anchor{cp/topics/expressions _CPPv2NK6gccjit7context10new_rvalueEN6gccjit4typeENSt6vectorIN6gccjit6rvalueEEE}@anchor{209}@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type std vector gccjit rvalue C}@anchor{20a} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,context}::new_rvalue (gccjit::type vector_type, std::vector<gccjit::rvalue> elements) const Given a vector type, and a vector of scalar rvalue elements, generate a vector rvalue. @@ -13559,20 +12502,20 @@ The number of elements needs to match that of the vector type. @end deffn @node Unary Operations<2>,Binary Operations<2>,Vector expressions<2>,Rvalues<2> -@anchor{cp/topics/expressions unary-operations}@anchor{183} +@anchor{cp/topics/expressions unary-operations}@anchor{20b} @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{184} -@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) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context12new_unary_opE16gcc_jit_unary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{20c}@anchor{cp/topics/expressions _CPPv3N6gccjit7context12new_unary_opE16gcc_jit_unary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{20d}@anchor{cp/topics/expressions _CPPv2N6gccjit7context12new_unary_opE16gcc_jit_unary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{20e}@anchor{cp/topics/expressions gccjit context new_unary_op__gcc_jit_unary_op gccjit type gccjit rvalue gccjit location}@anchor{20f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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. Parameter @code{loc} is optional. -This is a thin wrapper around the C API's -@pxref{9e,,gcc_jit_context_new_unary_op()} and the available unary +This is a thin wrapper around the C API’s +@ref{a1,,gcc_jit_context_new_unary_op()} and the available unary operations are documented there. @end deffn @@ -13580,8 +12523,8 @@ 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{185} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{210}@anchor{cp/topics/expressions _CPPv3N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{211}@anchor{cp/topics/expressions _CPPv2N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{212}@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit location}@anchor{213} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,context}::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc) Negate an arithmetic value; for example: @@ -13589,41 +12532,33 @@ Negate an arithmetic value; for example: gccjit::rvalue negpi = ctxt.new_minus (t_double, pi); @end example -@noindent - builds the equivalent of this C expression: @example -pi @end example - -@noindent @end deffn @geindex new_bitwise_negate (C++ function) -@anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{186} -@deffn {C++ Function} gccjit::rvalue new_bitwise_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv418new_bitwise_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{214}@anchor{cp/topics/expressions _CPPv318new_bitwise_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{215}@anchor{cp/topics/expressions _CPPv218new_bitwise_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{216}@anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{217} +@deffn {C++ Function} gccjit::@ref{131,,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: +Bitwise negation of an integer value (one’s complement); for example: @example gccjit::rvalue mask = ctxt.new_bitwise_negate (t_int, a); @end example -@noindent - builds the equivalent of this C expression: @example ~a @end example - -@noindent @end deffn @geindex new_logical_negate (C++ function) -@anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{187} -@deffn {C++ Function} gccjit::rvalue new_logical_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv418new_logical_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{218}@anchor{cp/topics/expressions _CPPv318new_logical_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{219}@anchor{cp/topics/expressions _CPPv218new_logical_negateN6gccjit4typeEN6gccjit6rvalueEN6gccjit8locationE}@anchor{21a}@anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{21b} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} new_logical_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc) Logical negation of an arithmetic or pointer value; for example: @@ -13631,67 +12566,57 @@ Logical negation of an arithmetic or pointer value; for example: gccjit::rvalue guard = ctxt.new_logical_negate (t_bool, cond); @end example -@noindent - builds the equivalent of this C expression: @example !cond @end example - -@noindent @end deffn The most concise way to spell them is with overloaded operators: @geindex operator- (C++ function) -@anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{188} -@deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a) +@anchor{cp/topics/expressions _CPPv4miN6gccjit6rvalueE}@anchor{21c}@anchor{cp/topics/expressions _CPPv3miN6gccjit6rvalueE}@anchor{21d}@anchor{cp/topics/expressions _CPPv2miN6gccjit6rvalueE}@anchor{21e}@anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{21f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator@w{-} (gccjit::rvalue a) @example gccjit::rvalue negpi = -pi; @end example - -@noindent @end deffn @geindex operator~ (C++ function) -@anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{189} -@deffn {C++ Function} gccjit::rvalue operator~ (gccjit::rvalue a) +@anchor{cp/topics/expressions _CPPv4coN6gccjit6rvalueE}@anchor{220}@anchor{cp/topics/expressions _CPPv3coN6gccjit6rvalueE}@anchor{221}@anchor{cp/topics/expressions _CPPv2coN6gccjit6rvalueE}@anchor{222}@anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{223} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator~ (gccjit::rvalue a) @example gccjit::rvalue mask = ~a; @end example - -@noindent @end deffn @geindex operator! (C++ function) -@anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{18a} -@deffn {C++ Function} gccjit::rvalue operator! (gccjit::rvalue a) +@anchor{cp/topics/expressions _CPPv4ntN6gccjit6rvalueE}@anchor{224}@anchor{cp/topics/expressions _CPPv3ntN6gccjit6rvalueE}@anchor{225}@anchor{cp/topics/expressions _CPPv2ntN6gccjit6rvalueE}@anchor{226}@anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{227} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator! (gccjit::rvalue a) @example gccjit::rvalue guard = !cond; @end example - -@noindent @end deffn @node Binary Operations<2>,Comparisons<2>,Unary Operations<2>,Rvalues<2> -@anchor{cp/topics/expressions binary-operations}@anchor{18b} +@anchor{cp/topics/expressions binary-operations}@anchor{228} @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{123} -@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) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context13new_binary_opE17gcc_jit_binary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{130}@anchor{cp/topics/expressions _CPPv3N6gccjit7context13new_binary_opE17gcc_jit_binary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{229}@anchor{cp/topics/expressions _CPPv2N6gccjit7context13new_binary_opE17gcc_jit_binary_opN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{22a}@anchor{cp/topics/expressions gccjit context new_binary_op__gcc_jit_binary_op gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{22b} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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. Parameter @code{loc} is optional. -This is a thin wrapper around the C API's -@pxref{12,,gcc_jit_context_new_binary_op()} and the available binary +This is a thin wrapper around the C API’s +@ref{12,,gcc_jit_context_new_binary_op()} and the available binary operations are documented there. @end deffn @@ -13699,165 +12624,145 @@ 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{18c} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_plus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context8new_plusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{22c}@anchor{cp/topics/expressions _CPPv3N6gccjit7context8new_plusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{22d}@anchor{cp/topics/expressions _CPPv2N6gccjit7context8new_plusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{22e}@anchor{cp/topics/expressions gccjit context new_plus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{22f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{18d} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{230}@anchor{cp/topics/expressions _CPPv3N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{231}@anchor{cp/topics/expressions _CPPv2N6gccjit7context9new_minusEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{232}@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{233} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{18e} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_mult (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context8new_multEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{234}@anchor{cp/topics/expressions _CPPv3N6gccjit7context8new_multEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{235}@anchor{cp/topics/expressions _CPPv2N6gccjit7context8new_multEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{236}@anchor{cp/topics/expressions gccjit context new_mult__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{237} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{18f} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_divide (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context10new_divideEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{238}@anchor{cp/topics/expressions _CPPv3N6gccjit7context10new_divideEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{239}@anchor{cp/topics/expressions _CPPv2N6gccjit7context10new_divideEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{23a}@anchor{cp/topics/expressions gccjit context new_divide__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{23b} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{190} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_modulo (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context10new_moduloEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{23c}@anchor{cp/topics/expressions _CPPv3N6gccjit7context10new_moduloEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{23d}@anchor{cp/topics/expressions _CPPv2N6gccjit7context10new_moduloEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{23e}@anchor{cp/topics/expressions gccjit context new_modulo__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{23f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{191} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context15new_bitwise_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{240}@anchor{cp/topics/expressions _CPPv3N6gccjit7context15new_bitwise_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{241}@anchor{cp/topics/expressions _CPPv2N6gccjit7context15new_bitwise_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{242}@anchor{cp/topics/expressions gccjit context new_bitwise_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{243} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{192} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_xor (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context15new_bitwise_xorEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{244}@anchor{cp/topics/expressions _CPPv3N6gccjit7context15new_bitwise_xorEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{245}@anchor{cp/topics/expressions _CPPv2N6gccjit7context15new_bitwise_xorEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{246}@anchor{cp/topics/expressions gccjit context new_bitwise_xor__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{247} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{193} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context14new_bitwise_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{248}@anchor{cp/topics/expressions _CPPv3N6gccjit7context14new_bitwise_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{249}@anchor{cp/topics/expressions _CPPv2N6gccjit7context14new_bitwise_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{24a}@anchor{cp/topics/expressions gccjit context new_bitwise_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{24b} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{194} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context15new_logical_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{24c}@anchor{cp/topics/expressions _CPPv3N6gccjit7context15new_logical_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{24d}@anchor{cp/topics/expressions _CPPv2N6gccjit7context15new_logical_andEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{24e}@anchor{cp/topics/expressions gccjit context new_logical_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{24f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{195} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context14new_logical_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{250}@anchor{cp/topics/expressions _CPPv3N6gccjit7context14new_logical_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{251}@anchor{cp/topics/expressions _CPPv2N6gccjit7context14new_logical_orEN6gccjit4typeEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{252}@anchor{cp/topics/expressions gccjit context new_logical_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{253} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{196} -@deffn {C++ Function} gccjit::rvalue operator+ (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4plN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{254}@anchor{cp/topics/expressions _CPPv3plN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{255}@anchor{cp/topics/expressions _CPPv2plN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{256}@anchor{cp/topics/expressions add-operator__gccjit rvalue gccjit rvalue}@anchor{257} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator+ (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue sum = a + b; @end example - -@noindent @end deffn @geindex operator- (C++ function) -@anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{197} -@deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4miN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{258}@anchor{cp/topics/expressions _CPPv3miN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{259}@anchor{cp/topics/expressions _CPPv2miN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{25a}@anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{25b} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator@w{-} (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue diff = a - b; @end example - -@noindent @end deffn @geindex operator* (C++ function) -@anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{198} -@deffn {C++ Function} gccjit::rvalue operator* (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4mlN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{25c}@anchor{cp/topics/expressions _CPPv3mlN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{25d}@anchor{cp/topics/expressions _CPPv2mlN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{25e}@anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{25f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator* (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue prod = a * b; @end example - -@noindent @end deffn @geindex operator/ (C++ function) -@anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{199} -@deffn {C++ Function} gccjit::rvalue operator/ (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4dvN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{260}@anchor{cp/topics/expressions _CPPv3dvN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{261}@anchor{cp/topics/expressions _CPPv2dvN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{262}@anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{263} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator/ (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue result = a / b; @end example - -@noindent @end deffn @geindex operator% (C++ function) -@anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{19a} -@deffn {C++ Function} gccjit::rvalue operator% (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4rmN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{264}@anchor{cp/topics/expressions _CPPv3rmN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{265}@anchor{cp/topics/expressions _CPPv2rmN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{266}@anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{267} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator% (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue mod = a % b; @end example - -@noindent @end deffn @geindex operator& (C++ function) -@anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{19b} -@deffn {C++ Function} gccjit::rvalue operator& (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4anN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{268}@anchor{cp/topics/expressions _CPPv3anN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{269}@anchor{cp/topics/expressions _CPPv2anN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{26a}@anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{26b} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator& (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue x = a & b; @end example - -@noindent @end deffn @geindex operator^ (C++ function) -@anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{19c} -@deffn {C++ Function} gccjit::rvalue operator^ (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4eoN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{26c}@anchor{cp/topics/expressions _CPPv3eoN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{26d}@anchor{cp/topics/expressions _CPPv2eoN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{26e}@anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{26f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator^ (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue x = a ^ b; @end example - -@noindent @end deffn @geindex operator| (C++ function) -@anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{19d} -@deffn {C++ Function} gccjit::rvalue operator| (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4orN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{270}@anchor{cp/topics/expressions _CPPv3orN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{271}@anchor{cp/topics/expressions _CPPv2orN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{272}@anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{273} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator| (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue x = a | b; @end example - -@noindent @end deffn @geindex operator&& (C++ function) -@anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{19e} -@deffn {C++ Function} gccjit::rvalue operator&& (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4aaN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{274}@anchor{cp/topics/expressions _CPPv3aaN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{275}@anchor{cp/topics/expressions _CPPv2aaN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{276}@anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{277} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator&& (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue cond = a && b; @end example - -@noindent @end deffn @geindex operator|| (C++ function) -@anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{19f} -@deffn {C++ Function} gccjit::rvalue operator|| (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4ooN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{278}@anchor{cp/topics/expressions _CPPv3ooN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{279}@anchor{cp/topics/expressions _CPPv2ooN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{27a}@anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{27b} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator|| (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue cond = a || b; @end example - -@noindent @end deffn These can of course be combined, giving a terse way to build compound @@ -13868,25 +12773,23 @@ expressions: @example gccjit::rvalue discriminant = (b * b) - (four * a * c); @end example - -@noindent @end quotation @node Comparisons<2>,Function calls<2>,Binary Operations<2>,Rvalues<2> -@anchor{cp/topics/expressions comparisons}@anchor{1a0} +@anchor{cp/topics/expressions comparisons}@anchor{27c} @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{130} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_comparison (enum gcc_jit_comparison, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context14new_comparisonE18gcc_jit_comparisonN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{142}@anchor{cp/topics/expressions _CPPv3N6gccjit7context14new_comparisonE18gcc_jit_comparisonN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{27d}@anchor{cp/topics/expressions _CPPv2N6gccjit7context14new_comparisonE18gcc_jit_comparisonN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{27e}@anchor{cp/topics/expressions gccjit context new_comparison__gcc_jit_comparison gccjit rvalue gccjit rvalue gccjit location}@anchor{27f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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. Parameter @code{loc} is optional. -This is a thin wrapper around the C API's -@pxref{2c,,gcc_jit_context_new_comparison()} and the available kinds +This is a thin wrapper around the C API’s +@ref{2c,,gcc_jit_context_new_comparison()} and the available kinds of comparison are documented there. @end deffn @@ -13894,113 +12797,101 @@ 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{1a1} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_eq (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_eqEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{280}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_eqEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{281}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_eqEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{282}@anchor{cp/topics/expressions gccjit context new_eq__gccjit rvalue gccjit rvalue gccjit location}@anchor{283} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{1a2} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_ne (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_neEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{284}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_neEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{285}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_neEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{286}@anchor{cp/topics/expressions gccjit context new_ne__gccjit rvalue gccjit rvalue gccjit location}@anchor{287} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{1a3} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_lt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_ltEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{288}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_ltEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{289}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_ltEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{28a}@anchor{cp/topics/expressions gccjit context new_lt__gccjit rvalue gccjit rvalue gccjit location}@anchor{28b} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{1a4} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_le (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_leEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{28c}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_leEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{28d}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_leEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{28e}@anchor{cp/topics/expressions gccjit context new_le__gccjit rvalue gccjit rvalue gccjit location}@anchor{28f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{1a5} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_gt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_gtEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{290}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_gtEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{291}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_gtEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{292}@anchor{cp/topics/expressions gccjit context new_gt__gccjit rvalue gccjit rvalue gccjit location}@anchor{293} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{1a6} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_ge (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context6new_geEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{294}@anchor{cp/topics/expressions _CPPv3N6gccjit7context6new_geEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{295}@anchor{cp/topics/expressions _CPPv2N6gccjit7context6new_geEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{296}@anchor{cp/topics/expressions gccjit context new_ge__gccjit rvalue gccjit rvalue gccjit location}@anchor{297} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,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{1a7} -@deffn {C++ Function} gccjit::rvalue operator== (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4eqN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{298}@anchor{cp/topics/expressions _CPPv3eqN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{299}@anchor{cp/topics/expressions _CPPv2eqN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{29a}@anchor{cp/topics/expressions eq-operator__gccjit rvalue gccjit rvalue}@anchor{29b} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator== (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue cond = (a == ctxt.zero (t_int)); @end example - -@noindent @end deffn @geindex operator!= (C++ function) -@anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{1a8} -@deffn {C++ Function} gccjit::rvalue operator!= (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4neN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{29c}@anchor{cp/topics/expressions _CPPv3neN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{29d}@anchor{cp/topics/expressions _CPPv2neN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{29e}@anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{29f} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator!= (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue cond = (i != j); @end example - -@noindent @end deffn @geindex operator< (C++ function) -@anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{1a9} -@deffn {C++ Function} gccjit::rvalue operator< (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4ltN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a0}@anchor{cp/topics/expressions _CPPv3ltN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a1}@anchor{cp/topics/expressions _CPPv2ltN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a2}@anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{2a3} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator< (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue cond = i < n; @end example - -@noindent @end deffn @geindex operator<= (C++ function) -@anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{1aa} -@deffn {C++ Function} gccjit::rvalue operator<= (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4leN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a4}@anchor{cp/topics/expressions _CPPv3leN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a5}@anchor{cp/topics/expressions _CPPv2leN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a6}@anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{2a7} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator<= (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue cond = i <= n; @end example - -@noindent @end deffn @geindex operator> (C++ function) -@anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{1ab} -@deffn {C++ Function} gccjit::rvalue operator> (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4gtN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a8}@anchor{cp/topics/expressions _CPPv3gtN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2a9}@anchor{cp/topics/expressions _CPPv2gtN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2aa}@anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{2ab} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator> (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue cond = (ch > limit); @end example - -@noindent @end deffn @geindex operator>= (C++ function) -@anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{1ac} -@deffn {C++ Function} gccjit::rvalue operator>= (gccjit::rvalue a, gccjit::rvalue b) +@anchor{cp/topics/expressions _CPPv4geN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ac}@anchor{cp/topics/expressions _CPPv3geN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ad}@anchor{cp/topics/expressions _CPPv2geN6gccjit6rvalueEN6gccjit6rvalueE}@anchor{2ae}@anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{2af} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} operator>= (gccjit::rvalue a, gccjit::rvalue b) @example gccjit::rvalue cond = (score >= ctxt.new_rvalue (t_int, 100)); @end example - -@noindent @end deffn @c TODO: beyond this point @node Function calls<2>,Function pointers<3>,Comparisons<2>,Rvalues<2> -@anchor{cp/topics/expressions function-calls}@anchor{1ad} +@anchor{cp/topics/expressions function-calls}@anchor{2b0} @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{1ae} -@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) +@anchor{cp/topics/expressions _CPPv424gcc_jit_context_new_callP15gcc_jit_contextP16gcc_jit_locationP16gcc_jit_functioniPP14gcc_jit_rvalue}@anchor{2b1}@anchor{cp/topics/expressions _CPPv324gcc_jit_context_new_callP15gcc_jit_contextP16gcc_jit_locationP16gcc_jit_functioniPP14gcc_jit_rvalue}@anchor{2b2}@anchor{cp/topics/expressions _CPPv224gcc_jit_context_new_callP15gcc_jit_contextP16gcc_jit_locationP16gcc_jit_functioniPP14gcc_jit_rvalue}@anchor{2b3}@anchor{cp/topics/expressions gcc_jit_context_new_call__gcc_jit_contextP gcc_jit_locationP gcc_jit_functionP i gcc_jit_rvaluePP}@anchor{2b4} +@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 call to the function, with the result as an rvalue. @@ -14008,46 +12899,44 @@ call to the function, with the result as an rvalue. @cartouche @quotation Note @code{gccjit::context::new_call()} merely builds a -@pxref{179,,gccjit;;rvalue} i.e. an expression that can be evaluated, +@ref{131,,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 +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{1af,,gccjit;;block;;add_eval()}: +@ref{2b5,,gccjit;;block;;add_eval()}: @example /* Add "(void)printf (arg0, arg1);". */ block.add_eval (ctxt.new_call (printf_func, arg0, arg1)); @end example - -@noindent @end quotation @end cartouche @end deffn @node Function pointers<3>,Type-coercion<2>,Function calls<2>,Rvalues<2> -@anchor{cp/topics/expressions function-pointers}@anchor{1b0} +@anchor{cp/topics/expressions function-pointers}@anchor{2b6} @subsubsection Function pointers @geindex gccjit;;function;;get_address (C++ function) -@anchor{cp/topics/expressions gccjit function get_address__gccjit location}@anchor{1b1} -@deffn {C++ Function} gccjit::rvalue gccjit::function::get_address (gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit8function11get_addressEN6gccjit8locationE}@anchor{2b7}@anchor{cp/topics/expressions _CPPv3N6gccjit8function11get_addressEN6gccjit8locationE}@anchor{2b8}@anchor{cp/topics/expressions _CPPv2N6gccjit8function11get_addressEN6gccjit8locationE}@anchor{2b9}@anchor{cp/topics/expressions gccjit function get_address__gccjit location}@anchor{2ba} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{13f,,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<3>,Rvalues<2> -@anchor{cp/topics/expressions type-coercion}@anchor{1b2} +@anchor{cp/topics/expressions type-coercion}@anchor{2bb} @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{1b3} -@deffn {C++ Function} gccjit::rvalue gccjit::context::new_cast (gccjit::rvalue rvalue, gccjit::type type, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context8new_castEN6gccjit6rvalueEN6gccjit4typeEN6gccjit8locationE}@anchor{2bc}@anchor{cp/topics/expressions _CPPv3N6gccjit7context8new_castEN6gccjit6rvalueEN6gccjit4typeEN6gccjit8locationE}@anchor{2bd}@anchor{cp/topics/expressions _CPPv2N6gccjit7context8new_castEN6gccjit6rvalueEN6gccjit4typeEN6gccjit8locationE}@anchor{2be}@anchor{cp/topics/expressions gccjit context new_cast__gccjit rvalue gccjit type gccjit location}@anchor{2bf} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{128,,context}::new_cast (gccjit::rvalue rvalue, gccjit::type type, gccjit::location loc) Given an rvalue of T, construct another rvalue of another type. @@ -14071,25 +12960,25 @@ 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{1b4} +@anchor{cp/topics/expressions lvalues}@anchor{2c0} @subsubsection Lvalues @geindex gccjit;;lvalue (C++ class) -@anchor{cp/topics/expressions gccjit lvalue}@anchor{1b5} +@anchor{cp/topics/expressions _CPPv4N6gccjit6lvalueE}@anchor{13a}@anchor{cp/topics/expressions _CPPv3N6gccjit6lvalueE}@anchor{2c1}@anchor{cp/topics/expressions _CPPv2N6gccjit6lvalueE}@anchor{2c2}@anchor{cp/topics/expressions gccjit lvalue}@anchor{2c3} @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{179,,gccjit;;rvalue}, where the rvalue is computed by reading from the +@ref{131,,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. +It iss a thin wrapper around @ref{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{1b6} -@deffn {C++ Function} gccjit::rvalue gccjit::lvalue::get_address (gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit6lvalue11get_addressEN6gccjit8locationE}@anchor{2c4}@anchor{cp/topics/expressions _CPPv3N6gccjit6lvalue11get_addressEN6gccjit8locationE}@anchor{2c5}@anchor{cp/topics/expressions _CPPv2N6gccjit6lvalue11get_addressEN6gccjit8locationE}@anchor{2c6}@anchor{cp/topics/expressions gccjit lvalue get_address__gccjit location}@anchor{2c7} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{13a,,lvalue}::get_address (gccjit::location loc) Take the address of an lvalue; analogous to: @@ -14097,11 +12986,9 @@ Take the address of an lvalue; analogous to: &(EXPR) @end example -@noindent - in C. -Parameter "loc" is optional. +Parameter “loc” is optional. @end deffn @menu @@ -14110,28 +12997,28 @@ Parameter "loc" is optional. @end menu @node Global variables<2>,,,Lvalues<2> -@anchor{cp/topics/expressions global-variables}@anchor{1b7} +@anchor{cp/topics/expressions global-variables}@anchor{2c8} @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{1b8} -@deffn {C++ Function} gccjit::lvalue gccjit::context::new_global (enum gcc_jit_global_kind, gccjit::type type, const char* name, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context10new_globalE19gcc_jit_global_kindN6gccjit4typeEPKcN6gccjit8locationE}@anchor{2c9}@anchor{cp/topics/expressions _CPPv3N6gccjit7context10new_globalE19gcc_jit_global_kindN6gccjit4typeEPKcN6gccjit8locationE}@anchor{2ca}@anchor{cp/topics/expressions _CPPv2N6gccjit7context10new_globalE19gcc_jit_global_kindN6gccjit4typeEPKcN6gccjit8locationE}@anchor{2cb}@anchor{cp/topics/expressions gccjit context new_global__gcc_jit_global_kind gccjit type cCP gccjit location}@anchor{2cc} +@deffn {C++ Function} gccjit::@ref{13a,,lvalue} gccjit::@ref{128,,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{c4,,gcc_jit_context_new_global()} from -the C API; the "kind" parameter has the same meaning as there. +This is a thin wrapper around @ref{c7,,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{1b9} +@anchor{cp/topics/expressions working-with-pointers-structs-and-unions}@anchor{2cd} @subsubsection Working with pointers, structs and unions @geindex gccjit;;rvalue;;dereference (C++ function) -@anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{1ba} -@deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference (gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit6rvalue11dereferenceEN6gccjit8locationE}@anchor{2ce}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalue11dereferenceEN6gccjit8locationE}@anchor{2cf}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalue11dereferenceEN6gccjit8locationE}@anchor{2d0}@anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{2d1} +@deffn {C++ Function} gccjit::@ref{13a,,lvalue} gccjit::@ref{131,,rvalue}::dereference (gccjit::location loc) Given an rvalue of pointer type @code{T *}, dereferencing the pointer, getting an lvalue of type @code{T}. Analogous to: @@ -14140,48 +13027,42 @@ getting an lvalue of type @code{T}. Analogous to: *(EXPR) @end example -@noindent - in C. -Parameter "loc" is optional. +Parameter “loc” is optional. @end deffn -If you don't need to specify the location, this can also be expressed using +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{1bb} -@deffn {C++ Function} gccjit::lvalue gccjit::rvalue::operator* () +@anchor{cp/topics/expressions _CPPv4N6gccjit6rvaluemlEv}@anchor{2d2}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvaluemlEv}@anchor{2d3}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvaluemlEv}@anchor{2d4}@anchor{cp/topics/expressions gccjit rvalue mul-operator}@anchor{2d5} +@deffn {C++ Function} gccjit::@ref{13a,,lvalue} gccjit::@ref{131,,rvalue}::operator* () @example gccjit::lvalue content = *ptr; @end example - -@noindent @end deffn 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{1bc} -@deffn {C++ Function} gccjit::lvalue gccjit::lvalue::access_field (gccjit::field field, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit6lvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{2d6}@anchor{cp/topics/expressions _CPPv3N6gccjit6lvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{2d7}@anchor{cp/topics/expressions _CPPv2N6gccjit6lvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{2d8}@anchor{cp/topics/expressions gccjit lvalue access_field__gccjit field gccjit location}@anchor{2d9} +@deffn {C++ Function} gccjit::@ref{13a,,lvalue} gccjit::@ref{13a,,lvalue}::access_field (gccjit::field field, gccjit::location loc) Given an lvalue of struct or union type, access the given field, -getting an lvalue of the field's type. Analogous to: +getting an lvalue of the field’s type. Analogous to: @example (EXPR).field = ...; @end example -@noindent - in C. @end deffn @geindex gccjit;;rvalue;;access_field (C++ function) -@anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{1bd} -@deffn {C++ Function} gccjit::rvalue gccjit::rvalue::access_field (gccjit::field field, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit6rvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{2da}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{2db}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalue12access_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{2dc}@anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{2dd} +@deffn {C++ Function} gccjit::@ref{131,,rvalue} gccjit::@ref{131,,rvalue}::access_field (gccjit::field field, gccjit::location loc) Given an rvalue of struct or union type, access the given field as an rvalue. Analogous to: @@ -14190,14 +13071,12 @@ as an rvalue. Analogous to: (EXPR).field @end example -@noindent - in C. @end deffn @geindex gccjit;;rvalue;;dereference_field (C++ function) -@anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{1be} -@deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference_field (gccjit::field field, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit6rvalue17dereference_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{2de}@anchor{cp/topics/expressions _CPPv3N6gccjit6rvalue17dereference_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{2df}@anchor{cp/topics/expressions _CPPv2N6gccjit6rvalue17dereference_fieldEN6gccjit5fieldEN6gccjit8locationE}@anchor{2e0}@anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{2e1} +@deffn {C++ Function} gccjit::@ref{13a,,lvalue} gccjit::@ref{131,,rvalue}::dereference_field (gccjit::field field, gccjit::location loc) Given an rvalue of pointer type @code{T *} where T is of struct or union type, access the given field as an lvalue. Analogous to: @@ -14206,14 +13085,12 @@ type, access the given field as an lvalue. Analogous to: (EXPR)->field @end example -@noindent - 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{1bf} -@deffn {C++ Function} gccjit::lvalue gccjit::context::new_array_access (gccjit::rvalue ptr, gccjit::rvalue index, gccjit::location loc) +@anchor{cp/topics/expressions _CPPv4N6gccjit7context16new_array_accessEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2e2}@anchor{cp/topics/expressions _CPPv3N6gccjit7context16new_array_accessEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2e3}@anchor{cp/topics/expressions _CPPv2N6gccjit7context16new_array_accessEN6gccjit6rvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2e4}@anchor{cp/topics/expressions gccjit context new_array_access__gccjit rvalue gccjit rvalue gccjit location}@anchor{2e5} +@deffn {C++ Function} gccjit::@ref{13a,,lvalue} gccjit::@ref{128,,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 the given index, using standard C array indexing rules i.e. each @@ -14224,14 +13101,12 @@ Analogous to: PTR[INDEX] @end example -@noindent - in C (or, indeed, to @code{PTR + INDEX}). -Parameter "loc" is optional. +Parameter “loc” is optional. @end deffn -For array accesses where you don't need to specify a @pxref{153,,gccjit;;location}, +For array accesses where you don’t need to specify a @ref{14e,,gccjit;;location}, two overloaded operators are available: @quotation @@ -14242,15 +13117,11 @@ gccjit::lvalue gccjit::rvalue::operator[] (gccjit::rvalue index) gccjit::lvalue element = array[idx]; @end example -@noindent - gccjit::lvalue gccjit::rvalue::operator[] (int index) @example gccjit::lvalue element = array[0]; @end example - -@noindent @end quotation @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @@ -14271,7 +13142,7 @@ gccjit::lvalue element = array[0]; @c <http://www.gnu.org/licenses/>. @node Creating and using functions<2>,Source Locations<2>,Expressions<2>,Topic Reference<2> -@anchor{cp/topics/functions doc}@anchor{1c0}@anchor{cp/topics/functions creating-and-using-functions}@anchor{1c1} +@anchor{cp/topics/functions doc}@anchor{2e6}@anchor{cp/topics/functions creating-and-using-functions}@anchor{2e7} @subsection Creating and using functions @@ -14284,97 +13155,97 @@ gccjit::lvalue element = array[0]; @end menu @node Params<2>,Functions<2>,,Creating and using functions<2> -@anchor{cp/topics/functions params}@anchor{1c2} +@anchor{cp/topics/functions params}@anchor{2e8} @subsubsection Params @geindex gccjit;;param (C++ class) -@anchor{cp/topics/functions gccjit param}@anchor{1c3} +@anchor{cp/topics/functions _CPPv4N6gccjit5paramE}@anchor{13b}@anchor{cp/topics/functions _CPPv3N6gccjit5paramE}@anchor{2e9}@anchor{cp/topics/functions _CPPv2N6gccjit5paramE}@anchor{2ea}@anchor{cp/topics/functions gccjit param}@anchor{2eb} @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{122} -@deffn {C++ Function} gccjit::param gccjit::context::new_param (gccjit::type type, const char* name, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit7context9new_paramEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{12f}@anchor{cp/topics/functions _CPPv3N6gccjit7context9new_paramEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{2ec}@anchor{cp/topics/functions _CPPv2N6gccjit7context9new_paramEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{2ed}@anchor{cp/topics/functions gccjit context new_param__gccjit type cCP gccjit location}@anchor{2ee} +@deffn {C++ Function} gccjit::@ref{13b,,param} gccjit::@ref{128,,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{1c3,,gccjit;;param} is a subclass of @pxref{1b5,,gccjit;;lvalue} (and thus -of @pxref{179,,gccjit;;rvalue} and @pxref{160,,gccjit;;object}). It is a thin -wrapper around the C API's @pxref{25,,gcc_jit_param *}. +@ref{13b,,gccjit;;param} is a subclass of @ref{13a,,gccjit;;lvalue} (and thus +of @ref{131,,gccjit;;rvalue} and @ref{12d,,gccjit;;object}). It is a thin +wrapper around the C API’s @ref{25,,gcc_jit_param *}. @node Functions<2>,Blocks<2>,Params<2>,Creating and using functions<2> -@anchor{cp/topics/functions functions}@anchor{1c4} +@anchor{cp/topics/functions functions}@anchor{2ef} @subsubsection Functions @geindex gccjit;;function (C++ class) -@anchor{cp/topics/functions gccjit function}@anchor{1c5} +@anchor{cp/topics/functions _CPPv4N6gccjit8functionE}@anchor{13f}@anchor{cp/topics/functions _CPPv3N6gccjit8functionE}@anchor{2f0}@anchor{cp/topics/functions _CPPv2N6gccjit8functionE}@anchor{2f1}@anchor{cp/topics/functions gccjit function}@anchor{2f2} @deffn {C++ Class} gccjit::function -A @cite{gccjit::function} represents a function - either one that we're -creating ourselves, or one that we're referencing. +A @cite{gccjit::function} represents a function - either one that we’re +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{1c6} -@deffn {C++ Function} gccjit::function gccjit::context::new_function (enum gcc_jit_function_kind, gccjit::type return_type, const char* name, std::vector<param>& params, int is_variadic, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit7context12new_functionE21gcc_jit_function_kindN6gccjit4typeEPKcRNSt6vectorI5paramEEiN6gccjit8locationE}@anchor{2f3}@anchor{cp/topics/functions _CPPv3N6gccjit7context12new_functionE21gcc_jit_function_kindN6gccjit4typeEPKcRNSt6vectorI5paramEEiN6gccjit8locationE}@anchor{2f4}@anchor{cp/topics/functions _CPPv2N6gccjit7context12new_functionE21gcc_jit_function_kindN6gccjit4typeEPKcRNSt6vectorI5paramEEiN6gccjit8locationE}@anchor{2f5}@anchor{cp/topics/functions gccjit context new_function__gcc_jit_function_kind gccjit type cCP std vector param R i gccjit location}@anchor{2f6} +@deffn {C++ Function} gccjit::@ref{13f,,function} gccjit::@ref{128,,context}::new_function (enum gcc_jit_function_kind, gccjit::type return_type, const char *name, std::vector<param> ¶ms, int is_variadic, gccjit::location loc) Create a gcc_jit_function with the given name and parameters. -Parameters "is_variadic" and "loc" are optional. +Parameters “is_variadic” and “loc” are optional. -This is a wrapper around the C API's @pxref{11,,gcc_jit_context_new_function()}. +This is a wrapper around the C API’s @ref{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{1c7} -@deffn {C++ Function} gccjit::function gccjit::context::get_builtin_function (const char* name) +@anchor{cp/topics/functions _CPPv4N6gccjit7context20get_builtin_functionEPKc}@anchor{2f7}@anchor{cp/topics/functions _CPPv3N6gccjit7context20get_builtin_functionEPKc}@anchor{2f8}@anchor{cp/topics/functions _CPPv2N6gccjit7context20get_builtin_functionEPKc}@anchor{2f9}@anchor{cp/topics/functions gccjit context get_builtin_function__cCP}@anchor{2fa} +@deffn {C++ Function} gccjit::@ref{13f,,function} gccjit::@ref{128,,context}::get_builtin_function (const char *name) -This is a wrapper around the C API's -@pxref{db,,gcc_jit_context_get_builtin_function()}. +This is a wrapper around the C API’s +@ref{de,,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{1c8} -@deffn {C++ Function} gccjit::param gccjit::function::get_param (int index) const +@anchor{cp/topics/functions _CPPv4NK6gccjit8function9get_paramEi}@anchor{2fb}@anchor{cp/topics/functions _CPPv3NK6gccjit8function9get_paramEi}@anchor{2fc}@anchor{cp/topics/functions _CPPv2NK6gccjit8function9get_paramEi}@anchor{2fd}@anchor{cp/topics/functions gccjit function get_param__iC}@anchor{2fe} +@deffn {C++ Function} gccjit::@ref{13b,,param} gccjit::@ref{13f,,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{135} -@deffn {C++ Function} void gccjit::function::dump_to_dot (const char* path) +@anchor{cp/topics/functions _CPPv4N6gccjit8function11dump_to_dotEPKc}@anchor{147}@anchor{cp/topics/functions _CPPv3N6gccjit8function11dump_to_dotEPKc}@anchor{2ff}@anchor{cp/topics/functions _CPPv2N6gccjit8function11dump_to_dotEPKc}@anchor{300}@anchor{cp/topics/functions gccjit function dump_to_dot__cCP}@anchor{301} +@deffn {C++ Function} void gccjit::@ref{13f,,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{12c} -@deffn {C++ Function} gccjit::lvalue gccjit::function::new_local (gccjit::type type, const char* name, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit8function9new_localEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{13c}@anchor{cp/topics/functions _CPPv3N6gccjit8function9new_localEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{302}@anchor{cp/topics/functions _CPPv2N6gccjit8function9new_localEN6gccjit4typeEPKcN6gccjit8locationE}@anchor{303}@anchor{cp/topics/functions gccjit function new_local__gccjit type cCP gccjit location}@anchor{304} +@deffn {C++ Function} gccjit::@ref{13a,,lvalue} gccjit::@ref{13f,,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 name. @end deffn @node Blocks<2>,Statements<2>,Functions<2>,Creating and using functions<2> -@anchor{cp/topics/functions blocks}@anchor{1c9} +@anchor{cp/topics/functions blocks}@anchor{305} @subsubsection Blocks @geindex gccjit;;block (C++ class) -@anchor{cp/topics/functions gccjit block}@anchor{1ca} +@anchor{cp/topics/functions _CPPv4N6gccjit5blockE}@anchor{13e}@anchor{cp/topics/functions _CPPv3N6gccjit5blockE}@anchor{306}@anchor{cp/topics/functions _CPPv2N6gccjit5blockE}@anchor{307}@anchor{cp/topics/functions gccjit block}@anchor{308} @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{1ca,,gccjit;;block} is a subclass of @pxref{160,,gccjit;;object}. +@ref{13e,,gccjit;;block} is a subclass of @ref{12d,,gccjit;;object}. The first basic block that you create within a function will be the entrypoint. @@ -14383,13 +13254,13 @@ Each basic block that you create within a function must be terminated, either with a conditional, a jump, a return, or a switch. -It's legal to have multiple basic blocks that return within +It’s legal to have multiple basic blocks that return within one function. @end deffn @geindex gccjit;;function;;new_block (C++ function) -@anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{1cb} -@deffn {C++ Function} gccjit::block gccjit::function::new_block (const char* name) +@anchor{cp/topics/functions _CPPv4N6gccjit8function9new_blockEPKc}@anchor{309}@anchor{cp/topics/functions _CPPv3N6gccjit8function9new_blockEPKc}@anchor{30a}@anchor{cp/topics/functions _CPPv2N6gccjit8function9new_blockEPKc}@anchor{30b}@anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{30c} +@deffn {C++ Function} gccjit::@ref{13e,,block} gccjit::@ref{13f,,function}::new_block (const char *name) Create a basic block of the given name. The name may be NULL, but providing meaningful names is often helpful when debugging: it may @@ -14398,29 +13269,27 @@ messages. @end deffn @node Statements<2>,,Blocks<2>,Creating and using functions<2> -@anchor{cp/topics/functions statements}@anchor{1cc} +@anchor{cp/topics/functions statements}@anchor{30d} @subsubsection Statements @geindex gccjit;;block;;add_eval (C++ function) -@anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{1af} -@deffn {C++ Function} void gccjit::block::add_eval (gccjit::rvalue rvalue, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit5block8add_evalEN6gccjit6rvalueEN6gccjit8locationE}@anchor{2b5}@anchor{cp/topics/functions _CPPv3N6gccjit5block8add_evalEN6gccjit6rvalueEN6gccjit8locationE}@anchor{30e}@anchor{cp/topics/functions _CPPv2N6gccjit5block8add_evalEN6gccjit6rvalueEN6gccjit8locationE}@anchor{30f}@anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{310} +@deffn {C++ Function} void gccjit::@ref{13e,,block}::add_eval (gccjit::rvalue rvalue, gccjit::location loc) Add evaluation of an rvalue, discarding the result -(e.g. a function call that "returns" void). +(e.g. a function call that “returns” void). This is equivalent to this C code: @example (void)expression; @end example - -@noindent @end deffn @geindex gccjit;;block;;add_assignment (C++ function) -@anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{12e} -@deffn {C++ Function} void gccjit::block::add_assignment (gccjit::lvalue lvalue, gccjit::rvalue rvalue, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit5block14add_assignmentEN6gccjit6lvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{140}@anchor{cp/topics/functions _CPPv3N6gccjit5block14add_assignmentEN6gccjit6lvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{311}@anchor{cp/topics/functions _CPPv2N6gccjit5block14add_assignmentEN6gccjit6lvalueEN6gccjit6rvalueEN6gccjit8locationE}@anchor{312}@anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{313} +@deffn {C++ Function} void gccjit::@ref{13e,,block}::add_assignment (gccjit::lvalue lvalue, gccjit::rvalue rvalue, gccjit::location loc) Add evaluation of an rvalue, assigning the result to the given lvalue. @@ -14430,18 +13299,16 @@ This is roughly equivalent to this C code: @example lvalue = rvalue; @end example - -@noindent @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{132} -@deffn {C++ Function} void gccjit::block::add_assignment_op (gccjit::lvalue lvalue, enum gcc_jit_binary_op, gccjit::rvalue rvalue, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit5block17add_assignment_opEN6gccjit6lvalueE17gcc_jit_binary_opN6gccjit6rvalueEN6gccjit8locationE}@anchor{144}@anchor{cp/topics/functions _CPPv3N6gccjit5block17add_assignment_opEN6gccjit6lvalueE17gcc_jit_binary_opN6gccjit6rvalueEN6gccjit8locationE}@anchor{314}@anchor{cp/topics/functions _CPPv2N6gccjit5block17add_assignment_opEN6gccjit6lvalueE17gcc_jit_binary_opN6gccjit6rvalueEN6gccjit8locationE}@anchor{315}@anchor{cp/topics/functions gccjit block add_assignment_op__gccjit lvalue gcc_jit_binary_op gccjit rvalue gccjit location}@anchor{316} +@deffn {C++ Function} void gccjit::@ref{13e,,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 lvalue. -This is analogous to "+=" and friends: +This is analogous to “+=” and friends: @example lvalue += rvalue; @@ -14449,8 +13316,6 @@ lvalue *= rvalue; lvalue /= rvalue; @end example -@noindent - etc. For example: @example @@ -14460,27 +13325,25 @@ loop_body.add_assignment_op ( GCC_JIT_BINARY_OP_PLUS, ctxt.one (int_type)); @end example - -@noindent @end deffn @geindex gccjit;;block;;add_comment (C++ function) -@anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{13d} -@deffn {C++ Function} void gccjit::block::add_comment (const char* text, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit5block11add_commentEPKcN6gccjit8locationE}@anchor{150}@anchor{cp/topics/functions _CPPv3N6gccjit5block11add_commentEPKcN6gccjit8locationE}@anchor{317}@anchor{cp/topics/functions _CPPv2N6gccjit5block11add_commentEPKcN6gccjit8locationE}@anchor{318}@anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{319} +@deffn {C++ Function} void gccjit::@ref{13e,,block}::add_comment (const char *text, gccjit::location loc) Add a no-op textual comment to the internal representation of the code. It will be optimized away, but will be visible in the dumps -seen via @pxref{66,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE} -and @pxref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE}, -and thus may be of use when debugging how your project's internal +seen via @ref{66,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE} +and @ref{1c,,GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE}, +and thus may be of use when debugging how your project’s internal representation gets converted to the libgccjit IR. -Parameter "loc" is optional. +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{131} -@deffn {C++ Function} void gccjit::block::end_with_conditional (gccjit::rvalue boolval, gccjit::block on_true, gccjit::block on_false, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit5block20end_with_conditionalEN6gccjit6rvalueEN6gccjit5blockEN6gccjit5blockEN6gccjit8locationE}@anchor{143}@anchor{cp/topics/functions _CPPv3N6gccjit5block20end_with_conditionalEN6gccjit6rvalueEN6gccjit5blockEN6gccjit5blockEN6gccjit8locationE}@anchor{31a}@anchor{cp/topics/functions _CPPv2N6gccjit5block20end_with_conditionalEN6gccjit6rvalueEN6gccjit5blockEN6gccjit5blockEN6gccjit8locationE}@anchor{31b}@anchor{cp/topics/functions gccjit block end_with_conditional__gccjit rvalue gccjit block gccjit block gccjit location}@anchor{31c} +@deffn {C++ Function} void gccjit::@ref{13e,,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 result to the appropriate successor block. @@ -14494,14 +13357,12 @@ else goto on_false; @end example -@noindent - 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{1cd} -@deffn {C++ Function} void gccjit::block::end_with_jump (gccjit::block target, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit5block13end_with_jumpEN6gccjit5blockEN6gccjit8locationE}@anchor{31d}@anchor{cp/topics/functions _CPPv3N6gccjit5block13end_with_jumpEN6gccjit5blockEN6gccjit8locationE}@anchor{31e}@anchor{cp/topics/functions _CPPv2N6gccjit5block13end_with_jumpEN6gccjit5blockEN6gccjit8locationE}@anchor{31f}@anchor{cp/topics/functions gccjit block end_with_jump__gccjit block gccjit location}@anchor{320} +@deffn {C++ Function} void gccjit::@ref{13e,,block}::end_with_jump (gccjit::block target, gccjit::location loc) Terminate a block by adding a jump to the given target block. @@ -14510,20 +13371,18 @@ This is roughly equivalent to this C code: @example goto target; @end example - -@noindent @end deffn @geindex gccjit;;block;;end_with_return (C++ function) -@anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{1ce} -@deffn {C++ Function} void gccjit::block::end_with_return (gccjit::rvalue rvalue, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit5block15end_with_returnEN6gccjit6rvalueEN6gccjit8locationE}@anchor{321}@anchor{cp/topics/functions _CPPv3N6gccjit5block15end_with_returnEN6gccjit6rvalueEN6gccjit8locationE}@anchor{322}@anchor{cp/topics/functions _CPPv2N6gccjit5block15end_with_returnEN6gccjit6rvalueEN6gccjit8locationE}@anchor{323}@anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{324} +@deffn {C++ Function} void gccjit::@ref{13e,,block}::end_with_return (gccjit::rvalue rvalue, gccjit::location loc) Terminate a block. Both params are optional. An rvalue must be provided for a function returning non-void, and -must not be provided by a function "returning" @cite{void}. +must not be provided by a function “returning” @cite{void}. If an rvalue is provided, the block is terminated by evaluating the rvalue and returning the value. @@ -14534,23 +13393,19 @@ This is roughly equivalent to this C code: return expression; @end example -@noindent - If an rvalue is not provided, the block is terminated by adding a -valueless return, for use within a function with "void" return type. +valueless return, for use within a function with “void” return type. This is equivalent to this C code: @example return; @end example - -@noindent @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{1cf} -@deffn {C++ Function} void gccjit::block::end_with_switch (gccjit::rvalue expr, gccjit::block default_block, std::vector<gccjit::case_> cases, gccjit::location loc) +@anchor{cp/topics/functions _CPPv4N6gccjit5block15end_with_switchEN6gccjit6rvalueEN6gccjit5blockENSt6vectorIN6gccjit5case_EEEN6gccjit8locationE}@anchor{325}@anchor{cp/topics/functions _CPPv3N6gccjit5block15end_with_switchEN6gccjit6rvalueEN6gccjit5blockENSt6vectorIN6gccjit5case_EEEN6gccjit8locationE}@anchor{326}@anchor{cp/topics/functions _CPPv2N6gccjit5block15end_with_switchEN6gccjit6rvalueEN6gccjit5blockENSt6vectorIN6gccjit5case_EEEN6gccjit8locationE}@anchor{327}@anchor{cp/topics/functions gccjit block end_with_switch__gccjit rvalue gccjit block std vector gccjit case_ gccjit location}@anchor{328} +@deffn {C++ Function} void gccjit::@ref{13e,,block}::end_with_switch (gccjit::rvalue expr, gccjit::block default_block, std::vector<gccjit::case_> cases, gccjit::location loc) Terminate a block by adding evalation of an rvalue, then performing a multiway branch. @@ -14576,8 +13431,6 @@ switch (expr) @} @end example -@noindent - @code{expr} must be of the same integer type as all of the @code{min_value} and @code{max_value} within the cases. @@ -14592,49 +13445,30 @@ The API entrypoints relating to switch statements and cases: @itemize * @item -@pxref{1cf,,gccjit;;block;;end_with_switch()} +@ref{325,,gccjit;;block;;end_with_switch()} @item -@pxref{1d0,,gccjit;;context;;new_case()} +@code{gccjit::context::new_case()} @end itemize @end quotation -were added in @pxref{e9,,LIBGCCJIT_ABI_3}; you can test for their presence +were added in @ref{ec,,LIBGCCJIT_ABI_3}; you can test for their presence using @example #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS @end example -@noindent - -@geindex gccjit;;block;;end_with_switch;;gccjit;;case_ (C++ class) -@anchor{cp/topics/functions gccjit block end_with_switch gccjit case_}@anchor{1d1} -@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{14b,,gccjit;;context} using -@pxref{1d0,,gccjit;;context;;new_case()}. It is a subclass of -@pxref{160,,gccjit;;object}. +is created within a particular @ref{128,,gccjit;;context} using +@code{gccjit::context::new_case()}. It is a subclass of +@ref{12d,,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{1d0} -@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. -@cite{min_value} and @cite{max_value} must be constants of an integer type, -which must match that of the expression of the switch statement. - -@cite{dest_block} must be within the same function as the switch -statement. -@end deffn - -Here's an example of creating a switch statement: +Here’s an example of creating a switch statement: @quotation @@ -14709,10 +13543,7 @@ create_code (gcc_jit_context *c_ctxt, void *user_data) b_default.end_with_return (ctxt.new_rvalue (t_int, 10)); @} - @end example - -@noindent @end quotation @end deffn @@ -14734,12 +13565,12 @@ create_code (gcc_jit_context *c_ctxt, void *user_data) @c <http://www.gnu.org/licenses/>. @node Source Locations<2>,Compiling a context<2>,Creating and using functions<2>,Topic Reference<2> -@anchor{cp/topics/locations source-locations}@anchor{1d2}@anchor{cp/topics/locations doc}@anchor{1d3} +@anchor{cp/topics/locations doc}@anchor{329}@anchor{cp/topics/locations source-locations}@anchor{32a} @subsection Source Locations @geindex gccjit;;location (C++ class) -@anchor{cp/topics/locations gccjit location}@anchor{153} +@anchor{cp/topics/locations _CPPv4N6gccjit8locationE}@anchor{14e}@anchor{cp/topics/locations _CPPv3N6gccjit8locationE}@anchor{32b}@anchor{cp/topics/locations _CPPv2N6gccjit8locationE}@anchor{32c}@anchor{cp/topics/locations gccjit location}@anchor{32d} @deffn {C++ Class} gccjit::location A @cite{gccjit::location} encapsulates a source code location, so that @@ -14750,22 +13581,20 @@ 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{141,,gccjit;;context;;new_location()}. +You can construct them using @ref{154,,gccjit;;context;;new_location()}. -You need to enable @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the -@pxref{14b,,gccjit;;context} for these locations to actually be usable by +You need to enable @ref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the +@ref{128,,gccjit;;context} for these locations to actually be usable by the debugger: @example ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1); @end example - -@noindent @end deffn @geindex gccjit;;context;;new_location (C++ function) -@anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{141} -@deffn {C++ Function} gccjit::location gccjit::context::new_location (const char* filename, int line, int column) +@anchor{cp/topics/locations _CPPv4N6gccjit7context12new_locationEPKcii}@anchor{154}@anchor{cp/topics/locations _CPPv3N6gccjit7context12new_locationEPKcii}@anchor{32e}@anchor{cp/topics/locations _CPPv2N6gccjit7context12new_locationEPKcii}@anchor{32f}@anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{330} +@deffn {C++ Function} gccjit::@ref{14e,,location} gccjit::@ref{128,,context}::new_location (const char *filename, int line, int column) Create a @cite{gccjit::location} instance representing the given source location. @@ -14777,21 +13606,19 @@ location. @end menu @node Faking it<2>,,,Source Locations<2> -@anchor{cp/topics/locations faking-it}@anchor{1d4} +@anchor{cp/topics/locations faking-it}@anchor{331} @subsubsection Faking it -If you don't have source code for your internal representation, but need +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{152,,gccjit;;context;;dump_to_file()}: +your context using @ref{173,,gccjit;;context;;dump_to_file()}: @example ctxt.dump_to_file ("/tmp/something.c", 1 /* update_locations */); @end example -@noindent - This will dump C-like code to the given path. If the @cite{update_locations} argument is true, this will also set up @cite{gccjit::location} information throughout the context, pointing at the dump file as if it were a source @@ -14815,13 +13642,13 @@ file, giving you @emph{something} you can step through in the debugger. @c <http://www.gnu.org/licenses/>. @node Compiling a context<2>,,Source Locations<2>,Topic Reference<2> -@anchor{cp/topics/compilation compiling-a-context}@anchor{1d5}@anchor{cp/topics/compilation doc}@anchor{1d6} +@anchor{cp/topics/compilation doc}@anchor{332}@anchor{cp/topics/compilation compiling-a-context}@anchor{333} @subsection Compiling a context -Once populated, a @pxref{14b,,gccjit;;context} can be compiled to -machine code, either in-memory via @pxref{124,,gccjit;;context;;compile()} or -to disk via @pxref{1d7,,gccjit;;context;;compile_to_file()}. +Once populated, a @ref{128,,gccjit;;context} can be compiled to +machine code, either in-memory via @ref{132,,gccjit;;context;;compile()} or +to disk via @ref{334,,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 @@ -14834,39 +13661,39 @@ 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{1d8} +@anchor{cp/topics/compilation in-memory-compilation}@anchor{335} @subsubsection In-memory compilation @geindex gccjit;;context;;compile (C++ function) -@anchor{cp/topics/compilation gccjit context compile}@anchor{124} -@deffn {C++ Function} gcc_jit_result* gccjit::context::compile () +@anchor{cp/topics/compilation _CPPv4N6gccjit7context7compileEv}@anchor{132}@anchor{cp/topics/compilation _CPPv3N6gccjit7context7compileEv}@anchor{336}@anchor{cp/topics/compilation _CPPv2N6gccjit7context7compileEv}@anchor{337}@anchor{cp/topics/compilation gccjit context compile}@anchor{338} +@deffn {C++ Function} gcc_jit_result *gccjit::@ref{128,,context}::compile () This calls into GCC and builds the code, returning a @cite{gcc_jit_result *}. This is a thin wrapper around the -@pxref{15,,gcc_jit_context_compile()} API entrypoint. +@ref{15,,gcc_jit_context_compile()} API entrypoint. @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{1d9} +@anchor{cp/topics/compilation ahead-of-time-compilation}@anchor{339} @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{1d7,,gccjit;;context;;compile_to_file()} method. +compilers, via the @ref{334,,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{1d7} -@deffn {C++ Function} void gccjit::context::compile_to_file (enum gcc_jit_output_kind, const char* output_path) +@anchor{cp/topics/compilation _CPPv4N6gccjit7context15compile_to_fileE19gcc_jit_output_kindPKc}@anchor{334}@anchor{cp/topics/compilation _CPPv3N6gccjit7context15compile_to_fileE19gcc_jit_output_kindPKc}@anchor{33a}@anchor{cp/topics/compilation _CPPv2N6gccjit7context15compile_to_fileE19gcc_jit_output_kindPKc}@anchor{33b}@anchor{cp/topics/compilation gccjit context compile_to_file__gcc_jit_output_kind cCP}@anchor{33c} +@deffn {C++ Function} void gccjit::@ref{128,,context}::compile_to_file (enum gcc_jit_output_kind, const char *output_path) -Compile the @pxref{14b,,gccjit;;context} to a file of the given +Compile the @ref{128,,gccjit;;context} to a file of the given kind. This is a thin wrapper around the -@pxref{4a,,gcc_jit_context_compile_to_file()} API entrypoint. +@ref{4a,,gcc_jit_context_compile_to_file()} API entrypoint. @end deffn @c Copyright (C) 2014-2020 Free Software Foundation, Inc. @@ -14887,7 +13714,7 @@ This is a thin wrapper around the @c <http://www.gnu.org/licenses/>. @node Internals,Indices and tables,C++ bindings for libgccjit,Top -@anchor{internals/index internals}@anchor{1da}@anchor{internals/index doc}@anchor{1db} +@anchor{internals/index doc}@anchor{33d}@anchor{internals/index internals}@anchor{33e} @chapter Internals @@ -14903,11 +13730,11 @@ 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{1dc} +@anchor{internals/index working-on-the-jit-library}@anchor{33f} @section Working on the JIT library -Having checked out the source code (to "src"), you can configure and build +Having checked out the source code (to “src”), you can configure and build the JIT library like this: @example @@ -14924,8 +13751,6 @@ cd build nice make -j4 # altering the "4" to however many cores you have @end example -@noindent - This should build a libgccjit.so within jit/build/gcc: @example @@ -14935,13 +13760,11 @@ gcc/libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1' gcc/libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV), dynamically linked, not stripped @end example -@noindent - -Here's what those configuration options mean: +Here’s what those configuration options mean: @geindex command line option; --enable-host-shared -@anchor{internals/index cmdoption--enable-host-shared}@anchor{1dd} -@deffn {Option} --enable-host-shared +@anchor{internals/index cmdoption-enable-host-shared}@anchor{340} +@deffn {Option} @w{-}@w{-}enable@w{-}host@w{-}shared Configuring with this option means that the compiler is built as position-independent code, which incurs a slight performance hit, @@ -14949,8 +13772,8 @@ 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{1de} -@deffn {Option} --enable-languages=jit,c++ +@anchor{internals/index cmdoption-enable-languages}@anchor{341} +@deffn {Option} @w{-}@w{-}enable@w{-}languages=jit,c++ This specifies which frontends to build. The JIT library looks like a frontend to the rest of the code. @@ -14963,23 +13786,21 @@ running the test suite: xgcc: error: /home/david/jit/src/gcc/testsuite/jit.dg/test-quadratic.cc: C++ compiler not installed on this system c++: error trying to exec 'cc1plus': execvp: No such file or directory @end example - -@noindent @end deffn @geindex command line option; --disable-bootstrap -@anchor{internals/index cmdoption--disable-bootstrap}@anchor{1df} -@deffn {Option} --disable-bootstrap +@anchor{internals/index cmdoption-disable-bootstrap}@anchor{342} +@deffn {Option} @w{-}@w{-}disable@w{-}bootstrap -For hacking on the "jit" subdirectory, performing a full -bootstrap can be overkill, since it's unused by a bootstrap. However, +For hacking on the “jit” subdirectory, performing a full +bootstrap can be overkill, since it’s unused by a bootstrap. However, when submitting patches, you should remove this option, to ensure that the compiler can still bootstrap itself. @end deffn @geindex command line option; --enable-checking=release -@anchor{internals/index cmdoption--enable-checking}@anchor{1e0} -@deffn {Option} --enable-checking=release +@anchor{internals/index cmdoption-enable-checking}@anchor{343} +@deffn {Option} @w{-}@w{-}enable@w{-}checking=release The compile can perform extensive self-checking as it runs, useful when debugging, but slowing things down. @@ -14989,7 +13810,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{1e1} +@anchor{internals/index running-the-test-suite}@anchor{344} @section Running the test suite @@ -14998,24 +13819,18 @@ disable this self-checking. [gcc] $ make check-jit RUNTESTFLAGS="-v -v -v" @end example -@noindent - A summary of the tests can then be seen in: @example jit/build/gcc/testsuite/jit/jit.sum @end example -@noindent - and detailed logs in: @example jit/build/gcc/testsuite/jit/jit.log @end example -@noindent - The test executables are normally deleted after each test is run. For debugging, they can be preserved by setting @geindex PRESERVE_EXECUTABLES @@ -15027,11 +13842,9 @@ in the environment. If so, they can then be seen as: jit/build/gcc/testsuite/jit/*.exe @end example -@noindent - which can be run independently. -You can compile and run individual tests by passing "jit.exp=TESTNAME" to RUNTESTFLAGS e.g.: +You can compile and run individual tests by passing “jit.exp=TESTNAME” to RUNTESTFLAGS e.g.: @example [gcc] $ PRESERVE_EXECUTABLES= \ @@ -15039,8 +13852,6 @@ You can compile and run individual tests by passing "jit.exp=TESTNAME" to RUNTES RUNTESTFLAGS="-v -v -v jit.exp=test-factorial.c" @end example -@noindent - and once a test has been compiled, you can debug it directly: @example @@ -15051,15 +13862,13 @@ and once a test has been compiled, you can debug it directly: testsuite/jit/test-factorial.c.exe @end example -@noindent - @menu * Running under valgrind:: @end menu @node Running under valgrind,,,Running the test suite -@anchor{internals/index running-under-valgrind}@anchor{1e2} +@anchor{internals/index running-under-valgrind}@anchor{345} @subsection Running under valgrind @@ -15103,14 +13912,12 @@ $ less testsuite/jit/test-sum-of-squares.c.exe.valgrind.txt (...shows full valgrind report for this test case...) @end example -@noindent - -When running under valgrind, it's best to have configured gcc with +When running under valgrind, it’s best to have configured gcc with @code{--enable-valgrind-annotations}, which automatically suppresses various known false positives. @node Environment variables,Packaging notes,Running the test suite,Internals -@anchor{internals/index environment-variables}@anchor{1e3} +@anchor{internals/index environment-variables}@anchor{346} @section Environment variables @@ -15118,14 +13925,14 @@ 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{1e4} +@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{347} @deffn {Environment Variable} LD_LIBRARY_PATH @quotation @cite{libgccjit.so} is dynamically linked into client code, so if running against a locally-built library, @code{LD_LIBRARY_PATH} needs to be set -up appropriately. The library can be found within the "gcc" +up appropriately. The library can be found within the “gcc” subdirectory of the build tree: @end quotation @@ -15135,12 +13942,10 @@ libgccjit.so: symbolic link to `libgccjit.so.0' libgccjit.so.0: symbolic link to `libgccjit.so.0.0.1' libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux), dynamically linked, not stripped @end example - -@noindent @end deffn @geindex environment variable; PATH -@anchor{internals/index envvar-PATH}@anchor{1e5} +@anchor{internals/index envvar-PATH}@anchor{348} @deffn {Environment Variable} PATH The library uses a driver executable for converting from .s assembler @@ -15153,13 +13958,13 @@ Hence @code{PATH} needs to include a directory where the library can locate this executable. The executable is normally installed to the installation bindir -(e.g. /usr/bin), but a copy is also created within the "gcc" +(e.g. /usr/bin), but a copy is also created within the “gcc” subdirectory of the build tree for running the testsuite, and for ease of development. @end deffn @geindex environment variable; LIBRARY_PATH -@anchor{internals/index envvar-LIBRARY_PATH}@anchor{1e6} +@anchor{internals/index envvar-LIBRARY_PATH}@anchor{349} @deffn {Environment Variable} LIBRARY_PATH The driver executable invokes the linker, and the latter needs to locate @@ -15172,10 +13977,8 @@ ld: cannot find -lgcc ld: cannot find -lgcc_s @end example -@noindent - Hence if running directly from a locally-built copy (without installing), -@code{LIBRARY_PATH} needs to contain the "gcc" subdirectory of the build +@code{LIBRARY_PATH} needs to contain the “gcc” subdirectory of the build tree. @end deffn @@ -15192,14 +13995,12 @@ $ LD_LIBRARY_PATH=$(LIBGCCJIT_BUILD_DIR):$(LD_LIBRARY_PATH) \ hello world @end example -@noindent - @node Packaging notes,Overview of code structure,Environment variables,Internals -@anchor{internals/index packaging-notes}@anchor{1e7} +@anchor{internals/index packaging-notes}@anchor{34a} @section Packaging notes -The configure-time option @pxref{1dd,,--enable-host-shared} is needed when +The configure-time option @ref{340,,--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: @@ -15210,10 +14011,10 @@ with libgccjit, please configure and build twice: @itemize * @item -once without @pxref{1dd,,--enable-host-shared} for most languages, and +once without @ref{340,,--enable-host-shared} for most languages, and @item -once with @pxref{1dd,,--enable-host-shared} for the jit +once with @ref{340,,--enable-host-shared} for the jit @end itemize @end quotation @@ -15254,10 +14055,8 @@ make install popd @end example -@noindent - @node Overview of code structure,Design notes,Packaging notes,Internals -@anchor{internals/index overview-of-code-structure}@anchor{1e8} +@anchor{internals/index overview-of-code-structure}@anchor{34b} @section Overview of code structure @@ -15292,6 +14091,7 @@ The gcc::jit::recording classes (within @code{jit-recording.c} and class union_; class vector_type; class field; + class bitfield; class fields; class function; class block; @@ -15305,10 +14105,7 @@ The gcc::jit::recording classes (within @code{jit-recording.c} and class statement; class case_; - @end example - -@noindent @end quotation @item @@ -15336,11 +14133,8 @@ within langhook:parse_file: class location; class case_; - @end example -@noindent - @example Client Code . Generated . libgccjit.so . code . @@ -15476,10 +14270,7 @@ etc│ . . . . . . │ If that was the case, clean it up now. <─────────────────────────── . . │ . . . . - @end example - -@noindent @end quotation @end itemize @@ -15488,13 +14279,13 @@ Here is a high-level summary from @code{jit-common.h}: @quotation In order to allow jit objects to be usable outside of a compile -whilst working with the existing structure of GCC's code the +whilst working with the existing structure of GCC’s code the C API is implemented in terms of a gcc::jit::recording::context, which records the calls made to it. When a gcc_jit_context is compiled, the recording context creates a playback context. The playback context invokes the bulk of the GCC -code, and within the "frontend" parsing hook, plays back the recorded +code, and within the “frontend” parsing hook, plays back the recorded API calls, creating GCC tree objects. So there are two parallel families of classes: those relating to @@ -15520,13 +14311,13 @@ garbage-collected; they can own GC-references. @item Integration with rest of GCC: recording objects are unrelated to the -rest of GCC, whereas playback objects are wrappers around "tree" -instances. Hence you can't ask a recording rvalue or lvalue what its +rest of GCC, whereas playback objects are wrappers around “tree” +instances. Hence you can’t ask a recording rvalue or lvalue what its type is, whereas you can for a playback rvalue of lvalue (since it can work with the underlying GCC tree nodes). @item -Instancing: There can be multiple recording contexts "alive" at once +Instancing: There can be multiple recording contexts “alive” at once (albeit it only one compiling at once), whereas there can only be one playback context alive at one time (since it interacts with the GC). @end itemize @@ -15542,14 +14333,14 @@ the appropriate playback object subclass. For these casts to make sense, the two class hierarchies need to have the same structure. Note that the playback objects that @code{m_playback_obj} points to are -GC-allocated, but the recording objects don't own references: +GC-allocated, but the recording objects don’t own references: these associations only exist within a part of the code where -the GC doesn't collect, and are set back to NULL before the GC can +the GC doesn’t collect, and are set back to NULL before the GC can run. @end quotation @anchor{internals/index example-of-log-file}@anchor{5c} Another way to understand the structure of the code is to enable logging, -via @pxref{5b,,gcc_jit_context_set_logfile()}. Here is an example of a log +via @ref{5b,,gcc_jit_context_set_logfile()}. Here is an example of a log generated via this call: @example @@ -15729,26 +14520,23 @@ JIT: exiting: gcc::jit::tempdir::~tempdir() JIT: exiting: virtual gcc::jit::result::~result() JIT: exiting: gcc_jit_result_release JIT: gcc::jit::logger::~logger() - @end example -@noindent - @node Design notes,Submitting patches,Overview of code structure,Internals -@anchor{internals/index design-notes}@anchor{1e9} +@anchor{internals/index design-notes}@anchor{34c} @section Design notes It should not be possible for client code to cause an internal compiler error. If this @emph{does} happen, the root cause should be isolated (perhaps -using @pxref{5d,,gcc_jit_context_dump_reproducer_to_file()}) and the cause +using @ref{5d,,gcc_jit_context_dump_reproducer_to_file()}) and the cause should be rejected via additional checking. The checking ideally should be within the libgccjit API entrypoints in libgccjit.c, since this is as 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{1ea} +@anchor{internals/index submitting-patches}@anchor{34d} @section Submitting patches @@ -15757,9 +14545,9 @@ Please read the contribution guidelines for gcc at Patches for the jit should be sent to both the @email{gcc-patches@@gcc.gnu.org} and @email{jit@@gcc.gnu.org} mailing lists, -with "jit" and "PATCH" in the Subject line. +with “jit” and “PATCH” in the Subject line. -You don't need to do a full bootstrap for code that just touches the +You don’t need to do a full bootstrap for code that just touches the @code{jit} and @code{testsuite/jit.dg} subdirectories. However, please run @code{make check-jit} before submitting the patch, and mention the results in your email (along with the host triple that the tests were run on). @@ -15797,8 +14585,8 @@ A patch that adds new API entrypoints should also contain: @itemize * @item -a feature macro in @code{libgccjit.h} so that client code that doesn't -use a "configure" mechanism can still easily detect the presence of +a feature macro in @code{libgccjit.h} so that client code that doesn’t +use a “configure” mechanism can still easily detect the presence of the entrypoint. See e.g. @code{LIBGCCJIT_HAVE_SWITCH_STATEMENTS} (for a category of entrypoints) and @code{LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks} @@ -15809,11 +14597,11 @@ a new ABI tag containing the new symbols (in @code{libgccjit.map}), so that we can detect client code that uses them @item -Support for @pxref{5d,,gcc_jit_context_dump_reproducer_to_file()}. Most +Support for @ref{5d,,gcc_jit_context_dump_reproducer_to_file()}. Most jit testcases attempt to dump their contexts to a .c file; @code{jit.exp} then sanity-checks the generated c by compiling them (though not running them). A new API entrypoint -needs to "know" how to write itself back out to C (by implementing +needs to “know” how to write itself back out to C (by implementing @code{gcc::jit::recording::memento::write_reproducer} for the appropriate @code{memento} subclass). @@ -15836,9 +14624,9 @@ documentation for the new ABI tag (see @code{topics/compatibility.rst}). Depending on the patch you can either extend an existing test case, or add a new test case. If you add an entirely new testcase: @code{jit.exp} expects jit testcases to begin with @code{test-}, or @code{test-error-} (for a -testcase that generates an error on a @pxref{8,,gcc_jit_context}). +testcase that generates an error on a @ref{8,,gcc_jit_context}). -Every new testcase that doesn't generate errors should also touch +Every new testcase that doesn’t generate errors should also touch @code{gcc/testsuite/jit.dg/all-non-failing-tests.h}: @quotation @@ -15847,27 +14635,27 @@ Every new testcase that doesn't generate errors should also touch @itemize * @item -Testcases that don't generate errors should ideally be added to the +Testcases that don’t generate errors should ideally be added to the @code{testcases} array in that file; this means that, in addition to being run standalone, they also get run within @code{test-combination.c} (which runs all successful tests inside one -big @pxref{8,,gcc_jit_context}), and @code{test-threads.c} (which runs all +big @ref{8,,gcc_jit_context}), and @code{test-threads.c} (which runs all successful tests in one process, each one running in a different -thread on a different @pxref{8,,gcc_jit_context}). +thread on a different @ref{8,,gcc_jit_context}). @cartouche @quotation Note -Given that exported functions within a @pxref{8,,gcc_jit_context} +Given that exported functions within a @ref{8,,gcc_jit_context} must have unique names, and most testcases are run within @code{test-combination.c}, this means that every jit-compiled test -function typically needs a name that's unique across the entire +function typically needs a name that’s unique across the entire test suite. @end quotation @end cartouche @item -Testcases that aren't to be added to the @code{testcases} array should -instead add a comment to the file clarifying why they're not in that +Testcases that aren’t to be added to the @code{testcases} array should +instead add a comment to the file clarifying why they’re not in that array. See the file for examples. @end itemize @end quotation @@ -15875,14 +14663,14 @@ array. See the file for examples. Typically a patch that touches the .rst documentation will also need the texinfo to be regenerated. You can do this with Sphinx 1.0@footnote{http://sphinx-doc.org/} or later by -running @code{make texinfo} within @code{SRCDIR/gcc/jit/docs}. Don't do this +running @code{make texinfo} within @code{SRCDIR/gcc/jit/docs}. Don’t do this within the patch sent to the mailing list; it can often be relatively large and inconsequential (e.g. anchor renumbering), rather like generated -"configure" changes from configure.ac. You can regenerate it when +“configure” changes from configure.ac. You can regenerate it when committing to svn. @node Indices and tables,Index,Internals,Top -@anchor{index indices-and-tables}@anchor{1eb} +@anchor{index indices-and-tables}@anchor{34e} @unnumbered Indices and tables @@ -15890,13 +14678,13 @@ committing to svn. @itemize * @item -@emph{genindex} +genindex @item -@emph{modindex} +modindex @item -@emph{search} +search @end itemize @c Some notes: @@ -15912,5 +14700,6 @@ committing to svn. @printindex ge + @c %**end of body @bye diff --git a/gcc/jit/docs/topics/expressions.rst b/gcc/jit/docs/topics/expressions.rst index db2f2ca..d783cee 100644 --- a/gcc/jit/docs/topics/expressions.rst +++ b/gcc/jit/docs/topics/expressions.rst @@ -162,6 +162,8 @@ Unary Operations Build a unary operation out of an input rvalue. + The parameter ``result_type`` must be a numeric type. + .. type:: enum gcc_jit_unary_op The available unary operations are: @@ -227,6 +229,8 @@ Binary Operations Build a binary operation out of two constituent rvalues. + The parameter ``result_type`` must be a numeric type. + .. type:: enum gcc_jit_binary_op The available binary operations are: @@ -547,6 +551,8 @@ Global variables Add a new global variable of the given type and name to the context. + The parameter ``type`` must be non-`void`. + The parameter ``name`` must be non-NULL. The call takes a copy of the underlying string, so it is valid to pass in a pointer to an on-stack buffer. diff --git a/gcc/jit/docs/topics/function-pointers.rst b/gcc/jit/docs/topics/function-pointers.rst index c8424ee..7d2fa8b 100644 --- a/gcc/jit/docs/topics/function-pointers.rst +++ b/gcc/jit/docs/topics/function-pointers.rst @@ -78,3 +78,5 @@ Here's an example of creating a function pointer type corresponding to C's Generate a :c:type:`gcc_jit_type` for a function pointer with the given return type and parameters. + + Each of `param_types` must be non-`void`; `return_type` may be `void`. diff --git a/gcc/jit/docs/topics/functions.rst b/gcc/jit/docs/topics/functions.rst index 74d479a..29ce96c 100644 --- a/gcc/jit/docs/topics/functions.rst +++ b/gcc/jit/docs/topics/functions.rst @@ -35,6 +35,8 @@ Params In preparation for creating a function, create a new parameter of the given type and name. + The parameter ``type`` must be non-`void`. + The parameter ``name`` must be non-NULL. The call takes a copy of the underlying string, so it is valid to pass in a pointer to an on-stack buffer. @@ -148,6 +150,8 @@ Functions Create a new local variable within the function, of the given type and name. + The parameter ``type`` must be non-`void`. + The parameter ``name`` must be non-NULL. The call takes a copy of the underlying string, so it is valid to pass in a pointer to an on-stack buffer. diff --git a/gcc/jit/docs/topics/types.rst b/gcc/jit/docs/topics/types.rst index d1a39ee..ea7c8ff 100644 --- a/gcc/jit/docs/topics/types.rst +++ b/gcc/jit/docs/topics/types.rst @@ -115,13 +115,13 @@ Pointers, `const`, and `volatile` gcc_jit_type *element_type, \ int num_elements) - Given type "T", get type "T[N]" (for a constant N). + Given non-`void` type "T", get type "T[N]" (for a constant N). .. function:: gcc_jit_type *\ gcc_jit_type_get_aligned (gcc_jit_type *type, \ size_t alignment_in_bytes) - Given type "T", get type: + Given non-`void` type "T", get type: .. code-block:: c @@ -243,6 +243,8 @@ You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and Construct a new field, with the given type and name. + The parameter ``type`` must be non-`void`. + The parameter ``name`` must be non-NULL. The call takes a copy of the underlying string, so it is valid to pass in a pointer to an on-stack buffer. diff --git a/gcc/jit/libgccjit.c b/gcc/jit/libgccjit.c index a29e988..3d04f6d 100644 --- a/gcc/jit/libgccjit.c +++ b/gcc/jit/libgccjit.c @@ -527,6 +527,8 @@ gcc_jit_context_new_array_type (gcc_jit_context *ctxt, /* LOC can be NULL. */ RETURN_NULL_IF_FAIL (element_type, ctxt, loc, "NULL type"); RETURN_NULL_IF_FAIL (num_elements >= 0, ctxt, NULL, "negative size"); + RETURN_NULL_IF_FAIL (!element_type->is_void (), ctxt, loc, + "void type for elements"); return (gcc_jit_type *)ctxt->new_array_type (loc, element_type, @@ -556,6 +558,11 @@ gcc_jit_context_new_field (gcc_jit_context *ctxt, "unknown size for field \"%s\" (type: %s)", name, type->get_debug_string ()); + RETURN_NULL_IF_FAIL_PRINTF1 ( + !type->is_void (), + ctxt, loc, + "void type for field \"%s\"", + name); return (gcc_jit_field *)ctxt->new_field (loc, type, name); } @@ -786,10 +793,15 @@ gcc_jit_context_new_function_ptr_type (gcc_jit_context *ctxt, ctxt, loc, "NULL param_types creating function pointer type"); for (int i = 0; i < num_params; i++) - RETURN_NULL_IF_FAIL_PRINTF1 ( - param_types[i], - ctxt, loc, - "NULL parameter type %i creating function pointer type", i); + { + RETURN_NULL_IF_FAIL_PRINTF1 (param_types[i], + ctxt, loc, + "NULL parameter type %i" + " creating function pointer type", i); + RETURN_NULL_IF_FAIL_PRINTF1 (!param_types[i]->is_void (), + ctxt, loc, + "void type for param %i", i); + } return (gcc_jit_type*) ctxt->new_function_ptr_type (loc, return_type, @@ -816,6 +828,9 @@ gcc_jit_context_new_param (gcc_jit_context *ctxt, /* LOC can be NULL. */ RETURN_NULL_IF_FAIL (type, ctxt, loc, "NULL type"); RETURN_NULL_IF_FAIL (name, ctxt, loc, "NULL name"); + RETURN_NULL_IF_FAIL_PRINTF1 (!type->is_void (), + ctxt, loc, + "void type for param \"%s\"", name); return (gcc_jit_param *)ctxt->new_param (loc, type, name); } @@ -1093,6 +1108,11 @@ gcc_jit_context_new_global (gcc_jit_context *ctxt, "unknown size for global \"%s\" (type: %s)", name, type->get_debug_string ()); + RETURN_NULL_IF_FAIL_PRINTF1 ( + !type->is_void (), + ctxt, loc, + "void type for global \"%s\"", + name); return (gcc_jit_lvalue *)ctxt->new_global (loc, kind, type, name); } @@ -1911,6 +1931,11 @@ gcc_jit_function_new_local (gcc_jit_function *func, "unknown size for local \"%s\" (type: %s)", name, type->get_debug_string ()); + RETURN_NULL_IF_FAIL_PRINTF1 ( + !type->is_void (), + ctxt, loc, + "void type for local \"%s\"", + name); return (gcc_jit_lvalue *)func->new_local (loc, type, name); } @@ -3068,6 +3093,7 @@ gcc_jit_type_get_aligned (gcc_jit_type *type, (pow2_or_zerop (alignment_in_bytes), ctxt, NULL, "alignment not a power of two: %zi", alignment_in_bytes); + RETURN_NULL_IF_FAIL (!type->is_void (), ctxt, NULL, "void type"); return (gcc_jit_type *)type->get_aligned (alignment_in_bytes); } |