Refactoring of timevar API

gcc/ChangeLog: * main.c (main): Pass in NULL for toplev's external_timer. * timevar.c: Include coretypes.h. (class timer::named_items): New. (timer::named_items::named_items): New. (timer::named_items::~named_items): New. (timer::named_items::push): New. (timer::named_items::pop): New. (timer::named_items::print): New. (timer::timer): Initialize field "m_jit_client_items". (timer::~timer): New. (timer::push): Move bulk of implementation to... (timer::push_internal): ...here. New function. (timer::pop): Move bulk of implementation to... (timer::pop_internal): ...here. New function. (timer::push_client_item): New. (timer::pop_client_item): New. (timer::print_row): New function, taken from timer::print. (timer::print): Print "GCC items" header if we also have client items. Move row-printing to timer::print_row. Print any client items. (timer::get_topmost_item_name): New method. * timevar.def (TV_JIT_ACQUIRING_MUTEX): New. (TV_JIT_CLIENT_CODE): New. * timevar.h (timer::push_client_item): New declaration. (timer::pop_client_item): New declaration. (timer::get_topmost_item_name): New method. (timer::push_internal): New declaration. (timer::pop_internal): New declaration. (timer::print_row): New declaration. (timer::named_items): New declaration. (timer::m_jit_client_items): New field. (timer): Add friend class named_items. (auto_timevar::auto_timevar): Add timer param. (auto_timevar::~auto_timevar): Use field "m_timer". (auto_timevar::m_timer): New field. * toplev.c (initialize_rtl): Add g_timer as param when constructing auto_timevar instance. (toplev::toplev): Add "external_timer" param, and use it to initialize the "g_timer" global if non-NULL. (toplev::~toplev): If this created "g_timer", delete it. * toplev.h (toplev::toplev): Replace "use_TV_TOTAL" bool param with "external_timer" timer *. gcc/jit/ChangeLog: * docs/topics/compatibility.rst (LIBGCCJIT_ABI_4): New. * docs/topics/contexts.rst (GCC_JIT_BOOL_OPTION_DUMP_SUMMARY): We no longer show a profile. * docs/topics/index.rst (Topic Reference): Add performance.rst. * docs/topics/performance.rst: New file. * docs/_build/texinfo/libgccjit.texi: Regenerate. * jit-playback.c (gcc::jit::playback::context::compile): Add timer param when constructing the "toplev" instance. (gcc::jit::playback::context::acquire_mutex): Add timer param when constructing auto_timevar instance. (gcc::jit::playback::context::make_fake_args): If we have a timer, add "-ftime-report". (gcc::jit::playback::context::invoke_driver): Add timer param when constructing auto_timevar instance. (gcc::jit::playback::context::dlopen_built_dso): Likewise. * jit-playback.h (gcc::jit::playback::context::get_timer): New accessor. * jit-recording.c: Include timevar.h. (gcc::jit::recording::context::context): Initialize field "m_timer". * jit-recording.h: Add forward declaration of class timer. (gcc::jit::recording::context::set_timer): New method. (gcc::jit::recording::context::get_timer): New method. (gcc::jit::recording::context::m_timer): New field. * libgccjit++.h (gccjit::timer): New class. (gccjit::auto_time): New class. (gccjit::context::set_timer): New method. (gccjit::context::get_timer): New. (gccjit::timer::timer): New. (gccjit::timer::push): New. (gccjit::timer::pop): New. (timer::print): New. (timer::get_inner_timer): New. (timer::release): New. (auto_time::auto_time): New. (auto_time::~auto_time): New. * libgccjit.c: Include timevar.h. (struct gcc_jit_timer): New. (gcc_jit_timer_new): New function. (gcc_jit_timer_release): New function. (gcc_jit_context_set_timer): New function. (gcc_jit_context_get_timer): New function. (gcc_jit_timer_push): New function. (gcc_jit_timer_pop): New function. (gcc_jit_timer_print): New function. * libgccjit.h (LIBGCCJIT_HAVE_TIMING_API): New macro. (gcc_jit_timer): New typedef. (gcc_jit_timer_new): New function. (gcc_jit_timer_release): New function. (gcc_jit_context_set_timer): New function. (gcc_jit_context_get_timer): New function. (gcc_jit_timer_push): New function. (gcc_jit_timer_pop): New function. (gcc_jit_timer_print): New function. * libgccjit.map (LIBGCCJIT_ABI_4): New. (gcc_jit_timer_new): New function. (gcc_jit_timer_release): New function. (gcc_jit_context_set_timer): New function. (gcc_jit_context_get_timer): New function. (gcc_jit_timer_push): New function. (gcc_jit_timer_pop): New function. (gcc_jit_timer_print): New function. gcc/testsuite/ChangeLog: * jit.dg/test-benchmark.c (test_jit): Add param "timer" and use it to push/pop timing items. (main): For each optimization level, create a gcc_jit_timer, and time all of the iteration within that level cumulatively. * jit.dg/test-error-gcc_jit_timer_pop-mismatch.c: New test case. * jit.dg/test-error-gcc_jit_timer_pop-too-many.c: New test case. From-SVN: r226530
author: David Malcolm <dmalcolm@redhat.com> 2015-08-03 20:14:21 +0000
committer: David Malcolm <dmalcolm@gcc.gnu.org> 2015-08-03 20:14:21 +0000
commit: afed345982d5923b04d41885e868c9ca345ff3f9 (patch)
tree: b90c7df0235fa14daf2c76f22203ee08c2c32bcb /gcc/jit
parent: ef9da28d8fa1e2c0dc890f87374c0f21b18430c3 (diff)
download: gcc-afed345982d5923b04d41885e868c9ca345ff3f9.zip
gcc-afed345982d5923b04d41885e868c9ca345ff3f9.tar.gz
gcc-afed345982d5923b04d41885e868c9ca345ff3f9.tar.bz2
14 files changed, 1293 insertions, 271 deletions
diff --git a/gcc/jit/ChangeLog b/gcc/jit/ChangeLog
index f38143d..2cb6dfc 100644
--- a/gcc/jit/ChangeLog
+++ b/gcc/jit/ChangeLog
@@ -1,3 +1,66 @@
+2015-08-03  David Malcolm  <dmalcolm@redhat.com>
+
+	* docs/topics/compatibility.rst (LIBGCCJIT_ABI_4): New.
+	* docs/topics/contexts.rst (GCC_JIT_BOOL_OPTION_DUMP_SUMMARY):
+	We no longer show a profile.
+	* docs/topics/index.rst (Topic Reference): Add performance.rst.
+	* docs/topics/performance.rst: New file.
+	* docs/_build/texinfo/libgccjit.texi: Regenerate.
+	* jit-playback.c (gcc::jit::playback::context::compile): Add timer
+	param when constructing the "toplev" instance.
+	(gcc::jit::playback::context::acquire_mutex): Add timer param when
+	constructing auto_timevar instance.
+	(gcc::jit::playback::context::make_fake_args): If we have a timer,
+	add "-ftime-report".
+	(gcc::jit::playback::context::invoke_driver): Add timer param when
+	constructing auto_timevar instance.
+	(gcc::jit::playback::context::dlopen_built_dso): Likewise.
+	* jit-playback.h (gcc::jit::playback::context::get_timer): New accessor.
+	* jit-recording.c: Include timevar.h.
+	(gcc::jit::recording::context::context): Initialize field "m_timer".
+	* jit-recording.h: Add forward declaration of class timer.
+	(gcc::jit::recording::context::set_timer): New method.
+	(gcc::jit::recording::context::get_timer): New method.
+	(gcc::jit::recording::context::m_timer): New field.
+	* libgccjit++.h (gccjit::timer): New class.
+	(gccjit::auto_time): New class.
+	(gccjit::context::set_timer): New method.
+	(gccjit::context::get_timer): New.
+	(gccjit::timer::timer): New.
+	(gccjit::timer::push): New.
+	(gccjit::timer::pop): New.
+	(timer::print): New.
+	(timer::get_inner_timer): New.
+	(timer::release): New.
+	(auto_time::auto_time): New.
+	(auto_time::~auto_time): New.
+	* libgccjit.c: Include timevar.h.
+	(struct gcc_jit_timer): New.
+	(gcc_jit_timer_new): New function.
+	(gcc_jit_timer_release): New function.
+	(gcc_jit_context_set_timer): New function.
+	(gcc_jit_context_get_timer): New function.
+	(gcc_jit_timer_push): New function.
+	(gcc_jit_timer_pop): New function.
+	(gcc_jit_timer_print): New function.
+	* libgccjit.h (LIBGCCJIT_HAVE_TIMING_API): New macro.
+	(gcc_jit_timer): New typedef.
+	(gcc_jit_timer_new): New function.
+	(gcc_jit_timer_release): New function.
+	(gcc_jit_context_set_timer): New function.
+	(gcc_jit_context_get_timer): New function.
+	(gcc_jit_timer_push): New function.
+	(gcc_jit_timer_pop): New function.
+	(gcc_jit_timer_print): New function.
+	* libgccjit.map (LIBGCCJIT_ABI_4): New.
+	(gcc_jit_timer_new): New function.
+	(gcc_jit_timer_release): New function.
+	(gcc_jit_context_set_timer): New function.
+	(gcc_jit_context_get_timer): New function.
+	(gcc_jit_timer_push): New function.
+	(gcc_jit_timer_pop): New function.
+	(gcc_jit_timer_print): New function.
+
 2015-07-23  David Malcolm  <dmalcolm@redhat.com>
 
 	* jit-playback.c (invoke_driver): Convert local "argvec"
diff --git a/gcc/jit/docs/_build/texinfo/libgccjit.texi b/gcc/jit/docs/_build/texinfo/libgccjit.texi
index 88df0ad..f688e2d 100644
--- a/gcc/jit/docs/_build/texinfo/libgccjit.texi
+++ b/gcc/jit/docs/_build/texinfo/libgccjit.texi
@@ -19,7 +19,7 @@
 
 @copying
 @quotation
-libgccjit 6.0.0 (experimental 20150723), July 23, 2015
+libgccjit 6.0.0 (experimental 20150803), August 03, 2015
 
 David Malcolm
 
@@ -169,6 +169,7 @@ Topic Reference
 * Source Locations:: 
 * Compiling a context:: 
 * ABI and API compatibility:: 
+* Performance:: 
 
 Compilation contexts
 
@@ -236,6 +237,11 @@ ABI symbol tags
 * LIBGCCJIT_ABI_1:: 
 * LIBGCCJIT_ABI_2:: 
 * LIBGCCJIT_ABI_3:: 
+* LIBGCCJIT_ABI_4:: 
+
+Performance
+
+* The timing API:: 
 
 C++ bindings for libgccjit
 
@@ -4852,6 +4858,7 @@ and to a dynamic library.  See the documentation of
 * Source Locations:: 
 * Compiling a context:: 
 * ABI and API compatibility:: 
+* Performance:: 
 
 Compilation contexts
 
@@ -4919,6 +4926,11 @@ ABI symbol tags
 * LIBGCCJIT_ABI_1:: 
 * LIBGCCJIT_ABI_2:: 
 * LIBGCCJIT_ABI_3:: 
+* LIBGCCJIT_ABI_4:: 
+
+Performance
+
+* The timing API:: 
 
 @end menu
 
@@ -5435,8 +5447,7 @@ square:
 @deffn {C Macro} GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
 
 If true, @pxref{15,,gcc_jit_context_compile()} will print information to stderr
-on the actions it is performing, followed by a profile showing
-the time taken and memory usage of each phase.
+on the actions it is performing.
 @end deffn
 
 @geindex GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING (C macro)
@@ -8226,7 +8237,7 @@ against.
 @c along with this program.  If not, see
 @c <http://www.gnu.org/licenses/>.
 
-@node ABI and API compatibility,,Compiling a context,Topic Reference
+@node ABI and API compatibility,Performance,Compiling a context,Topic Reference
 @anchor{topics/compatibility abi-and-api-compatibility}@anchor{e6}@anchor{topics/compatibility doc}@anchor{e7}
 @section ABI and API compatibility
 
@@ -8289,6 +8300,7 @@ ABI symbol tags
 * LIBGCCJIT_ABI_1:: 
 * LIBGCCJIT_ABI_2:: 
 * LIBGCCJIT_ABI_3:: 
+* LIBGCCJIT_ABI_4:: 
 
 @end menu
 
@@ -8307,6 +8319,7 @@ Newer releases use the following tags.
 * LIBGCCJIT_ABI_1:: 
 * LIBGCCJIT_ABI_2:: 
 * LIBGCCJIT_ABI_3:: 
+* LIBGCCJIT_ABI_4:: 
 
 @end menu
 
@@ -8338,7 +8351,7 @@ continue to work, with this being handled transparently by the linker
 @code{LIBGCCJIT_ABI_2} covers the addition of
 @pxref{6b,,gcc_jit_context_set_bool_allow_unreachable_blocks()}
 
-@node LIBGCCJIT_ABI_3,,LIBGCCJIT_ABI_2,ABI symbol tags
+@node LIBGCCJIT_ABI_3,LIBGCCJIT_ABI_4,LIBGCCJIT_ABI_2,ABI symbol tags
 @anchor{topics/compatibility libgccjit-abi-3}@anchor{d8}@anchor{topics/compatibility id4}@anchor{ed}
 @subsubsection @code{LIBGCCJIT_ABI_3}
 
@@ -8362,6 +8375,353 @@ entrypoints:
 @end itemize
 @end quotation
 
+@node LIBGCCJIT_ABI_4,,LIBGCCJIT_ABI_3,ABI symbol tags
+@anchor{topics/compatibility id5}@anchor{ee}@anchor{topics/compatibility libgccjit-abi-4}@anchor{ef}
+@subsubsection @code{LIBGCCJIT_ABI_4}
+
+
+@code{LIBGCCJIT_ABI_4} covers the addition of timers via API
+entrypoints:
+
+@quotation
+
+
+@itemize *
+
+@item 
+@pxref{f0,,gcc_jit_context_get_timer()}
+
+@item 
+@pxref{f1,,gcc_jit_context_set_timer()}
+
+@item 
+@pxref{f2,,gcc_jit_timer_new()}
+
+@item 
+@pxref{f3,,gcc_jit_timer_release()}
+
+@item 
+@pxref{f4,,gcc_jit_timer_push()}
+
+@item 
+@pxref{f5,,gcc_jit_timer_pop()}
+
+@item 
+@pxref{f6,,gcc_jit_timer_print()}
+@end itemize
+@end quotation
+
+@c Copyright (C) 2015 Free Software Foundation, Inc.
+@c Originally contributed by David Malcolm <dmalcolm@redhat.com>
+@c 
+@c This is free software: you can redistribute it and/or modify it
+@c under the terms of the GNU General Public License as published by
+@c the Free Software Foundation, either version 3 of the License, or
+@c (at your option) any later version.
+@c 
+@c This program is distributed in the hope that it will be useful, but
+@c WITHOUT ANY WARRANTY; without even the implied warranty of
+@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+@c General Public License for more details.
+@c 
+@c You should have received a copy of the GNU General Public License
+@c along with this program.  If not, see
+@c <http://www.gnu.org/licenses/>.
+
+@node Performance,,ABI and API compatibility,Topic Reference
+@anchor{topics/performance performance}@anchor{f7}@anchor{topics/performance doc}@anchor{f8}
+@section Performance
+
+
+@menu
+* The timing API:: 
+
+@end menu
+
+@node The timing API,,,Performance
+@anchor{topics/performance the-timing-api}@anchor{f9}
+@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{fa,,gcc_jit_timer} instance, which will
+measure time spent since its creation.  The timer maintains a stack
+of "timer items": as control flow moves through your code, you can push
+and pop named items relating to your code onto the stack, and the timer
+will account the time spent accordingly.
+
+You can also asssociate a timer with a @pxref{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":
+
+@example
+/* Create a timer.  */
+gcc_jit_timer *timer = gcc_jit_timer_new ();
+if (!timer)
+  @{
+     error ("gcc_jit_timer_new failed");
+     return -1;
+  @}
+
+/* Let's repeatedly compile and run some code, accumulating it
+   all into the timer.  */
+for (int i = 0; i < num_iterations; i++)
+  @{
+    /* Create a context and associate it with the timer.  */
+    gcc_jit_context *ctxt = gcc_jit_context_acquire ();
+    if (!ctxt)
+      @{
+        error ("gcc_jit_context_acquire failed");
+        return -1;
+      @}
+    gcc_jit_context_set_timer (ctxt, timer);
+
+    /* Populate the context, timing it as client item "create_code".  */
+    gcc_jit_timer_push (timer, "create_code");
+    create_code (ctxt);
+    gcc_jit_timer_pop (timer, "create_code");
+
+    /* Compile the context, timing it as client item "compile".  */
+    gcc_jit_timer_push (timer, "compile");
+    result = gcc_jit_context_compile (ctxt);
+    gcc_jit_timer_pop (timer, "compile");
+
+    /* Run the generated code, timing it as client item "running code".  */
+    gcc_jit_timer_push (timer, "running code");
+    run_the_code (ctxt, result);
+    gcc_jit_timer_pop (timer, "running code");
+
+    /* Clean up.  */
+    gcc_jit_context_release (ctxt);
+    gcc_jit_result_release (result);
+@}
+
+/* Print the accumulated timings.  */
+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:
+
+@example
+Execution times (seconds)
+GCC items:
+ phase setup             :   0.29 (14%) usr   0.00 ( 0%) sys   0.32 ( 5%) wall   10661 kB (50%) ggc
+ phase parsing           :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall     653 kB ( 3%) ggc
+ phase finalize          :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+ dump files              :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.01 ( 0%) wall       0 kB ( 0%) ggc
+ callgraph construction  :   0.02 ( 1%) usr   0.01 ( 6%) sys   0.01 ( 0%) wall     242 kB ( 1%) ggc
+ callgraph optimization  :   0.03 ( 2%) usr   0.00 ( 0%) sys   0.02 ( 0%) wall     142 kB ( 1%) ggc
+ trivially dead code     :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+ df scan insns           :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       9 kB ( 0%) ggc
+ df live regs            :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.01 ( 0%) wall       0 kB ( 0%) ggc
+ inline parameters       :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.01 ( 0%) wall      82 kB ( 0%) ggc
+ tree CFG cleanup        :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+ tree PHI insertion      :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.02 ( 0%) wall      64 kB ( 0%) ggc
+ tree SSA other          :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.01 ( 0%) wall      18 kB ( 0%) ggc
+ expand                  :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall     398 kB ( 2%) ggc
+ jump                    :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+ loop init               :   0.01 ( 0%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall      67 kB ( 0%) ggc
+ integrated RA           :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall    2468 kB (12%) ggc
+ thread pro- & epilogue  :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall     162 kB ( 1%) ggc
+ final                   :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall     216 kB ( 1%) ggc
+ rest of compilation     :   1.37 (69%) usr   0.00 ( 0%) sys   1.13 (18%) wall    1391 kB ( 6%) ggc
+ assemble JIT code       :   0.01 ( 1%) usr   0.00 ( 0%) sys   4.04 (66%) wall       0 kB ( 0%) ggc
+ load JIT result         :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+ JIT client code         :   0.00 ( 0%) usr   0.01 ( 6%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+Client items:
+ create_code             :   0.00 ( 0%) usr   0.01 ( 6%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+ compile                 :   0.36 (18%) usr   0.15 (83%) sys   0.86 (14%) wall   14939 kB (70%) ggc
+ running code            :   0.00 ( 0%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+ 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{fb}
+@deffn {C Macro} LIBGCCJIT_HAVE_TIMING_API
+
+The timer API was added to libgccjit in GCC 6.
+This macro is only defined in versions of libgccjit.h which have the
+timer API, and so can be used to guard code that may need to compile
+against earlier releases:
+
+@example
+#ifdef LIBGCCJIT_HAVE_TIMING_API
+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{fa}
+@deffn {C Type} gcc_jit_timer
+@end deffn
+
+@geindex gcc_jit_timer_new (C function)
+@anchor{topics/performance gcc_jit_timer_new}@anchor{f2}
+@deffn {C Function} gcc_jit_timer * gcc_jit_timer_new (void)
+
+Create a @pxref{fa,,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{ef,,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{f3}
+@deffn {C Function} void gcc_jit_timer_release (gcc_jit_timer@w{ }*timer)
+
+Release a @pxref{fa,,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{ef,,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{f1}
+@deffn {C Function} void gcc_jit_context_set_timer (gcc_jit_context@w{ }*ctxt, gcc_jit_timer@w{ }*timer)
+
+Associate a @pxref{fa,,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.
+
+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{ef,,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{f0}
+@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{ef,,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{f4}
+@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:
+
+@example
+gcc_jit_timer_push (t, "running code");
+run_the_code (ctxt, result);
+gcc_jit_timer_pop (t, "running code");
+@end example
+
+@noindent
+
+This API entrypoint was added in @pxref{ef,,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{f5}
+@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.
+
+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{ef,,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{f6}
+@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{ef,,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-2015 Free Software Foundation, Inc.
 @c Originally contributed by David Malcolm <dmalcolm@redhat.com>
 @c 
@@ -8380,7 +8740,7 @@ entrypoints:
 @c <http://www.gnu.org/licenses/>.
 
 @node C++ bindings for libgccjit,Internals,Topic Reference,Top
-@anchor{cp/index c-bindings-for-libgccjit}@anchor{ee}@anchor{cp/index doc}@anchor{ef}
+@anchor{cp/index c-bindings-for-libgccjit}@anchor{fc}@anchor{cp/index doc}@anchor{fd}
 @chapter C++ bindings for libgccjit
 
 
@@ -8528,7 +8888,7 @@ Compiling a context
 
 
 @node Tutorial<2>,Topic Reference<2>,,C++ bindings for libgccjit
-@anchor{cp/intro/index doc}@anchor{f0}@anchor{cp/intro/index tutorial}@anchor{f1}
+@anchor{cp/intro/index doc}@anchor{fe}@anchor{cp/intro/index tutorial}@anchor{ff}
 @section Tutorial
 
 
@@ -8558,7 +8918,7 @@ Compiling a context
 @end menu
 
 @node Tutorial part 1 "Hello world"<2>,Tutorial part 2 Creating a trivial machine code function<2>,,Tutorial<2>
-@anchor{cp/intro/tutorial01 doc}@anchor{f2}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{f3}
+@anchor{cp/intro/tutorial01 doc}@anchor{100}@anchor{cp/intro/tutorial01 tutorial-part-1-hello-world}@anchor{101}
 @subsection Tutorial part 1: "Hello world"
 
 
@@ -8728,7 +9088,7 @@ hello world
 @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{f4}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{f5}
+@anchor{cp/intro/tutorial02 doc}@anchor{102}@anchor{cp/intro/tutorial02 tutorial-part-2-creating-a-trivial-machine-code-function}@anchor{103}
 @subsection Tutorial part 2: Creating a trivial machine code function
 
 
@@ -8757,7 +9117,7 @@ All state associated with compilation is associated with a
 @code{gccjit::context}, which is a thin C++ wrapper around the C API's
 @pxref{8,,gcc_jit_context *}.
 
-Create one using @pxref{f6,,gccjit;;context;;acquire()}:
+Create one using @pxref{104,,gccjit;;context;;acquire()}:
 
 @example
 gccjit::context ctxt;
@@ -8770,7 +9130,7 @@ The JIT library has a system of types.  It is statically-typed: every
 expression is of a specific type, fixed at compile-time.  In our example,
 all of the expressions are of the C @cite{int} type, so let's obtain this from
 the context, as a @code{gccjit::type}, using
-@pxref{f7,,gccjit;;context;;get_type()}:
+@pxref{105,,gccjit;;context;;get_type()}:
 
 @example
 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
@@ -8783,7 +9143,7 @@ entity in the API is associated with a @code{gccjit::context}.
 
 Memory management is easy: all such "contextual" objects are automatically
 cleaned up for you when the context is released, using
-@pxref{f8,,gccjit;;context;;release()}:
+@pxref{106,,gccjit;;context;;release()}:
 
 @example
 ctxt.release ();
@@ -8816,7 +9176,7 @@ The C++ class hierarchy within the @code{gccjit} namespace looks like this:
 
 One thing you can do with a @code{gccjit::object} is
 to ask it for a human-readable description as a @code{std::string}, using
-@pxref{f9,,gccjit;;object;;get_debug_string()}:
+@pxref{107,,gccjit;;object;;get_debug_string()}:
 
 @example
 printf ("obj: %s\n", obj.get_debug_string ().c_str ());
@@ -8836,7 +9196,7 @@ This is invaluable when debugging.
 
 Let's create the function.  To do so, we first need to construct
 its single parameter, specifying its type and giving it a name,
-using @pxref{fa,,gccjit;;context;;new_param()}:
+using @pxref{108,,gccjit;;context;;new_param()}:
 
 @example
 gccjit::param param_i = ctxt.new_param (int_type, "i");
@@ -8885,7 +9245,7 @@ gccjit::block block = func.new_block ();
 Our basic block is relatively simple: it immediately terminates by
 returning the value of an expression.
 
-We can build the expression using @pxref{fb,,gccjit;;context;;new_binary_op()}:
+We can build the expression using @pxref{109,,gccjit;;context;;new_binary_op()}:
 
 @example
 gccjit::rvalue expr =
@@ -8898,7 +9258,7 @@ gccjit::rvalue expr =
 
 A @code{gccjit::rvalue} is another example of a
 @code{gccjit::object} subclass.  As before, we can print it with
-@pxref{f9,,gccjit;;object;;get_debug_string()}.
+@pxref{107,,gccjit;;object;;get_debug_string()}.
 
 @example
 printf ("expr: %s\n", expr.get_debug_string ().c_str ());
@@ -8935,7 +9295,7 @@ block.end_with_return (expr);
 @noindent
 
 OK, we've populated the context.  We can now compile it using
-@pxref{fc,,gccjit;;context;;compile()}:
+@pxref{10a,,gccjit;;context;;compile()}:
 
 @example
 gcc_jit_result *result;
@@ -8985,12 +9345,12 @@ result: 25
 @end menu
 
 @node Options<3>,Full example<3>,,Tutorial part 2 Creating a trivial machine code function<2>
-@anchor{cp/intro/tutorial02 options}@anchor{fd}
+@anchor{cp/intro/tutorial02 options}@anchor{10b}
 @subsubsection Options
 
 
 To get more information on what's going on, you can set debugging flags
-on the context using @pxref{fe,,gccjit;;context;;set_bool_option()}.
+on the context using @pxref{10c,,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
@@ -9062,7 +9422,7 @@ square:
 
 By default, no optimizations are performed, the equivalent of GCC's
 @cite{-O0} option.  We can turn things up to e.g. @cite{-O3} by calling
-@pxref{ff,,gccjit;;context;;set_int_option()} with
+@pxref{10d,,gccjit;;context;;set_int_option()} with
 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
 
 @example
@@ -9096,7 +9456,7 @@ square:
 Naturally this has only a small effect on such a trivial function.
 
 @node Full example<3>,,Options<3>,Tutorial part 2 Creating a trivial machine code function<2>
-@anchor{cp/intro/tutorial02 full-example}@anchor{100}
+@anchor{cp/intro/tutorial02 full-example}@anchor{10e}
 @subsubsection Full example
 
 
@@ -9239,7 +9599,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{101}@anchor{cp/intro/tutorial03 doc}@anchor{102}
+@anchor{cp/intro/tutorial03 tutorial-part-3-loops-and-variables}@anchor{10f}@anchor{cp/intro/tutorial03 doc}@anchor{110}
 @subsection Tutorial part 3: Loops and variables
 
 
@@ -9363,7 +9723,7 @@ gccjit::function func =
 @end menu
 
 @node Expressions lvalues and rvalues<2>,Control flow<2>,,Tutorial part 3 Loops and variables<2>
-@anchor{cp/intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{103}
+@anchor{cp/intro/tutorial03 expressions-lvalues-and-rvalues}@anchor{111}
 @subsubsection Expressions: lvalues and rvalues
 
 
@@ -9436,7 +9796,7 @@ body of a function.
 
 Our new example has a new kind of expression: we have two local
 variables.  We create them by calling
-@pxref{104,,gccjit;;function;;new_local()}, supplying a type and a name:
+@pxref{112,,gccjit;;function;;new_local()}, supplying a type and a name:
 
 @example
 /* Build locals:  */
@@ -9462,7 +9822,7 @@ Instead, having added the local to the function, we have to separately add
 an assignment of @cite{0} to @cite{local_i} at the beginning of the function.
 
 @node Control flow<2>,Visualizing the control flow graph<2>,Expressions lvalues and rvalues<2>,Tutorial part 3 Loops and variables<2>
-@anchor{cp/intro/tutorial03 control-flow}@anchor{105}
+@anchor{cp/intro/tutorial03 control-flow}@anchor{113}
 @subsubsection Control flow
 
 
@@ -9501,8 +9861,8 @@ We now populate each block with statements.
 
 The entry block @cite{b_initial} consists of initializations followed by a jump
 to the conditional.  We assign @cite{0} to @cite{i} and to @cite{sum}, using
-@pxref{106,,gccjit;;block;;add_assignment()} to add
-an assignment statement, and using @pxref{107,,gccjit;;context;;zero()} to get
+@pxref{114,,gccjit;;block;;add_assignment()} to add
+an assignment statement, and using @pxref{115,,gccjit;;context;;zero()} to get
 the constant value @cite{0} for the relevant type for the right-hand side of
 the assignment:
 
@@ -9529,7 +9889,7 @@ C example. It contains a single statement: a conditional, which jumps to
 one of two destination blocks depending on a boolean
 @code{gccjit::rvalue}, in this case the comparison of @cite{i} and @cite{n}.
 
-We could build the comparison using @pxref{108,,gccjit;;context;;new_comparison()}:
+We could build the comparison using @pxref{116,,gccjit;;context;;new_comparison()}:
 
 @example
 gccjit::rvalue guard =
@@ -9540,7 +9900,7 @@ gccjit::rvalue guard =
 @noindent
 
 and can then use this to add @cite{b_loop_cond}'s sole statement, via
-@pxref{109,,gccjit;;block;;end_with_conditional()}:
+@pxref{117,,gccjit;;block;;end_with_conditional()}:
 
 @example
 b_loop_cond.end_with_conditional (guard,
@@ -9574,7 +9934,7 @@ Next, we populate the body of the loop.
 
 The C statement @cite{sum += i * i;} is an assignment operation, where an
 lvalue is modified "in-place".  We use
-@pxref{10a,,gccjit;;block;;add_assignment_op()} to handle these operations:
+@pxref{118,,gccjit;;block;;add_assignment_op()} to handle these operations:
 
 @example
 /* sum += i * i */
@@ -9602,7 +9962,7 @@ b_loop_body.add_assignment_op (i,
 @cartouche
 @quotation Note 
 For numeric constants other than 0 or 1, we could use
-@pxref{10b,,gccjit;;context;;new_rvalue()}, which has overloads
+@pxref{119,,gccjit;;context;;new_rvalue()}, which has overloads
 for both @code{int} and @code{double}.
 @end quotation
 @end cartouche
@@ -9678,12 +10038,12 @@ result: 285
 @noindent
 
 @node Visualizing the control flow graph<2>,Full example<4>,Control flow<2>,Tutorial part 3 Loops and variables<2>
-@anchor{cp/intro/tutorial03 visualizing-the-control-flow-graph}@anchor{10c}
+@anchor{cp/intro/tutorial03 visualizing-the-control-flow-graph}@anchor{11a}
 @subsubsection Visualizing the control flow graph
 
 
 You can see the control flow graph of a function using
-@pxref{10d,,gccjit;;function;;dump_to_dot()}:
+@pxref{11b,,gccjit;;function;;dump_to_dot()}:
 
 @example
 func.dump_to_dot ("/tmp/sum-of-squares.dot");
@@ -9717,7 +10077,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{10e}
+@anchor{cp/intro/tutorial03 full-example}@anchor{11c}
 @subsubsection Full example
 
 
@@ -9900,7 +10260,7 @@ 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{10f}@anchor{cp/intro/tutorial04 doc}@anchor{110}
+@anchor{cp/intro/tutorial04 tutorial-part-4-adding-jit-compilation-to-a-toy-interpreter}@anchor{11d}@anchor{cp/intro/tutorial04 doc}@anchor{11e}
 @subsection Tutorial part 4: Adding JIT-compilation to a toy interpreter
 
 
@@ -9922,7 +10282,7 @@ to it.
 @end menu
 
 @node Our toy interpreter<2>,Compiling to machine code<2>,,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
-@anchor{cp/intro/tutorial04 our-toy-interpreter}@anchor{111}
+@anchor{cp/intro/tutorial04 our-toy-interpreter}@anchor{11f}
 @subsubsection Our toy interpreter
 
 
@@ -10330,7 +10690,7 @@ toyvm_function::interpret (int arg, FILE *trace)
 @end quotation
 
 @node Compiling to machine code<2>,Setting things up<2>,Our toy interpreter<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
-@anchor{cp/intro/tutorial04 compiling-to-machine-code}@anchor{112}
+@anchor{cp/intro/tutorial04 compiling-to-machine-code}@anchor{120}
 @subsubsection Compiling to machine code
 
 
@@ -10410,7 +10770,7 @@ This means our compiler has the following state:
 @end quotation
 
 @node Setting things up<2>,Populating the function<2>,Compiling to machine code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
-@anchor{cp/intro/tutorial04 setting-things-up}@anchor{113}
+@anchor{cp/intro/tutorial04 setting-things-up}@anchor{121}
 @subsubsection Setting things up
 
 
@@ -10578,7 +10938,7 @@ We create the locals within the function.
 @end quotation
 
 @node Populating the function<2>,Verifying the control flow graph<2>,Setting things up<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
-@anchor{cp/intro/tutorial04 populating-the-function}@anchor{114}
+@anchor{cp/intro/tutorial04 populating-the-function}@anchor{122}
 @subsubsection Populating the function
 
 
@@ -10706,7 +11066,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{115,,gccjit;;block;;add_comment()} to add descriptive comments
+@pxref{123,,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}:
 
@@ -10855,14 +11215,14 @@ to the next block.
 This is analogous to simply incrementing the program counter.
 
 @node Verifying the control flow graph<2>,Compiling the context<2>,Populating the function<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
-@anchor{cp/intro/tutorial04 verifying-the-control-flow-graph}@anchor{116}
+@anchor{cp/intro/tutorial04 verifying-the-control-flow-graph}@anchor{124}
 @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{10d,,gccjit;;function;;dump_to_dot()}:
+using @pxref{11b,,gccjit;;function;;dump_to_dot()}:
 
 @example
 fn.dump_to_dot ("/tmp/factorial.dot");
@@ -10886,7 +11246,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{117}
+@anchor{cp/intro/tutorial04 compiling-the-context}@anchor{125}
 @subsubsection Compiling the context
 
 
@@ -10923,7 +11283,7 @@ We can now run the result:
 @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{118}
+@anchor{cp/intro/tutorial04 single-stepping-through-the-generated-code}@anchor{126}
 @subsubsection Single-stepping through the generated code
 
 
@@ -10937,14 +11297,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{119,,gccjit;;context;;new_location()} and using the
+calling @pxref{127,,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{fe,,gccjit;;context;;set_bool_option()}:
+@pxref{10c,,gccjit;;context;;set_bool_option()}:
 
 @example
 ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
@@ -11016,14 +11376,14 @@ optimization level in a regular compiler.
 @end cartouche
 
 @node Examining the generated code<2>,Putting it all together<2>,Single-stepping through the generated code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
-@anchor{cp/intro/tutorial04 examining-the-generated-code}@anchor{11a}
+@anchor{cp/intro/tutorial04 examining-the-generated-code}@anchor{128}
 @subsubsection Examining the generated code
 
 
 How good is the optimized code?
 
 We can turn up optimizations, by calling
-@pxref{ff,,gccjit;;context;;set_int_option()} with
+@pxref{10d,,gccjit;;context;;set_int_option()} with
 @pxref{1f,,GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL}:
 
 @example
@@ -11205,7 +11565,7 @@ Note that the stack pushing and popping have been eliminated, as has the
 recursive call (in favor of an iteration).
 
 @node Putting it all together<2>,Behind the curtain How does our code get optimized?<2>,Examining the generated code<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
-@anchor{cp/intro/tutorial04 putting-it-all-together}@anchor{11b}
+@anchor{cp/intro/tutorial04 putting-it-all-together}@anchor{129}
 @subsubsection Putting it all together
 
 
@@ -11238,7 +11598,7 @@ compiler result: 55
 @noindent
 
 @node Behind the curtain How does our code get optimized?<2>,,Putting it all together<2>,Tutorial part 4 Adding JIT-compilation to a toy interpreter<2>
-@anchor{cp/intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{11c}
+@anchor{cp/intro/tutorial04 behind-the-curtain-how-does-our-code-get-optimized}@anchor{12a}
 @subsubsection Behind the curtain: How does our code get optimized?
 
 
@@ -11439,7 +11799,7 @@ representation: @code{initial}, @code{instr4} and @code{instr9}.
 @end menu
 
 @node Optimizing away stack manipulation<2>,Elimination of tail recursion<2>,,Behind the curtain How does our code get optimized?<2>
-@anchor{cp/intro/tutorial04 optimizing-away-stack-manipulation}@anchor{11d}
+@anchor{cp/intro/tutorial04 optimizing-away-stack-manipulation}@anchor{12b}
 @subsubsection Optimizing away stack manipulation
 
 
@@ -11719,7 +12079,7 @@ instr9:
 @noindent
 
 @node Elimination of tail recursion<2>,,Optimizing away stack manipulation<2>,Behind the curtain How does our code get optimized?<2>
-@anchor{cp/intro/tutorial04 elimination-of-tail-recursion}@anchor{11e}
+@anchor{cp/intro/tutorial04 elimination-of-tail-recursion}@anchor{12c}
 @subsubsection Elimination of tail recursion
 
 
@@ -11806,7 +12166,7 @@ instr9:
 @c <http://www.gnu.org/licenses/>.
 
 @node Topic Reference<2>,,Tutorial<2>,C++ bindings for libgccjit
-@anchor{cp/topics/index doc}@anchor{11f}@anchor{cp/topics/index topic-reference}@anchor{120}
+@anchor{cp/topics/index doc}@anchor{12d}@anchor{cp/topics/index topic-reference}@anchor{12e}
 @section Topic Reference
 
 
@@ -11896,22 +12256,22 @@ Compiling a context
 
 
 @node Compilation contexts<2>,Objects<2>,,Topic Reference<2>
-@anchor{cp/topics/contexts compilation-contexts}@anchor{121}@anchor{cp/topics/contexts doc}@anchor{122}
+@anchor{cp/topics/contexts compilation-contexts}@anchor{12f}@anchor{cp/topics/contexts doc}@anchor{130}
 @subsection Compilation contexts
 
 
 @geindex gccjit;;context (C++ class)
-@anchor{cp/topics/contexts gccjit context}@anchor{123}
+@anchor{cp/topics/contexts gccjit context}@anchor{131}
 @deffn {C++ Class} gccjit::context
 @end deffn
 
-The top-level of the C++ API is the @pxref{123,,gccjit;;context} type.
+The top-level of the C++ API is the @pxref{131,,gccjit;;context} type.
 
-A @pxref{123,,gccjit;;context} instance encapsulates the state of a
+A @pxref{131,,gccjit;;context} instance encapsulates the state of a
 compilation.
 
 You can set up options on it, and add types, functions and code.
-Invoking @pxref{fc,,gccjit;;context;;compile()} on it gives you a
+Invoking @pxref{10a,,gccjit;;context;;compile()} on it gives you a
 @pxref{16,,gcc_jit_result *}.
 
 It is a thin wrapper around the C API's @pxref{8,,gcc_jit_context *}.
@@ -11926,7 +12286,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{124}
+@anchor{cp/topics/contexts lifetime-management}@anchor{132}
 @subsubsection Lifetime-management
 
 
@@ -11935,16 +12295,16 @@ have their lifetime bounded by the context they are created within, and
 cleanup of such objects is done for you when the context is released.
 
 @geindex gccjit;;context;;acquire (C++ function)
-@anchor{cp/topics/contexts gccjit context acquire}@anchor{f6}
+@anchor{cp/topics/contexts gccjit context acquire}@anchor{104}
 @deffn {C++ Function} gccjit::context gccjit::context::acquire ()
 
-This function acquires a new @pxref{123,,gccjit;;context} instance,
+This function acquires a new @pxref{131,,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{f8}
+@anchor{cp/topics/contexts gccjit context release}@anchor{106}
 @deffn {C++ Function} void gccjit::context::release ()
 
 This function releases all resources associated with the given context.
@@ -11963,7 +12323,7 @@ ctxt.release ();
 @end deffn
 
 @geindex gccjit;;context;;new_child_context (C++ function)
-@anchor{cp/topics/contexts gccjit context new_child_context}@anchor{125}
+@anchor{cp/topics/contexts gccjit context new_child_context}@anchor{133}
 @deffn {C++ Function} gccjit::context gccjit::context::new_child_context ()
 
 Given an existing JIT context, create a child context.
@@ -11995,16 +12355,16 @@ there will likely be a performance hit for such nesting.
 @end deffn
 
 @node Thread-safety<2>,Error-handling<3>,Lifetime-management<2>,Compilation contexts<2>
-@anchor{cp/topics/contexts thread-safety}@anchor{126}
+@anchor{cp/topics/contexts thread-safety}@anchor{134}
 @subsubsection Thread-safety
 
 
-Instances of @pxref{123,,gccjit;;context} created via
-@pxref{f6,,gccjit;;context;;acquire()} are independent from each other:
+Instances of @pxref{131,,gccjit;;context} created via
+@pxref{104,,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{125,,gccjit;;context;;new_child_context()} are
+Contexts created via @pxref{133,,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,
@@ -12012,7 +12372,7 @@ and if you're using multiple threads you should provide your own locking
 around entire such context partitions.
 
 @node Error-handling<3>,Debugging<2>,Thread-safety<2>,Compilation contexts<2>
-@anchor{cp/topics/contexts error-handling}@anchor{127}
+@anchor{cp/topics/contexts error-handling}@anchor{135}
 @subsubsection Error-handling
 
 
@@ -12025,10 +12385,10 @@ NULL.  You don't have to check everywhere for NULL results, since the
 API gracefully handles a NULL being passed in for any argument.
 
 Errors are printed on stderr and can be queried using
-@pxref{128,,gccjit;;context;;get_first_error()}.
+@pxref{136,,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{128}
+@anchor{cp/topics/contexts gccjit context get_first_error__gccjit contextP}@anchor{136}
 @deffn {C++ Function} const char* gccjit::context::get_first_error (gccjit::context* ctxt)
 
 Returns the first error message that occurred on the context.
@@ -12040,18 +12400,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{129}
+@anchor{cp/topics/contexts debugging}@anchor{137}
 @subsubsection Debugging
 
 
 @geindex gccjit;;context;;dump_to_file (C++ function)
-@anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{12a}
+@anchor{cp/topics/contexts gccjit context dump_to_file__ssCR i}@anchor{138}
 @deffn {C++ Function} void gccjit::context::dump_to_file (const std::string& path, int update_locations)
 
 To help with debugging: dump a C-like representation to the given path,
 describing what's been set up on the context.
 
-If "update_locations" is true, then also set up @pxref{12b,,gccjit;;location}
+If "update_locations" is true, then also set up @pxref{139,,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
@@ -12059,7 +12419,7 @@ code in a debugger.
 @end deffn
 
 @geindex gccjit;;context;;dump_reproducer_to_file (C++ function)
-@anchor{cp/topics/contexts gccjit context dump_reproducer_to_file__gcc_jit_contextP cCP}@anchor{12c}
+@anchor{cp/topics/contexts gccjit context dump_reproducer_to_file__gcc_jit_contextP cCP}@anchor{13a}
 @deffn {C++ Function} void gccjit::context::dump_reproducer_to_file (gcc_jit_context* ctxt, const char* path)
 
 This is a thin wrapper around the C API
@@ -12071,7 +12431,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{12d}
+@anchor{cp/topics/contexts options}@anchor{13b}
 @subsubsection Options
 
 
@@ -12084,12 +12444,12 @@ for seeing what the C++ bindings are doing at the C level.
 @end menu
 
 @node String Options<2>,Boolean options<2>,,Options<4>
-@anchor{cp/topics/contexts string-options}@anchor{12e}
+@anchor{cp/topics/contexts string-options}@anchor{13c}
 @subsubsection String Options
 
 
 @geindex gccjit;;context;;set_str_option (C++ function)
-@anchor{cp/topics/contexts gccjit context set_str_option__enum cCP}@anchor{12f}
+@anchor{cp/topics/contexts gccjit context set_str_option__enum cCP}@anchor{13d}
 @deffn {C++ Function} void gccjit::context::set_str_option (enum gcc_jit_str_option, const char* value)
 
 Set a string option of the context.
@@ -12100,12 +12460,12 @@ meaning.
 @end deffn
 
 @node Boolean options<2>,Integer options<2>,String Options<2>,Options<4>
-@anchor{cp/topics/contexts boolean-options}@anchor{130}
+@anchor{cp/topics/contexts boolean-options}@anchor{13e}
 @subsubsection Boolean options
 
 
 @geindex gccjit;;context;;set_bool_option (C++ function)
-@anchor{cp/topics/contexts gccjit context set_bool_option__enum i}@anchor{fe}
+@anchor{cp/topics/contexts gccjit context set_bool_option__enum i}@anchor{10c}
 @deffn {C++ Function} void gccjit::context::set_bool_option (enum gcc_jit_bool_option, int value)
 
 Set a boolean option of the context.
@@ -12116,7 +12476,7 @@ meaning.
 @end deffn
 
 @geindex gccjit;;context;;set_bool_allow_unreachable_blocks (C++ function)
-@anchor{cp/topics/contexts gccjit context set_bool_allow_unreachable_blocks__i}@anchor{131}
+@anchor{cp/topics/contexts gccjit context set_bool_allow_unreachable_blocks__i}@anchor{13f}
 @deffn {C++ Function} void gccjit::context::set_bool_allow_unreachable_blocks (int bool_value)
 
 By default, libgccjit will issue an error about unreachable blocks
@@ -12137,12 +12497,12 @@ its presence using
 @end deffn
 
 @node Integer options<2>,Additional command-line options<2>,Boolean options<2>,Options<4>
-@anchor{cp/topics/contexts integer-options}@anchor{132}
+@anchor{cp/topics/contexts integer-options}@anchor{140}
 @subsubsection Integer options
 
 
 @geindex gccjit;;context;;set_int_option (C++ function)
-@anchor{cp/topics/contexts gccjit context set_int_option__enum i}@anchor{ff}
+@anchor{cp/topics/contexts gccjit context set_int_option__enum i}@anchor{10d}
 @deffn {C++ Function} void gccjit::context::set_int_option (enum gcc_jit_int_option, int value)
 
 Set an integer option of the context.
@@ -12153,12 +12513,12 @@ meaning.
 @end deffn
 
 @node Additional command-line options<2>,,Integer options<2>,Options<4>
-@anchor{cp/topics/contexts additional-command-line-options}@anchor{133}
+@anchor{cp/topics/contexts additional-command-line-options}@anchor{141}
 @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{134}
+@anchor{cp/topics/contexts gccjit context add_command_line_option__cCP}@anchor{142}
 @deffn {C++ Function} void gccjit::context::add_command_line_option (const char* optname)
 
 Add an arbitrary gcc command-line option to the context for use
@@ -12195,18 +12555,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{135}@anchor{cp/topics/objects doc}@anchor{136}
+@anchor{cp/topics/objects objects}@anchor{143}@anchor{cp/topics/objects doc}@anchor{144}
 @subsection Objects
 
 
 @geindex gccjit;;object (C++ class)
-@anchor{cp/topics/objects gccjit object}@anchor{137}
+@anchor{cp/topics/objects gccjit object}@anchor{145}
 @deffn {C++ Class} gccjit::object
 @end deffn
 
 Almost every entity in the API (with the exception of
-@pxref{123,,gccjit;;context} and @pxref{16,,gcc_jit_result *}) is a
-"contextual" object, a @pxref{137,,gccjit;;object}.
+@pxref{131,,gccjit;;context} and @pxref{16,,gcc_jit_result *}) is a
+"contextual" object, a @pxref{145,,gccjit;;object}.
 
 A JIT object:
 
@@ -12216,7 +12576,7 @@ A JIT object:
 @itemize *
 
 @item 
-is associated with a @pxref{123,,gccjit;;context}.
+is associated with a @pxref{131,,gccjit;;context}.
 
 @item 
 is automatically cleaned up for you when its context is released so
@@ -12243,17 +12603,17 @@ The C++ class hierarchy within the @code{gccjit} namespace looks like this:
 
 @noindent
 
-The @pxref{137,,gccjit;;object} base class has the following operations:
+The @pxref{145,,gccjit;;object} base class has the following operations:
 
 @geindex gccjit;;object;;get_context (C++ function)
-@anchor{cp/topics/objects gccjit object get_contextC}@anchor{138}
+@anchor{cp/topics/objects gccjit object get_contextC}@anchor{146}
 @deffn {C++ Function} gccjit::context gccjit::object::get_context () const
 
 Which context is the obj within?
 @end deffn
 
 @geindex gccjit;;object;;get_debug_string (C++ function)
-@anchor{cp/topics/objects gccjit object get_debug_stringC}@anchor{f9}
+@anchor{cp/topics/objects gccjit object get_debug_stringC}@anchor{107}
 @deffn {C++ Function} std::string gccjit::object::get_debug_string () const
 
 Generate a human-readable description for the given object.
@@ -12293,16 +12653,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{139}@anchor{cp/topics/types types}@anchor{13a}
+@anchor{cp/topics/types doc}@anchor{147}@anchor{cp/topics/types types}@anchor{148}
 @subsection Types
 
 
 @geindex gccjit;;type (C++ class)
-@anchor{cp/topics/types gccjit type}@anchor{13b}
+@anchor{cp/topics/types gccjit type}@anchor{149}
 @deffn {C++ Class} gccjit::type
 
 gccjit::type represents a type within the library.  It is a subclass
-of @pxref{137,,gccjit;;object}.
+of @pxref{145,,gccjit;;object}.
 @end deffn
 
 Types can be created in several ways:
@@ -12312,7 +12672,7 @@ Types can be created in several ways:
 
 @item 
 fundamental types can be accessed using
-@pxref{f7,,gccjit;;context;;get_type()}:
+@pxref{105,,gccjit;;context;;get_type()}:
 
 @example
 gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);
@@ -12332,7 +12692,7 @@ See @pxref{b,,gcc_jit_context_get_type()} for the available types.
 
 @item 
 derived types can be accessed by using functions such as
-@pxref{13c,,gccjit;;type;;get_pointer()} and @pxref{13d,,gccjit;;type;;get_const()}:
+@pxref{14a,,gccjit;;type;;get_pointer()} and @pxref{14b,,gccjit;;type;;get_const()}:
 
 @example
 gccjit::type const_int_star = int_type.get_const ().get_pointer ();
@@ -12353,12 +12713,12 @@ by creating structures (see below).
 @end menu
 
 @node Standard types<2>,Pointers const and volatile<2>,,Types<2>
-@anchor{cp/topics/types standard-types}@anchor{13e}
+@anchor{cp/topics/types standard-types}@anchor{14c}
 @subsubsection Standard types
 
 
 @geindex gccjit;;context;;get_type (C++ function)
-@anchor{cp/topics/types gccjit context get_type__enum}@anchor{f7}
+@anchor{cp/topics/types gccjit context get_type__enum}@anchor{105}
 @deffn {C++ Function} gccjit::type gccjit::context::get_type (enum gcc_jit_types)
 
 Access a specific type.  This is a thin wrapper around
@@ -12366,14 +12726,14 @@ Access a specific type.  This is a thin wrapper around
 @end deffn
 
 @geindex gccjit;;context;;get_int_type (C++ function)
-@anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{13f}
+@anchor{cp/topics/types gccjit context get_int_type__s i}@anchor{14d}
 @deffn {C++ Function} gccjit::type gccjit::context::get_int_type (size_t num_bytes, int is_signed)
 
 Access the integer type of the given size.
 @end deffn
 
 @geindex gccjit;;context;;get_int_type<T> (C++ function)
-@anchor{cp/topics/types gccjit context get_int_type T}@anchor{140}
+@anchor{cp/topics/types gccjit context get_int_type T}@anchor{14e}
 @deffn {C++ Function} gccjit::type gccjit::context::get_int_type<T> ()
 
 Access the given integer type.  For example, you could map the
@@ -12387,12 +12747,12 @@ gccjit::type t = ctxt.get_int_type <unsigned short> ();
 @end deffn
 
 @node Pointers const and volatile<2>,Structures and unions<2>,Standard types<2>,Types<2>
-@anchor{cp/topics/types pointers-const-and-volatile}@anchor{141}
+@anchor{cp/topics/types pointers-const-and-volatile}@anchor{14f}
 @subsubsection Pointers, @cite{const}, and @cite{volatile}
 
 
 @geindex gccjit;;type;;get_pointer (C++ function)
-@anchor{cp/topics/types gccjit type get_pointer}@anchor{13c}
+@anchor{cp/topics/types gccjit type get_pointer}@anchor{14a}
 @deffn {C++ Function} gccjit::type gccjit::type::get_pointer ()
 
 Given type "T", get type "T*".
@@ -12401,21 +12761,21 @@ Given type "T", get type "T*".
 @c FIXME: get_const doesn't seem to exist
 
 @geindex gccjit;;type;;get_const (C++ function)
-@anchor{cp/topics/types gccjit type get_const}@anchor{13d}
+@anchor{cp/topics/types gccjit type get_const}@anchor{14b}
 @deffn {C++ Function} gccjit::type gccjit::type::get_const ()
 
 Given type "T", get type "const T".
 @end deffn
 
 @geindex gccjit;;type;;get_volatile (C++ function)
-@anchor{cp/topics/types gccjit type get_volatile}@anchor{142}
+@anchor{cp/topics/types gccjit type get_volatile}@anchor{150}
 @deffn {C++ Function} gccjit::type gccjit::type::get_volatile ()
 
 Given type "T", get type "volatile T".
 @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{143}
+@anchor{cp/topics/types gccjit context new_array_type__gccjit type i gccjit location}@anchor{151}
 @deffn {C++ Function} gccjit::type gccjit::context::new_array_type (gccjit::type element_type, int num_elements, gccjit::location loc)
 
 Given type "T", get type "T[N]" (for a constant N).
@@ -12423,31 +12783,31 @@ Param "loc" is optional.
 @end deffn
 
 @node Structures and unions<2>,,Pointers const and volatile<2>,Types<2>
-@anchor{cp/topics/types structures-and-unions}@anchor{144}
+@anchor{cp/topics/types structures-and-unions}@anchor{152}
 @subsubsection Structures and unions
 
 
 @geindex gccjit;;struct_ (C++ class)
-@anchor{cp/topics/types gccjit struct_}@anchor{145}
+@anchor{cp/topics/types gccjit struct_}@anchor{153}
 @deffn {C++ Class} gccjit::struct_
 @end deffn
 
 A compound type analagous to a C @cite{struct}.
 
-@pxref{145,,gccjit;;struct_} is a subclass of @pxref{13b,,gccjit;;type} (and thus
-of @pxref{137,,gccjit;;object} in turn).
+@pxref{153,,gccjit;;struct_} is a subclass of @pxref{149,,gccjit;;type} (and thus
+of @pxref{145,,gccjit;;object} in turn).
 
 @geindex gccjit;;field (C++ class)
-@anchor{cp/topics/types gccjit field}@anchor{146}
+@anchor{cp/topics/types gccjit field}@anchor{154}
 @deffn {C++ Class} gccjit::field
 @end deffn
 
-A field within a @pxref{145,,gccjit;;struct_}.
+A field within a @pxref{153,,gccjit;;struct_}.
 
-@pxref{146,,gccjit;;field} is a subclass of @pxref{137,,gccjit;;object}.
+@pxref{154,,gccjit;;field} is a subclass of @pxref{145,,gccjit;;object}.
 
-You can model C @cite{struct} types by creating @pxref{145,,gccjit;;struct_} and
-@pxref{146,,gccjit;;field} instances, in either order:
+You can model C @cite{struct} types by creating @pxref{153,,gccjit;;struct_} and
+@pxref{154,,gccjit;;field} instances, in either order:
 
 
 @itemize *
@@ -12503,14 +12863,14 @@ node.set_fields (fields);
 @c FIXME: the above API doesn't seem to exist yet
 
 @geindex gccjit;;context;;new_field (C++ function)
-@anchor{cp/topics/types gccjit context new_field__gccjit type cCP gccjit location}@anchor{147}
+@anchor{cp/topics/types gccjit context new_field__gccjit type cCP gccjit location}@anchor{155}
 @deffn {C++ Function} gccjit::field gccjit::context::new_field (gccjit::type type, const char* name, gccjit::location loc)
 
 Construct a new field, with the given type and name.
 @end deffn
 
 @geindex gccjit;;context;;new_struct_type (C++ function)
-@anchor{cp/topics/types gccjit context new_struct_type__ssCR std vector field R gccjit location}@anchor{148}
+@anchor{cp/topics/types gccjit context new_struct_type__ssCR std vector field R gccjit location}@anchor{156}
 @deffn {C++ Function} gccjit::struct_ gccjit::context::new_struct_type (const std::string& name, std::vector<field>& fields, gccjit::location loc)
 
 @quotation
@@ -12520,7 +12880,7 @@ Construct a new struct type, with the given name and fields.
 @end deffn
 
 @geindex gccjit;;context;;new_opaque_struct (C++ function)
-@anchor{cp/topics/types gccjit context new_opaque_struct__ssCR gccjit location}@anchor{149}
+@anchor{cp/topics/types gccjit context new_opaque_struct__ssCR gccjit location}@anchor{157}
 @deffn {C++ Function} gccjit::struct_ gccjit::context::new_opaque_struct (const std::string& name, gccjit::location loc)
 
 Construct a new struct type, with the given name, but without
@@ -12547,7 +12907,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{14a}@anchor{cp/topics/expressions doc}@anchor{14b}
+@anchor{cp/topics/expressions expressions}@anchor{158}@anchor{cp/topics/expressions doc}@anchor{159}
 @subsection Expressions
 
 
@@ -12573,17 +12933,17 @@ Lvalues
 
 
 @node Rvalues<2>,Lvalues<2>,,Expressions<2>
-@anchor{cp/topics/expressions rvalues}@anchor{14c}
+@anchor{cp/topics/expressions rvalues}@anchor{15a}
 @subsubsection Rvalues
 
 
 @geindex gccjit;;rvalue (C++ class)
-@anchor{cp/topics/expressions gccjit rvalue}@anchor{14d}
+@anchor{cp/topics/expressions gccjit rvalue}@anchor{15b}
 @deffn {C++ Class} gccjit::rvalue
 @end deffn
 
-A @pxref{14d,,gccjit;;rvalue} is an expression that can be computed.  It is a
-subclass of @pxref{137,,gccjit;;object}, and is a thin wrapper around
+A @pxref{15b,,gccjit;;rvalue} is an expression that can be computed.  It is a
+subclass of @pxref{145,,gccjit;;object}, and is a thin wrapper around
 @pxref{13,,gcc_jit_rvalue *} from the C API.
 
 It can be simple, e.g.:
@@ -12629,7 +12989,7 @@ Every rvalue has an associated type, and the API will check to ensure
 that types match up correctly (otherwise the context will emit an error).
 
 @geindex gccjit;;rvalue;;get_type (C++ function)
-@anchor{cp/topics/expressions gccjit rvalue get_type}@anchor{14e}
+@anchor{cp/topics/expressions gccjit rvalue get_type}@anchor{15c}
 @deffn {C++ Function} gccjit::type gccjit::rvalue::get_type ()
 
 Get the type of this rvalue.
@@ -12646,12 +13006,12 @@ Get the type of this rvalue.
 @end menu
 
 @node Simple expressions<2>,Unary Operations<2>,,Rvalues<2>
-@anchor{cp/topics/expressions simple-expressions}@anchor{14f}
+@anchor{cp/topics/expressions simple-expressions}@anchor{15d}
 @subsubsection Simple expressions
 
 
 @geindex gccjit;;context;;new_rvalue (C++ function)
-@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{10b}
+@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type iC}@anchor{119}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, int value) const
 
 Given a numeric type (integer or floating point), build an rvalue for
@@ -12659,7 +13019,7 @@ the given constant @code{int} value.
 @end deffn
 
 @geindex gccjit;;context;;new_rvalue (C++ function)
-@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type lC}@anchor{150}
+@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type lC}@anchor{15e}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, long value) const
 
 Given a numeric type (integer or floating point), build an rvalue for
@@ -12667,7 +13027,7 @@ the given constant @code{long} value.
 @end deffn
 
 @geindex gccjit;;context;;zero (C++ function)
-@anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{107}
+@anchor{cp/topics/expressions gccjit context zero__gccjit typeC}@anchor{115}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::zero (gccjit::type numeric_type) const
 
 Given a numeric type (integer or floating point), get the rvalue for
@@ -12681,7 +13041,7 @@ ctxt.new_rvalue (numeric_type, 0)
 @end deffn
 
 @geindex gccjit;;context;;one (C++ function)
-@anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{151}
+@anchor{cp/topics/expressions gccjit context one__gccjit typeC}@anchor{15f}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::one (gccjit::type numeric_type) const
 
 Given a numeric type (integer or floating point), get the rvalue for
@@ -12695,7 +13055,7 @@ ctxt.new_rvalue (numeric_type, 1)
 @end deffn
 
 @geindex gccjit;;context;;new_rvalue (C++ function)
-@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{152}
+@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type doubleC}@anchor{160}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type numeric_type, double value) const
 
 Given a numeric type (integer or floating point), build an rvalue for
@@ -12703,14 +13063,14 @@ the given constant @code{double} value.
 @end deffn
 
 @geindex gccjit;;context;;new_rvalue (C++ function)
-@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type voidPC}@anchor{153}
+@anchor{cp/topics/expressions gccjit context new_rvalue__gccjit type voidPC}@anchor{161}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (gccjit::type pointer_type, void* value) const
 
 Given a pointer type, build an rvalue for the given address.
 @end deffn
 
 @geindex gccjit;;context;;new_rvalue (C++ function)
-@anchor{cp/topics/expressions gccjit context new_rvalue__ssCRC}@anchor{154}
+@anchor{cp/topics/expressions gccjit context new_rvalue__ssCRC}@anchor{162}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_rvalue (const std::string& value) const
 
 Generate an rvalue of type @code{GCC_JIT_TYPE_CONST_CHAR_PTR} for
@@ -12718,12 +13078,12 @@ the given string.  This is akin to a string literal.
 @end deffn
 
 @node Unary Operations<2>,Binary Operations<2>,Simple expressions<2>,Rvalues<2>
-@anchor{cp/topics/expressions unary-operations}@anchor{155}
+@anchor{cp/topics/expressions unary-operations}@anchor{163}
 @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{156}
+@anchor{cp/topics/expressions gccjit context new_unary_op__enum gccjit type gccjit rvalue gccjit location}@anchor{164}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_unary_op (enum gcc_jit_unary_op, gccjit::type result_type, gccjit::rvalue rvalue, gccjit::location loc)
 
 Build a unary operation out of an input rvalue.
@@ -12739,7 +13099,7 @@ There are shorter ways to spell the various specific kinds of unary
 operation:
 
 @geindex gccjit;;context;;new_minus (C++ function)
-@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit location}@anchor{157}
+@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit location}@anchor{165}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
 
 Negate an arithmetic value; for example:
@@ -12760,7 +13120,7 @@ builds the equivalent of this C expression:
 @end deffn
 
 @geindex new_bitwise_negate (C++ function)
-@anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{158}
+@anchor{cp/topics/expressions new_bitwise_negate__gccjit type gccjit rvalue gccjit location}@anchor{166}
 @deffn {C++ Function} gccjit::rvalue new_bitwise_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
 
 Bitwise negation of an integer value (one's complement); for example:
@@ -12781,7 +13141,7 @@ builds the equivalent of this C expression:
 @end deffn
 
 @geindex new_logical_negate (C++ function)
-@anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{159}
+@anchor{cp/topics/expressions new_logical_negate__gccjit type gccjit rvalue gccjit location}@anchor{167}
 @deffn {C++ Function} gccjit::rvalue new_logical_negate (gccjit::type result_type, gccjit::rvalue a, gccjit::location loc)
 
 Logical negation of an arithmetic or pointer value; for example:
@@ -12804,7 +13164,7 @@ builds the equivalent of this C expression:
 The most concise way to spell them is with overloaded operators:
 
 @geindex operator- (C++ function)
-@anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{15a}
+@anchor{cp/topics/expressions sub-operator__gccjit rvalue}@anchor{168}
 @deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a)
 
 @example
@@ -12815,7 +13175,7 @@ gccjit::rvalue negpi = -pi;
 @end deffn
 
 @geindex operator~ (C++ function)
-@anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{15b}
+@anchor{cp/topics/expressions inv-operator__gccjit rvalue}@anchor{169}
 @deffn {C++ Function} gccjit::rvalue operator~ (gccjit::rvalue a)
 
 @example
@@ -12826,7 +13186,7 @@ gccjit::rvalue mask = ~a;
 @end deffn
 
 @geindex operator! (C++ function)
-@anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{15c}
+@anchor{cp/topics/expressions not-operator__gccjit rvalue}@anchor{16a}
 @deffn {C++ Function} gccjit::rvalue operator! (gccjit::rvalue a)
 
 @example
@@ -12837,12 +13197,12 @@ gccjit::rvalue guard = !cond;
 @end deffn
 
 @node Binary Operations<2>,Comparisons<2>,Unary Operations<2>,Rvalues<2>
-@anchor{cp/topics/expressions binary-operations}@anchor{15d}
+@anchor{cp/topics/expressions binary-operations}@anchor{16b}
 @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{fb}
+@anchor{cp/topics/expressions gccjit context new_binary_op__enum gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{109}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_binary_op (enum gcc_jit_binary_op, gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 
 Build a binary operation out of two constituent rvalues.
@@ -12858,59 +13218,59 @@ There are shorter ways to spell the various specific kinds of binary
 operation:
 
 @geindex gccjit;;context;;new_plus (C++ function)
-@anchor{cp/topics/expressions gccjit context new_plus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{15e}
+@anchor{cp/topics/expressions gccjit context new_plus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{16c}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_plus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_minus (C++ function)
-@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{15f}
+@anchor{cp/topics/expressions gccjit context new_minus__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{16d}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_minus (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_mult (C++ function)
-@anchor{cp/topics/expressions gccjit context new_mult__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{160}
+@anchor{cp/topics/expressions gccjit context new_mult__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{16e}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_mult (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_divide (C++ function)
-@anchor{cp/topics/expressions gccjit context new_divide__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{161}
+@anchor{cp/topics/expressions gccjit context new_divide__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{16f}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_divide (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_modulo (C++ function)
-@anchor{cp/topics/expressions gccjit context new_modulo__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{162}
+@anchor{cp/topics/expressions gccjit context new_modulo__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{170}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_modulo (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_bitwise_and (C++ function)
-@anchor{cp/topics/expressions gccjit context new_bitwise_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{163}
+@anchor{cp/topics/expressions gccjit context new_bitwise_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{171}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_bitwise_xor (C++ function)
-@anchor{cp/topics/expressions gccjit context new_bitwise_xor__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{164}
+@anchor{cp/topics/expressions gccjit context new_bitwise_xor__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{172}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_xor (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_bitwise_or (C++ function)
-@anchor{cp/topics/expressions gccjit context new_bitwise_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{165}
+@anchor{cp/topics/expressions gccjit context new_bitwise_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{173}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_bitwise_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_logical_and (C++ function)
-@anchor{cp/topics/expressions gccjit context new_logical_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{166}
+@anchor{cp/topics/expressions gccjit context new_logical_and__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{174}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_and (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_logical_or (C++ function)
-@anchor{cp/topics/expressions gccjit context new_logical_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{167}
+@anchor{cp/topics/expressions gccjit context new_logical_or__gccjit type gccjit rvalue gccjit rvalue gccjit location}@anchor{175}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_logical_or (gccjit::type result_type, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 The most concise way to spell them is with overloaded operators:
 
 @geindex operator+ (C++ function)
-@anchor{cp/topics/expressions add-operator__gccjit rvalue gccjit rvalue}@anchor{168}
+@anchor{cp/topics/expressions add-operator__gccjit rvalue gccjit rvalue}@anchor{176}
 @deffn {C++ Function} gccjit::rvalue operator+ (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -12921,7 +13281,7 @@ gccjit::rvalue sum = a + b;
 @end deffn
 
 @geindex operator- (C++ function)
-@anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{169}
+@anchor{cp/topics/expressions sub-operator__gccjit rvalue gccjit rvalue}@anchor{177}
 @deffn {C++ Function} gccjit::rvalue operator- (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -12932,7 +13292,7 @@ gccjit::rvalue diff = a - b;
 @end deffn
 
 @geindex operator* (C++ function)
-@anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{16a}
+@anchor{cp/topics/expressions mul-operator__gccjit rvalue gccjit rvalue}@anchor{178}
 @deffn {C++ Function} gccjit::rvalue operator* (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -12943,7 +13303,7 @@ gccjit::rvalue prod = a * b;
 @end deffn
 
 @geindex operator/ (C++ function)
-@anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{16b}
+@anchor{cp/topics/expressions div-operator__gccjit rvalue gccjit rvalue}@anchor{179}
 @deffn {C++ Function} gccjit::rvalue operator/ (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -12954,7 +13314,7 @@ gccjit::rvalue result = a / b;
 @end deffn
 
 @geindex operator% (C++ function)
-@anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{16c}
+@anchor{cp/topics/expressions mod-operator__gccjit rvalue gccjit rvalue}@anchor{17a}
 @deffn {C++ Function} gccjit::rvalue operator% (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -12965,7 +13325,7 @@ gccjit::rvalue mod = a % b;
 @end deffn
 
 @geindex operator& (C++ function)
-@anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{16d}
+@anchor{cp/topics/expressions and-operator__gccjit rvalue gccjit rvalue}@anchor{17b}
 @deffn {C++ Function} gccjit::rvalue operator& (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -12976,7 +13336,7 @@ gccjit::rvalue x = a & b;
 @end deffn
 
 @geindex operator^ (C++ function)
-@anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{16e}
+@anchor{cp/topics/expressions xor-operator__gccjit rvalue gccjit rvalue}@anchor{17c}
 @deffn {C++ Function} gccjit::rvalue operator^ (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -12987,7 +13347,7 @@ gccjit::rvalue x = a ^ b;
 @end deffn
 
 @geindex operator| (C++ function)
-@anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{16f}
+@anchor{cp/topics/expressions or-operator__gccjit rvalue gccjit rvalue}@anchor{17d}
 @deffn {C++ Function} gccjit::rvalue operator| (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -12998,7 +13358,7 @@ gccjit::rvalue x = a | b;
 @end deffn
 
 @geindex operator&& (C++ function)
-@anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{170}
+@anchor{cp/topics/expressions sand-operator__gccjit rvalue gccjit rvalue}@anchor{17e}
 @deffn {C++ Function} gccjit::rvalue operator&& (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -13009,7 +13369,7 @@ gccjit::rvalue cond = a && b;
 @end deffn
 
 @geindex operator|| (C++ function)
-@anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{171}
+@anchor{cp/topics/expressions sor-operator__gccjit rvalue gccjit rvalue}@anchor{17f}
 @deffn {C++ Function} gccjit::rvalue operator|| (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -13032,12 +13392,12 @@ gccjit::rvalue discriminant = (b * b) - (four * a * c);
 @end quotation
 
 @node Comparisons<2>,Function calls<2>,Binary Operations<2>,Rvalues<2>
-@anchor{cp/topics/expressions comparisons}@anchor{172}
+@anchor{cp/topics/expressions comparisons}@anchor{180}
 @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{108}
+@anchor{cp/topics/expressions gccjit context new_comparison__enum gccjit rvalue gccjit rvalue gccjit location}@anchor{116}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_comparison (enum gcc_jit_comparison, gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 
 Build a boolean rvalue out of the comparison of two other rvalues.
@@ -13053,39 +13413,39 @@ There are shorter ways to spell the various specific kinds of binary
 operation:
 
 @geindex gccjit;;context;;new_eq (C++ function)
-@anchor{cp/topics/expressions gccjit context new_eq__gccjit rvalue gccjit rvalue gccjit location}@anchor{173}
+@anchor{cp/topics/expressions gccjit context new_eq__gccjit rvalue gccjit rvalue gccjit location}@anchor{181}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_eq (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_ne (C++ function)
-@anchor{cp/topics/expressions gccjit context new_ne__gccjit rvalue gccjit rvalue gccjit location}@anchor{174}
+@anchor{cp/topics/expressions gccjit context new_ne__gccjit rvalue gccjit rvalue gccjit location}@anchor{182}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_ne (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_lt (C++ function)
-@anchor{cp/topics/expressions gccjit context new_lt__gccjit rvalue gccjit rvalue gccjit location}@anchor{175}
+@anchor{cp/topics/expressions gccjit context new_lt__gccjit rvalue gccjit rvalue gccjit location}@anchor{183}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_lt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_le (C++ function)
-@anchor{cp/topics/expressions gccjit context new_le__gccjit rvalue gccjit rvalue gccjit location}@anchor{176}
+@anchor{cp/topics/expressions gccjit context new_le__gccjit rvalue gccjit rvalue gccjit location}@anchor{184}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_le (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_gt (C++ function)
-@anchor{cp/topics/expressions gccjit context new_gt__gccjit rvalue gccjit rvalue gccjit location}@anchor{177}
+@anchor{cp/topics/expressions gccjit context new_gt__gccjit rvalue gccjit rvalue gccjit location}@anchor{185}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_gt (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 @geindex gccjit;;context;;new_ge (C++ function)
-@anchor{cp/topics/expressions gccjit context new_ge__gccjit rvalue gccjit rvalue gccjit location}@anchor{178}
+@anchor{cp/topics/expressions gccjit context new_ge__gccjit rvalue gccjit rvalue gccjit location}@anchor{186}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_ge (gccjit::rvalue a, gccjit::rvalue b, gccjit::location loc)
 @end deffn
 
 The most concise way to spell them is with overloaded operators:
 
 @geindex operator== (C++ function)
-@anchor{cp/topics/expressions eq-operator__gccjit rvalue gccjit rvalue}@anchor{179}
+@anchor{cp/topics/expressions eq-operator__gccjit rvalue gccjit rvalue}@anchor{187}
 @deffn {C++ Function} gccjit::rvalue operator== (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -13096,7 +13456,7 @@ gccjit::rvalue cond = (a == ctxt.zero (t_int));
 @end deffn
 
 @geindex operator!= (C++ function)
-@anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{17a}
+@anchor{cp/topics/expressions neq-operator__gccjit rvalue gccjit rvalue}@anchor{188}
 @deffn {C++ Function} gccjit::rvalue operator!= (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -13107,7 +13467,7 @@ gccjit::rvalue cond = (i != j);
 @end deffn
 
 @geindex operator< (C++ function)
-@anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{17b}
+@anchor{cp/topics/expressions lt-operator__gccjit rvalue gccjit rvalue}@anchor{189}
 @deffn {C++ Function} gccjit::rvalue operator< (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -13118,7 +13478,7 @@ gccjit::rvalue cond = i < n;
 @end deffn
 
 @geindex operator<= (C++ function)
-@anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{17c}
+@anchor{cp/topics/expressions lte-operator__gccjit rvalue gccjit rvalue}@anchor{18a}
 @deffn {C++ Function} gccjit::rvalue operator<= (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -13129,7 +13489,7 @@ gccjit::rvalue cond = i <= n;
 @end deffn
 
 @geindex operator> (C++ function)
-@anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{17d}
+@anchor{cp/topics/expressions gt-operator__gccjit rvalue gccjit rvalue}@anchor{18b}
 @deffn {C++ Function} gccjit::rvalue operator> (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -13140,7 +13500,7 @@ gccjit::rvalue cond = (ch > limit);
 @end deffn
 
 @geindex operator>= (C++ function)
-@anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{17e}
+@anchor{cp/topics/expressions gte-operator__gccjit rvalue gccjit rvalue}@anchor{18c}
 @deffn {C++ Function} gccjit::rvalue operator>= (gccjit::rvalue a, gccjit::rvalue b)
 
 @example
@@ -13153,12 +13513,12 @@ gccjit::rvalue cond = (score >= ctxt.new_rvalue (t_int, 100));
 @c TODO: beyond this point
 
 @node Function calls<2>,Type-coercion<2>,Comparisons<2>,Rvalues<2>
-@anchor{cp/topics/expressions function-calls}@anchor{17f}
+@anchor{cp/topics/expressions function-calls}@anchor{18d}
 @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{180}
+@anchor{cp/topics/expressions gcc_jit_context_new_call__gcc_jit_contextP gcc_jit_locationP gcc_jit_functionP i gcc_jit_rvaluePP}@anchor{18e}
 @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
@@ -13167,14 +13527,14 @@ call to the function, with the result as an rvalue.
 @cartouche
 @quotation Note 
 @code{gccjit::context::new_call()} merely builds a
-@pxref{14d,,gccjit;;rvalue} i.e. an expression that can be evaluated,
+@pxref{15b,,gccjit;;rvalue} i.e. an expression that can be evaluated,
 perhaps as part of a more complicated expression.
 The call @emph{won't} happen unless you add a statement to a function
 that evaluates the expression.
 
 For example, if you want to call a function and discard the result
 (or to call a function with @code{void} return type), use
-@pxref{181,,gccjit;;block;;add_eval()}:
+@pxref{18f,,gccjit;;block;;add_eval()}:
 
 @example
 /* Add "(void)printf (arg0, arg1);".  */
@@ -13187,12 +13547,12 @@ block.add_eval (ctxt.new_call (printf_func, arg0, arg1));
 @end deffn
 
 @node Type-coercion<2>,,Function calls<2>,Rvalues<2>
-@anchor{cp/topics/expressions type-coercion}@anchor{182}
+@anchor{cp/topics/expressions type-coercion}@anchor{190}
 @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{183}
+@anchor{cp/topics/expressions gccjit context new_cast__gccjit rvalue gccjit type gccjit location}@anchor{191}
 @deffn {C++ Function} gccjit::rvalue gccjit::context::new_cast (gccjit::rvalue rvalue, gccjit::type type, gccjit::location loc)
 
 Given an rvalue of T, construct another rvalue of another type.
@@ -13217,24 +13577,24 @@ P*  <-> Q*, for pointer types P and Q
 @end deffn
 
 @node Lvalues<2>,Working with pointers structs and unions<2>,Rvalues<2>,Expressions<2>
-@anchor{cp/topics/expressions lvalues}@anchor{184}
+@anchor{cp/topics/expressions lvalues}@anchor{192}
 @subsubsection Lvalues
 
 
 @geindex gccjit;;lvalue (C++ class)
-@anchor{cp/topics/expressions gccjit lvalue}@anchor{185}
+@anchor{cp/topics/expressions gccjit lvalue}@anchor{193}
 @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{14d,,gccjit;;rvalue}, where the rvalue is computed by reading from the
+@pxref{15b,,gccjit;;rvalue}, where the rvalue is computed by reading from the
 storage area.
 
 It iss a thin wrapper around @pxref{24,,gcc_jit_lvalue *} from the C API.
 
 @geindex gccjit;;lvalue;;get_address (C++ function)
-@anchor{cp/topics/expressions gccjit lvalue get_address__gccjit location}@anchor{186}
+@anchor{cp/topics/expressions gccjit lvalue get_address__gccjit location}@anchor{194}
 @deffn {C++ Function} gccjit::rvalue gccjit::lvalue::get_address (gccjit::location loc)
 
 Take the address of an lvalue; analogous to:
@@ -13256,12 +13616,12 @@ Parameter "loc" is optional.
 @end menu
 
 @node Global variables<2>,,,Lvalues<2>
-@anchor{cp/topics/expressions global-variables}@anchor{187}
+@anchor{cp/topics/expressions global-variables}@anchor{195}
 @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{188}
+@anchor{cp/topics/expressions gccjit context new_global__enum gccjit type cCP gccjit location}@anchor{196}
 @deffn {C++ Function} gccjit::lvalue gccjit::context::new_global (enum gcc_jit_global_kind, gccjit::type type, const char* name, gccjit::location loc)
 
 Add a new global variable of the given type and name to the context.
@@ -13271,12 +13631,12 @@ 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{189}
+@anchor{cp/topics/expressions working-with-pointers-structs-and-unions}@anchor{197}
 @subsubsection Working with pointers, structs and unions
 
 
 @geindex gccjit;;rvalue;;dereference (C++ function)
-@anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{18a}
+@anchor{cp/topics/expressions gccjit rvalue dereference__gccjit location}@anchor{198}
 @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference (gccjit::location loc)
 
 Given an rvalue of pointer type @code{T *}, dereferencing the pointer,
@@ -13297,7 +13657,7 @@ If you don't need to specify the location, this can also be expressed using
 an overloaded operator:
 
 @geindex gccjit;;rvalue;;operator* (C++ function)
-@anchor{cp/topics/expressions gccjit rvalue mul-operator}@anchor{18b}
+@anchor{cp/topics/expressions gccjit rvalue mul-operator}@anchor{199}
 @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::operator* ()
 
 @example
@@ -13310,7 +13670,7 @@ gccjit::lvalue content = *ptr;
 Field access is provided separately for both lvalues and rvalues:
 
 @geindex gccjit;;lvalue;;access_field (C++ function)
-@anchor{cp/topics/expressions gccjit lvalue access_field__gccjit field gccjit location}@anchor{18c}
+@anchor{cp/topics/expressions gccjit lvalue access_field__gccjit field gccjit location}@anchor{19a}
 @deffn {C++ Function} gccjit::lvalue gccjit::lvalue::access_field (gccjit::field field, gccjit::location loc)
 
 Given an lvalue of struct or union type, access the given field,
@@ -13326,7 +13686,7 @@ in C.
 @end deffn
 
 @geindex gccjit;;rvalue;;access_field (C++ function)
-@anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{18d}
+@anchor{cp/topics/expressions gccjit rvalue access_field__gccjit field gccjit location}@anchor{19b}
 @deffn {C++ Function} gccjit::rvalue gccjit::rvalue::access_field (gccjit::field field, gccjit::location loc)
 
 Given an rvalue of struct or union type, access the given field
@@ -13342,7 +13702,7 @@ in C.
 @end deffn
 
 @geindex gccjit;;rvalue;;dereference_field (C++ function)
-@anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{18e}
+@anchor{cp/topics/expressions gccjit rvalue dereference_field__gccjit field gccjit location}@anchor{19c}
 @deffn {C++ Function} gccjit::lvalue gccjit::rvalue::dereference_field (gccjit::field field, gccjit::location loc)
 
 Given an rvalue of pointer type @code{T *} where T is of struct or union
@@ -13358,7 +13718,7 @@ in C, itself equivalent to @code{(*EXPR).FIELD}.
 @end deffn
 
 @geindex gccjit;;context;;new_array_access (C++ function)
-@anchor{cp/topics/expressions gccjit context new_array_access__gccjit rvalue gccjit rvalue gccjit location}@anchor{18f}
+@anchor{cp/topics/expressions gccjit context new_array_access__gccjit rvalue gccjit rvalue gccjit location}@anchor{19d}
 @deffn {C++ Function} gccjit::lvalue gccjit::context::new_array_access (gccjit::rvalue ptr, gccjit::rvalue index, gccjit::location loc)
 
 Given an rvalue of pointer type @code{T *}, get at the element @cite{T} at
@@ -13377,7 +13737,7 @@ in C (or, indeed, to @code{PTR + INDEX}).
 Parameter "loc" is optional.
 @end deffn
 
-For array accesses where you don't need to specify a @pxref{12b,,gccjit;;location},
+For array accesses where you don't need to specify a @pxref{139,,gccjit;;location},
 two overloaded operators are available:
 
 @quotation
@@ -13417,7 +13777,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{190}@anchor{cp/topics/functions creating-and-using-functions}@anchor{191}
+@anchor{cp/topics/functions doc}@anchor{19e}@anchor{cp/topics/functions creating-and-using-functions}@anchor{19f}
 @subsection Creating and using functions
 
 
@@ -13430,36 +13790,36 @@ gccjit::lvalue element = array[0];
 @end menu
 
 @node Params<2>,Functions<2>,,Creating and using functions<2>
-@anchor{cp/topics/functions params}@anchor{192}
+@anchor{cp/topics/functions params}@anchor{1a0}
 @subsubsection Params
 
 
 @geindex gccjit;;param (C++ class)
-@anchor{cp/topics/functions gccjit param}@anchor{193}
+@anchor{cp/topics/functions gccjit param}@anchor{1a1}
 @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{fa}
+@anchor{cp/topics/functions gccjit context new_param__gccjit type cCP gccjit location}@anchor{108}
 @deffn {C++ Function} gccjit::param gccjit::context::new_param (gccjit::type type, const char* name, gccjit::location loc)
 
 In preparation for creating a function, create a new parameter of the
 given type and name.
 @end deffn
 
-@pxref{193,,gccjit;;param} is a subclass of @pxref{185,,gccjit;;lvalue} (and thus
-of @pxref{14d,,gccjit;;rvalue} and @pxref{137,,gccjit;;object}).  It is a thin
+@pxref{1a1,,gccjit;;param} is a subclass of @pxref{193,,gccjit;;lvalue} (and thus
+of @pxref{15b,,gccjit;;rvalue} and @pxref{145,,gccjit;;object}).  It is a thin
 wrapper around the C API's @pxref{25,,gcc_jit_param *}.
 
 @node Functions<2>,Blocks<2>,Params<2>,Creating and using functions<2>
-@anchor{cp/topics/functions functions}@anchor{194}
+@anchor{cp/topics/functions functions}@anchor{1a2}
 @subsubsection Functions
 
 
 @geindex gccjit;;function (C++ class)
-@anchor{cp/topics/functions gccjit function}@anchor{195}
+@anchor{cp/topics/functions gccjit function}@anchor{1a3}
 @deffn {C++ Class} gccjit::function
 
 A @cite{gccjit::function} represents a function - either one that we're
@@ -13467,7 +13827,7 @@ creating ourselves, or one that we're referencing.
 @end deffn
 
 @geindex gccjit;;context;;new_function (C++ function)
-@anchor{cp/topics/functions gccjit context new_function__enum gccjit type cCP std vector param R i gccjit location}@anchor{196}
+@anchor{cp/topics/functions gccjit context new_function__enum gccjit type cCP std vector param R i gccjit location}@anchor{1a4}
 @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)
 
 Create a gcc_jit_function with the given name and parameters.
@@ -13478,7 +13838,7 @@ This is a wrapper around the C API's @pxref{11,,gcc_jit_context_new_function()}.
 @end deffn
 
 @geindex gccjit;;context;;get_builtin_function (C++ function)
-@anchor{cp/topics/functions gccjit context get_builtin_function__cCP}@anchor{197}
+@anchor{cp/topics/functions gccjit context get_builtin_function__cCP}@anchor{1a5}
 @deffn {C++ Function} gccjit::function gccjit::context::get_builtin_function (const char* name)
 
 This is a wrapper around the C API's
@@ -13486,21 +13846,21 @@ This is a wrapper around the C API's
 @end deffn
 
 @geindex gccjit;;function;;get_param (C++ function)
-@anchor{cp/topics/functions gccjit function get_param__iC}@anchor{198}
+@anchor{cp/topics/functions gccjit function get_param__iC}@anchor{1a6}
 @deffn {C++ Function} gccjit::param gccjit::function::get_param (int index) const
 
 Get the param of the given index (0-based).
 @end deffn
 
 @geindex gccjit;;function;;dump_to_dot (C++ function)
-@anchor{cp/topics/functions gccjit function dump_to_dot__cCP}@anchor{10d}
+@anchor{cp/topics/functions gccjit function dump_to_dot__cCP}@anchor{11b}
 @deffn {C++ Function} void gccjit::function::dump_to_dot (const char* path)
 
 Emit the function in graphviz format to the given path.
 @end deffn
 
 @geindex gccjit;;function;;new_local (C++ function)
-@anchor{cp/topics/functions gccjit function new_local__gccjit type cCP gccjit location}@anchor{104}
+@anchor{cp/topics/functions gccjit function new_local__gccjit type cCP gccjit location}@anchor{112}
 @deffn {C++ Function} gccjit::lvalue gccjit::function::new_local (gccjit::type type, const char* name, gccjit::location loc)
 
 Create a new local variable within the function, of the given type and
@@ -13508,19 +13868,19 @@ name.
 @end deffn
 
 @node Blocks<2>,Statements<2>,Functions<2>,Creating and using functions<2>
-@anchor{cp/topics/functions blocks}@anchor{199}
+@anchor{cp/topics/functions blocks}@anchor{1a7}
 @subsubsection Blocks
 
 
 @geindex gccjit;;block (C++ class)
-@anchor{cp/topics/functions gccjit block}@anchor{19a}
+@anchor{cp/topics/functions gccjit block}@anchor{1a8}
 @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{19a,,gccjit;;block} is a subclass of @pxref{137,,gccjit;;object}.
+@pxref{1a8,,gccjit;;block} is a subclass of @pxref{145,,gccjit;;object}.
 
 The first basic block that you create within a function will
 be the entrypoint.
@@ -13534,7 +13894,7 @@ one function.
 @end deffn
 
 @geindex gccjit;;function;;new_block (C++ function)
-@anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{19b}
+@anchor{cp/topics/functions gccjit function new_block__cCP}@anchor{1a9}
 @deffn {C++ Function} gccjit::block gccjit::function::new_block (const char* name)
 
 Create a basic block of the given name.  The name may be NULL, but
@@ -13544,12 +13904,12 @@ messages.
 @end deffn
 
 @node Statements<2>,,Blocks<2>,Creating and using functions<2>
-@anchor{cp/topics/functions statements}@anchor{19c}
+@anchor{cp/topics/functions statements}@anchor{1aa}
 @subsubsection Statements
 
 
 @geindex gccjit;;block;;add_eval (C++ function)
-@anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{181}
+@anchor{cp/topics/functions gccjit block add_eval__gccjit rvalue gccjit location}@anchor{18f}
 @deffn {C++ Function} void gccjit::block::add_eval (gccjit::rvalue rvalue, gccjit::location loc)
 
 Add evaluation of an rvalue, discarding the result
@@ -13565,7 +13925,7 @@ This is equivalent to this C code:
 @end deffn
 
 @geindex gccjit;;block;;add_assignment (C++ function)
-@anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{106}
+@anchor{cp/topics/functions gccjit block add_assignment__gccjit lvalue gccjit rvalue gccjit location}@anchor{114}
 @deffn {C++ Function} void gccjit::block::add_assignment (gccjit::lvalue lvalue, gccjit::rvalue rvalue, gccjit::location loc)
 
 Add evaluation of an rvalue, assigning the result to the given
@@ -13581,7 +13941,7 @@ lvalue = rvalue;
 @end deffn
 
 @geindex gccjit;;block;;add_assignment_op (C++ function)
-@anchor{cp/topics/functions gccjit block add_assignment_op__gccjit lvalue enum gccjit rvalue gccjit location}@anchor{10a}
+@anchor{cp/topics/functions gccjit block add_assignment_op__gccjit lvalue enum gccjit rvalue gccjit location}@anchor{118}
 @deffn {C++ Function} void gccjit::block::add_assignment_op (gccjit::lvalue lvalue, enum gcc_jit_binary_op, gccjit::rvalue rvalue, gccjit::location loc)
 
 Add evaluation of an rvalue, using the result to modify an
@@ -13611,7 +13971,7 @@ loop_body.add_assignment_op (
 @end deffn
 
 @geindex gccjit;;block;;add_comment (C++ function)
-@anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{115}
+@anchor{cp/topics/functions gccjit block add_comment__cCP gccjit location}@anchor{123}
 @deffn {C++ Function} void gccjit::block::add_comment (const char* text, gccjit::location loc)
 
 Add a no-op textual comment to the internal representation of the
@@ -13625,7 +13985,7 @@ Parameter "loc" is optional.
 @end deffn
 
 @geindex gccjit;;block;;end_with_conditional (C++ function)
-@anchor{cp/topics/functions gccjit block end_with_conditional__gccjit rvalue gccjit block gccjit block gccjit location}@anchor{109}
+@anchor{cp/topics/functions gccjit block end_with_conditional__gccjit rvalue gccjit block gccjit block gccjit location}@anchor{117}
 @deffn {C++ Function} void gccjit::block::end_with_conditional (gccjit::rvalue boolval, gccjit::block on_true, gccjit::block on_false, gccjit::location loc)
 
 Terminate a block by adding evaluation of an rvalue, branching on the
@@ -13646,7 +14006,7 @@ block, boolval, on_true, and on_false must be non-NULL.
 @end deffn
 
 @geindex gccjit;;block;;end_with_jump (C++ function)
-@anchor{cp/topics/functions gccjit block end_with_jump__gccjit block gccjit location}@anchor{19d}
+@anchor{cp/topics/functions gccjit block end_with_jump__gccjit block gccjit location}@anchor{1ab}
 @deffn {C++ Function} void gccjit::block::end_with_jump (gccjit::block target, gccjit::location loc)
 
 Terminate a block by adding a jump to the given target block.
@@ -13661,7 +14021,7 @@ goto target;
 @end deffn
 
 @geindex gccjit;;block;;end_with_return (C++ function)
-@anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{19e}
+@anchor{cp/topics/functions gccjit block end_with_return__gccjit rvalue gccjit location}@anchor{1ac}
 @deffn {C++ Function} void gccjit::block::end_with_return (gccjit::rvalue rvalue, gccjit::location loc)
 
 Terminate a block.
@@ -13695,7 +14055,7 @@ return;
 @end deffn
 
 @geindex gccjit;;block;;end_with_switch (C++ function)
-@anchor{cp/topics/functions gccjit block end_with_switch__gccjit rvalue gccjit block std vector gccjit case_ gccjit location}@anchor{19f}
+@anchor{cp/topics/functions gccjit block end_with_switch__gccjit rvalue gccjit block std vector gccjit case_ gccjit location}@anchor{1ad}
 @deffn {C++ Function} void gccjit::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
@@ -13738,10 +14098,10 @@ The API entrypoints relating to switch statements and cases:
 @itemize *
 
 @item 
-@pxref{19f,,gccjit;;block;;end_with_switch()}
+@pxref{1ad,,gccjit;;block;;end_with_switch()}
 
 @item 
-@pxref{1a0,,gccjit;;context;;new_case()}
+@pxref{1ae,,gccjit;;context;;new_case()}
 @end itemize
 @end quotation
 
@@ -13755,21 +14115,21 @@ using
 @noindent
 
 @geindex gccjit;;block;;end_with_switch;;gccjit;;case_ (C++ class)
-@anchor{cp/topics/functions gccjit block end_with_switch gccjit case_}@anchor{1a1}
+@anchor{cp/topics/functions gccjit block end_with_switch gccjit case_}@anchor{1af}
 @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{123,,gccjit;;context} using
-@pxref{1a0,,gccjit;;context;;new_case()}.  It is a subclass of
-@pxref{137,,gccjit;;object}.
+is created within a particular @pxref{131,,gccjit;;context} using
+@pxref{1ae,,gccjit;;context;;new_case()}.  It is a subclass of
+@pxref{145,,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{1a0}
+@anchor{cp/topics/functions gccjit block end_with_switch gccjit context new_case__gccjit rvalue gccjit rvalue gccjit block}@anchor{1ae}
 @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.
@@ -13880,12 +14240,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{1a2}@anchor{cp/topics/locations doc}@anchor{1a3}
+@anchor{cp/topics/locations source-locations}@anchor{1b0}@anchor{cp/topics/locations doc}@anchor{1b1}
 @subsection Source Locations
 
 
 @geindex gccjit;;location (C++ class)
-@anchor{cp/topics/locations gccjit location}@anchor{12b}
+@anchor{cp/topics/locations gccjit location}@anchor{139}
 @deffn {C++ Class} gccjit::location
 
 A @cite{gccjit::location} encapsulates a source code location, so that
@@ -13896,10 +14256,10 @@ single-step through your language.
 @cite{gccjit::location} instances are optional: you can always omit them
 from any C++ API entrypoint accepting one.
 
-You can construct them using @pxref{119,,gccjit;;context;;new_location()}.
+You can construct them using @pxref{127,,gccjit;;context;;new_location()}.
 
 You need to enable @pxref{42,,GCC_JIT_BOOL_OPTION_DEBUGINFO} on the
-@pxref{123,,gccjit;;context} for these locations to actually be usable by
+@pxref{131,,gccjit;;context} for these locations to actually be usable by
 the debugger:
 
 @example
@@ -13910,7 +14270,7 @@ ctxt.set_bool_option (GCC_JIT_BOOL_OPTION_DEBUGINFO, 1);
 @end deffn
 
 @geindex gccjit;;context;;new_location (C++ function)
-@anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{119}
+@anchor{cp/topics/locations gccjit context new_location__cCP i i}@anchor{127}
 @deffn {C++ Function} gccjit::location gccjit::context::new_location (const char* filename, int line, int column)
 
 Create a @cite{gccjit::location} instance representing the given source
@@ -13923,13 +14283,13 @@ location.
 @end menu
 
 @node Faking it<2>,,,Source Locations<2>
-@anchor{cp/topics/locations faking-it}@anchor{1a4}
+@anchor{cp/topics/locations faking-it}@anchor{1b2}
 @subsubsection Faking it
 
 
 If you don't have source code for your internal representation, but need
 to debug, you can generate a C-like representation of the functions in
-your context using @pxref{12a,,gccjit;;context;;dump_to_file()}:
+your context using @pxref{138,,gccjit;;context;;dump_to_file()}:
 
 @example
 ctxt.dump_to_file ("/tmp/something.c",
@@ -13961,13 +14321,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{1a5}@anchor{cp/topics/compilation doc}@anchor{1a6}
+@anchor{cp/topics/compilation compiling-a-context}@anchor{1b3}@anchor{cp/topics/compilation doc}@anchor{1b4}
 @subsection Compiling a context
 
 
-Once populated, a @pxref{123,,gccjit;;context} can be compiled to
-machine code, either in-memory via @pxref{fc,,gccjit;;context;;compile()} or
-to disk via @pxref{1a7,,gccjit;;context;;compile_to_file()}.
+Once populated, a @pxref{131,,gccjit;;context} can be compiled to
+machine code, either in-memory via @pxref{10a,,gccjit;;context;;compile()} or
+to disk via @pxref{1b5,,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
@@ -13980,12 +14340,12 @@ prevent any future compilation of that context.
 @end menu
 
 @node In-memory compilation<2>,Ahead-of-time compilation<2>,,Compiling a context<2>
-@anchor{cp/topics/compilation in-memory-compilation}@anchor{1a8}
+@anchor{cp/topics/compilation in-memory-compilation}@anchor{1b6}
 @subsubsection In-memory compilation
 
 
 @geindex gccjit;;context;;compile (C++ function)
-@anchor{cp/topics/compilation gccjit context compile}@anchor{fc}
+@anchor{cp/topics/compilation gccjit context compile}@anchor{10a}
 @deffn {C++ Function} gcc_jit_result* gccjit::context::compile ()
 
 This calls into GCC and builds the code, returning a
@@ -13996,19 +14356,19 @@ This is a thin wrapper around the
 @end deffn
 
 @node Ahead-of-time compilation<2>,,In-memory compilation<2>,Compiling a context<2>
-@anchor{cp/topics/compilation ahead-of-time-compilation}@anchor{1a9}
+@anchor{cp/topics/compilation ahead-of-time-compilation}@anchor{1b7}
 @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{1a7,,gccjit;;context;;compile_to_file()} method.
+compilers, via the @pxref{1b5,,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{1a7}
+@anchor{cp/topics/compilation gccjit context compile_to_file__enum cCP}@anchor{1b5}
 @deffn {C++ Function} void gccjit::context::compile_to_file (enum gcc_jit_output_kind, const char* output_path)
 
-Compile the @pxref{123,,gccjit;;context} to a file of the given
+Compile the @pxref{131,,gccjit;;context} to a file of the given
 kind.
 
 This is a thin wrapper around the
@@ -14033,7 +14393,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{1aa}@anchor{internals/index doc}@anchor{1ab}
+@anchor{internals/index internals}@anchor{1b8}@anchor{internals/index doc}@anchor{1b9}
 @chapter Internals
 
 
@@ -14049,7 +14409,7 @@ This is a thin wrapper around the
 @end menu
 
 @node Working on the JIT library,Running the test suite,,Internals
-@anchor{internals/index working-on-the-jit-library}@anchor{1ac}
+@anchor{internals/index working-on-the-jit-library}@anchor{1ba}
 @section Working on the JIT library
 
 
@@ -14086,7 +14446,7 @@ gcc/libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV),
 Here's what those configuration options mean:
 
 @geindex command line option; --enable-host-shared
-@anchor{internals/index cmdoption--enable-host-shared}@anchor{1ad}
+@anchor{internals/index cmdoption--enable-host-shared}@anchor{1bb}
 @deffn {Option} --enable-host-shared
 
 Configuring with this option means that the compiler is built as
@@ -14095,7 +14455,7 @@ but it necessary for a shared library.
 @end deffn
 
 @geindex command line option; --enable-languages=jit@comma{}c++
-@anchor{internals/index cmdoption--enable-languages}@anchor{1ae}
+@anchor{internals/index cmdoption--enable-languages}@anchor{1bc}
 @deffn {Option} --enable-languages=jit,c++
 
 This specifies which frontends to build.  The JIT library looks like
@@ -14114,7 +14474,7 @@ c++: error trying to exec 'cc1plus': execvp: No such file or directory
 @end deffn
 
 @geindex command line option; --disable-bootstrap
-@anchor{internals/index cmdoption--disable-bootstrap}@anchor{1af}
+@anchor{internals/index cmdoption--disable-bootstrap}@anchor{1bd}
 @deffn {Option} --disable-bootstrap
 
 For hacking on the "jit" subdirectory, performing a full
@@ -14124,7 +14484,7 @@ the compiler can still bootstrap itself.
 @end deffn
 
 @geindex command line option; --enable-checking=release
-@anchor{internals/index cmdoption--enable-checking}@anchor{1b0}
+@anchor{internals/index cmdoption--enable-checking}@anchor{1be}
 @deffn {Option} --enable-checking=release
 
 The compile can perform extensive self-checking as it runs, useful when
@@ -14135,7 +14495,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{1b1}
+@anchor{internals/index running-the-test-suite}@anchor{1bf}
 @section Running the test suite
 
 
@@ -14198,7 +14558,7 @@ and once a test has been compiled, you can debug it directly:
 @end menu
 
 @node Running under valgrind,,,Running the test suite
-@anchor{internals/index running-under-valgrind}@anchor{1b2}
+@anchor{internals/index running-under-valgrind}@anchor{1c0}
 @subsection Running under valgrind
 
 
@@ -14246,7 +14606,7 @@ When running under valgrind, it's best to have configured gcc with
 various known false positives.
 
 @node Environment variables,Packaging notes,Running the test suite,Internals
-@anchor{internals/index environment-variables}@anchor{1b3}
+@anchor{internals/index environment-variables}@anchor{1c1}
 @section Environment variables
 
 
@@ -14254,7 +14614,7 @@ When running client code against a locally-built libgccjit, three
 environment variables need to be set up:
 
 @geindex environment variable; LD_LIBRARY_PATH
-@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{1b4}
+@anchor{internals/index envvar-LD_LIBRARY_PATH}@anchor{1c2}
 @deffn {Environment Variable} LD_LIBRARY_PATH
 
 @quotation
@@ -14276,7 +14636,7 @@ libgccjit.so.0.0.1: ELF 64-bit LSB shared object, x86-64, version 1 (GNU/Linux),
 @end deffn
 
 @geindex environment variable; PATH
-@anchor{internals/index envvar-PATH}@anchor{1b5}
+@anchor{internals/index envvar-PATH}@anchor{1c3}
 @deffn {Environment Variable} PATH
 
 The library uses a driver executable for converting from .s assembler
@@ -14295,7 +14655,7 @@ of development.
 @end deffn
 
 @geindex environment variable; LIBRARY_PATH
-@anchor{internals/index envvar-LIBRARY_PATH}@anchor{1b6}
+@anchor{internals/index envvar-LIBRARY_PATH}@anchor{1c4}
 @deffn {Environment Variable} LIBRARY_PATH
 
 The driver executable invokes the linker, and the latter needs to locate
@@ -14331,11 +14691,11 @@ hello world
 @noindent
 
 @node Packaging notes,Overview of code structure,Environment variables,Internals
-@anchor{internals/index packaging-notes}@anchor{1b7}
+@anchor{internals/index packaging-notes}@anchor{1c5}
 @section Packaging notes
 
 
-The configure-time option @pxref{1ad,,--enable-host-shared} is needed when
+The configure-time option @pxref{1bb,,--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:
@@ -14346,10 +14706,10 @@ with libgccjit, please configure and build twice:
 @itemize *
 
 @item 
-once without @pxref{1ad,,--enable-host-shared} for most languages, and
+once without @pxref{1bb,,--enable-host-shared} for most languages, and
 
 @item 
-once with @pxref{1ad,,--enable-host-shared} for the jit
+once with @pxref{1bb,,--enable-host-shared} for the jit
 @end itemize
 @end quotation
 
@@ -14393,7 +14753,7 @@ popd
 @noindent
 
 @node Overview of code structure,Design notes,Packaging notes,Internals
-@anchor{internals/index overview-of-code-structure}@anchor{1b8}
+@anchor{internals/index overview-of-code-structure}@anchor{1c6}
 @section Overview of code structure
 
 
@@ -14860,7 +15220,7 @@ JIT: gcc::jit::logger::~logger()
 @noindent
 
 @node Design notes,Submitting patches,Overview of code structure,Internals
-@anchor{internals/index design-notes}@anchor{1b9}
+@anchor{internals/index design-notes}@anchor{1c7}
 @section Design notes
 
 
@@ -14873,7 +15233,7 @@ close as possible to the error; failing that, a good place is within
 @code{recording::context::validate ()} in jit-recording.c.
 
 @node Submitting patches,,Design notes,Internals
-@anchor{internals/index submitting-patches}@anchor{1ba}
+@anchor{internals/index submitting-patches}@anchor{1c8}
 @section Submitting patches
 
 
@@ -15007,7 +15367,7 @@ large and inconsequential (e.g. anchor renumbering), rather like generated
 committing to svn.
 
 @node Indices and tables,Index,Internals,Top
-@anchor{index indices-and-tables}@anchor{1bb}
+@anchor{index indices-and-tables}@anchor{1c9}
 @unnumbered Indices and tables
 
 
diff --git a/gcc/jit/docs/topics/compatibility.rst b/gcc/jit/docs/topics/compatibility.rst
index 37e2866..0a4b453 100644
--- a/gcc/jit/docs/topics/compatibility.rst
+++ b/gcc/jit/docs/topics/compatibility.rst
@@ -107,3 +107,24 @@ entrypoints:
   * :func:`gcc_jit_case_as_object`
 
   * :func:`gcc_jit_context_new_case`
+
+.. _LIBGCCJIT_ABI_4:
+
+``LIBGCCJIT_ABI_4``
+-------------------
+``LIBGCCJIT_ABI_4`` covers the addition of timers via API
+entrypoints:
+
+  * :func:`gcc_jit_context_get_timer`
+
+  * :func:`gcc_jit_context_set_timer`
+
+  * :func:`gcc_jit_timer_new`
+
+  * :func:`gcc_jit_timer_release`
+
+  * :func:`gcc_jit_timer_push`
+
+  * :func:`gcc_jit_timer_pop`
+
+  * :func:`gcc_jit_timer_print`
diff --git a/gcc/jit/docs/topics/contexts.rst b/gcc/jit/docs/topics/contexts.rst
index 78bcb71..1aa319a 100644
--- a/gcc/jit/docs/topics/contexts.rst
+++ b/gcc/jit/docs/topics/contexts.rst
@@ -430,8 +430,7 @@ Boolean options
   .. macro:: GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
 
      If true, :func:`gcc_jit_context_compile` will print information to stderr
-     on the actions it is performing, followed by a profile showing
-     the time taken and memory usage of each phase.
+     on the actions it is performing.
 
   .. macro:: GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING
 
diff --git a/gcc/jit/docs/topics/index.rst b/gcc/jit/docs/topics/index.rst
index 76b3d0b..d32f63b1 100644
--- a/gcc/jit/docs/topics/index.rst
+++ b/gcc/jit/docs/topics/index.rst
@@ -29,3 +29,4 @@ Topic Reference
    locations.rst
    compilation.rst
    compatibility.rst
+   performance.rst
diff --git a/gcc/jit/docs/topics/performance.rst b/gcc/jit/docs/topics/performance.rst
new file mode 100644
index 0000000..4dfc139
--- /dev/null
+++ b/gcc/jit/docs/topics/performance.rst
@@ -0,0 +1,240 @@
+.. Copyright (C) 2015 Free Software Foundation, Inc.
+   Originally contributed by David Malcolm <dmalcolm@redhat.com>
+
+   This is free software: you can redistribute it and/or modify it
+   under the terms of the GNU General Public License as published by
+   the Free Software Foundation, either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful, but
+   WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+   General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see
+   <http://www.gnu.org/licenses/>.
+
+.. default-domain:: c
+
+Performance
+===========
+
+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 :c:type:`gcc_jit_timer` instance, which will
+measure time spent since its creation.  The timer maintains a stack
+of "timer items": as control flow moves through your code, you can push
+and pop named items relating to your code onto the stack, and the timer
+will account the time spent accordingly.
+
+You can also asssociate a timer with a :c:type:`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":
+
+.. code-block:: c
+
+  /* Create a timer.  */
+  gcc_jit_timer *timer = gcc_jit_timer_new ();
+  if (!timer)
+    {
+       error ("gcc_jit_timer_new failed");
+       return -1;
+    }
+
+  /* Let's repeatedly compile and run some code, accumulating it
+     all into the timer.  */
+  for (int i = 0; i < num_iterations; i++)
+    {
+      /* Create a context and associate it with the timer.  */
+      gcc_jit_context *ctxt = gcc_jit_context_acquire ();
+      if (!ctxt)
+        {
+          error ("gcc_jit_context_acquire failed");
+          return -1;
+        }
+      gcc_jit_context_set_timer (ctxt, timer);
+
+      /* Populate the context, timing it as client item "create_code".  */
+      gcc_jit_timer_push (timer, "create_code");
+      create_code (ctxt);
+      gcc_jit_timer_pop (timer, "create_code");
+
+      /* Compile the context, timing it as client item "compile".  */
+      gcc_jit_timer_push (timer, "compile");
+      result = gcc_jit_context_compile (ctxt);
+      gcc_jit_timer_pop (timer, "compile");
+
+      /* Run the generated code, timing it as client item "running code".  */
+      gcc_jit_timer_push (timer, "running code");
+      run_the_code (ctxt, result);
+      gcc_jit_timer_pop (timer, "running code");
+
+      /* Clean up.  */
+      gcc_jit_context_release (ctxt);
+      gcc_jit_result_release (result);
+  }
+
+  /* Print the accumulated timings.  */
+  gcc_jit_timer_print (timer, stderr);
+  gcc_jit_timer_release (timer);
+
+giving output like this, showing the internal GCC items at the top, then
+client items, then the total::
+
+  Execution times (seconds)
+  GCC items:
+   phase setup             :   0.29 (14%) usr   0.00 ( 0%) sys   0.32 ( 5%) wall   10661 kB (50%) ggc
+   phase parsing           :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall     653 kB ( 3%) ggc
+   phase finalize          :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+   dump files              :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.01 ( 0%) wall       0 kB ( 0%) ggc
+   callgraph construction  :   0.02 ( 1%) usr   0.01 ( 6%) sys   0.01 ( 0%) wall     242 kB ( 1%) ggc
+   callgraph optimization  :   0.03 ( 2%) usr   0.00 ( 0%) sys   0.02 ( 0%) wall     142 kB ( 1%) ggc
+   trivially dead code     :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+   df scan insns           :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       9 kB ( 0%) ggc
+   df live regs            :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.01 ( 0%) wall       0 kB ( 0%) ggc
+   inline parameters       :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.01 ( 0%) wall      82 kB ( 0%) ggc
+   tree CFG cleanup        :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+   tree PHI insertion      :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.02 ( 0%) wall      64 kB ( 0%) ggc
+   tree SSA other          :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.01 ( 0%) wall      18 kB ( 0%) ggc
+   expand                  :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall     398 kB ( 2%) ggc
+   jump                    :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+   loop init               :   0.01 ( 0%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall      67 kB ( 0%) ggc
+   integrated RA           :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall    2468 kB (12%) ggc
+   thread pro- & epilogue  :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall     162 kB ( 1%) ggc
+   final                   :   0.01 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall     216 kB ( 1%) ggc
+   rest of compilation     :   1.37 (69%) usr   0.00 ( 0%) sys   1.13 (18%) wall    1391 kB ( 6%) ggc
+   assemble JIT code       :   0.01 ( 1%) usr   0.00 ( 0%) sys   4.04 (66%) wall       0 kB ( 0%) ggc
+   load JIT result         :   0.02 ( 1%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+   JIT client code         :   0.00 ( 0%) usr   0.01 ( 6%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+  Client items:
+   create_code             :   0.00 ( 0%) usr   0.01 ( 6%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+   compile                 :   0.36 (18%) usr   0.15 (83%) sys   0.86 (14%) wall   14939 kB (70%) ggc
+   running code            :   0.00 ( 0%) usr   0.00 ( 0%) sys   0.00 ( 0%) wall       0 kB ( 0%) ggc
+   TOTAL                   :   2.00             0.18             6.12              21444 kB
+
+The exact format is intended to be human-readable, and is subject to change.
+
+.. macro:: LIBGCCJIT_HAVE_TIMING_API
+
+   The timer API was added to libgccjit in GCC 6.
+   This macro is only defined in versions of libgccjit.h which have the
+   timer API, and so can be used to guard code that may need to compile
+   against earlier releases::
+
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+     gcc_jit_timer *t = gcc_jit_timer_new ();
+     gcc_jit_context_set_timer (ctxt, t);
+     #endif
+
+.. type:: gcc_jit_timer
+
+.. function:: gcc_jit_timer * gcc_jit_timer_new(void)
+
+   Create a :c:type:`gcc_jit_timer` instance, and start timing::
+
+     gcc_jit_timer *t = gcc_jit_timer_new ();
+
+   This API entrypoint was added in :ref:`LIBGCCJIT_ABI_4`; you can test
+   for its presence using
+
+   .. code-block:: c
+
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+
+.. function:: void gcc_jit_timer_release(gcc_jit_timer *timer)
+
+   Release a :c:type:`gcc_jit_timer` instance::
+
+     gcc_jit_timer_release (t);
+
+   This should be called exactly once on a timer.
+
+   This API entrypoint was added in :ref:`LIBGCCJIT_ABI_4`; you can test
+   for its presence using
+
+   .. code-block:: c
+
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+
+.. function:: void gcc_jit_context_set_timer(gcc_jit_context *ctxt, \
+                                             gcc_jit_timer *timer)
+
+   Associate a :c:type:`gcc_jit_timer` instance with a context::
+
+      gcc_jit_context_set_timer (ctxt, t);
+
+   A timer instance can be shared between multiple
+   :c:type:`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 :ref:`LIBGCCJIT_ABI_4`; you can test
+   for its presence using
+
+   .. code-block:: c
+
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+
+.. function:: gcc_jit_timer *gcc_jit_context_get_timer(gcc_jit_context *ctxt)
+
+   Get the timer associated with a context (if any).
+
+   This API entrypoint was added in :ref:`LIBGCCJIT_ABI_4`; you can test
+   for its presence using
+
+   .. code-block:: c
+
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+
+.. function:: void gcc_jit_timer_push(gcc_jit_timer *timer, \
+                                      const char *item_name)
+
+   Push the given item onto the timer's stack::
+
+      gcc_jit_timer_push (t, "running code");
+      run_the_code (ctxt, result);
+      gcc_jit_timer_pop (t, "running code");
+
+   This API entrypoint was added in :ref:`LIBGCCJIT_ABI_4`; you can test
+   for its presence using
+
+   .. code-block:: c
+
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+
+.. function:: void gcc_jit_timer_pop(gcc_jit_timer *timer, \
+                                     const char *item_name)
+
+   Pop the top item from the timer's stack.
+
+   If "item_name" is provided, it must match that of the top item.
+   Alternatively, ``NULL`` can be passed in, to suppress checking.
+
+   This API entrypoint was added in :ref:`LIBGCCJIT_ABI_4`; you can test
+   for its presence using
+
+   .. code-block:: c
+
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+
+.. function:: void gcc_jit_timer_print(gcc_jit_timer *timer, \
+                                       FILE *f_out)
+
+   Print timing information to the given stream about activity since
+   the timer was started.
+
+   This API entrypoint was added in :ref:`LIBGCCJIT_ABI_4`; you can test
+   for its presence using
+
+   .. code-block:: c
+
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
diff --git a/gcc/jit/jit-playback.c b/gcc/jit/jit-playback.c
index c469863..925fa86 100644
--- a/gcc/jit/jit-playback.c
+++ b/gcc/jit/jit-playback.c
@@ -1793,7 +1793,7 @@ compile ()
     }
 
   /* This runs the compiler.  */
-  toplev toplev (false, /* use_TV_TOTAL */
+  toplev toplev (get_timer (), /* external_timer */
 		 false); /* init_signals */
   enter_scope ("toplev::main");
   if (get_logger ())
@@ -2085,6 +2085,8 @@ static pthread_mutex_t jit_mutex = PTHREAD_MUTEX_INITIALIZER;
 void
 playback::context::acquire_mutex ()
 {
+  auto_timevar tv (get_timer (), TV_JIT_ACQUIRING_MUTEX);
+
   /* Acquire the big GCC mutex. */
   JIT_LOG_SCOPE (get_logger ());
   pthread_mutex_lock (&jit_mutex);
@@ -2252,6 +2254,9 @@ make_fake_args (vec <char *> *argvec,
       }
   }
 
+  if (get_timer ())
+    ADD_ARG ("-ftime-report");
+
   /* Add any user-provided extra options, starting with any from
      parent contexts.  */
   m_recording_ctxt->append_command_line_options (argvec);
@@ -2380,7 +2385,7 @@ invoke_driver (const char *ctxt_progname,
   JIT_LOG_SCOPE (get_logger ());
   /* Currently this lumps together both assembling and linking into
      TV_ASSEMBLE.  */
-  auto_timevar assemble_timevar (tv_id);
+  auto_timevar assemble_timevar (get_timer (), tv_id);
   const char *errmsg;
   auto_argvec argvec;
 #define ADD_ARG(arg) argvec.safe_push (xstrdup (arg))
@@ -2492,7 +2497,7 @@ playback::context::
 dlopen_built_dso ()
 {
   JIT_LOG_SCOPE (get_logger ());
-  auto_timevar load_timevar (TV_LOAD);
+  auto_timevar load_timevar (get_timer (), TV_LOAD);
   void *handle = NULL;
   const char *error = NULL;
   result *result_obj = NULL;
diff --git a/gcc/jit/jit-playback.h b/gcc/jit/jit-playback.h
index 1d7de17..52e402f 100644
--- a/gcc/jit/jit-playback.h
+++ b/gcc/jit/jit-playback.h
@@ -215,6 +215,8 @@ public:
     return m_recording_ctxt->errors_occurred ();
   }
 
+  timer *get_timer () const { return m_recording_ctxt->get_timer (); }
+
 private:
   void dump_generated_code ();
 
diff --git a/gcc/jit/jit-recording.c b/gcc/jit/jit-recording.c
index d888b0e..811d7c0 100644
--- a/gcc/jit/jit-recording.c
+++ b/gcc/jit/jit-recording.c
@@ -25,6 +25,7 @@ along with GCC; see the file COPYING3.  If not see
 #include "pretty-print.h"
 #include "hash-map.h"
 #include "toplev.h"
+#include "timevar.h"
 
 #include <pthread.h>
 
@@ -461,6 +462,7 @@ recording::context::context (context *parent_ctxt)
   : log_user (NULL),
     m_parent_ctxt (parent_ctxt),
     m_toplevel_ctxt (m_parent_ctxt ? m_parent_ctxt->m_toplevel_ctxt : this),
+    m_timer (NULL),
     m_error_count (0),
     m_first_error_str (NULL),
     m_owns_first_error_str (false),
diff --git a/gcc/jit/jit-recording.h b/gcc/jit/jit-recording.h
index 884304b..3d88b89 100644
--- a/gcc/jit/jit-recording.h
+++ b/gcc/jit/jit-recording.h
@@ -24,6 +24,8 @@ along with GCC; see the file COPYING3.  If not see
 #include "jit-common.h"
 #include "jit-logging.h"
 
+class timer;
+
 namespace gcc {
 
 namespace jit {
@@ -276,6 +278,9 @@ public:
   void
   get_all_requested_dumps (vec <recording::requested_dump> *out);
 
+  void set_timer (timer *t) { m_timer = t; }
+  timer *get_timer () const { return m_timer; }
+
 private:
   void log_all_options () const;
   void log_str_option (enum gcc_jit_str_option opt) const;
@@ -292,6 +297,8 @@ private:
      contexts.  This has itself as its own m_toplevel_ctxt.  */
   context *m_toplevel_ctxt;
 
+  timer *m_timer;
+
   int m_error_count;
 
   char *m_first_error_str;
diff --git a/gcc/jit/libgccjit++.h b/gcc/jit/libgccjit++.h
index 01579bd7..d7e491b 100644
--- a/gcc/jit/libgccjit++.h
+++ b/gcc/jit/libgccjit++.h
@@ -46,6 +46,8 @@ namespace gccjit
      class lvalue;
        class param;
     class case_;
+  class timer;
+  class auto_time;
 
   /* Errors within the API become C++ exceptions of this class.  */
   class error
@@ -125,6 +127,9 @@ namespace gccjit
 
     void add_command_line_option (const char *optname);
 
+    void set_timer (gccjit::timer t);
+    gccjit::timer get_timer () const;
+
     location
     new_location (const std::string &filename,
 		  int line,
@@ -523,6 +528,36 @@ namespace gccjit
 
   /* Dereferencing. */
   lvalue operator* (rvalue ptr);
+
+  class timer
+  {
+  public:
+    timer ();
+    timer (gcc_jit_timer *inner_timer);
+
+    void push (const char *item_name);
+    void pop (const char *item_name);
+    void print (FILE *f_out) const;
+
+    void release ();
+
+    gcc_jit_timer *get_inner_timer () const;
+
+  private:
+    gcc_jit_timer *m_inner_timer;
+  };
+
+  class auto_time
+  {
+  public:
+    auto_time (timer t, const char *item_name);
+    auto_time (context ctxt, const char *item_name);
+    ~auto_time ();
+
+  private:
+    timer m_timer;
+    const char *m_item_name;
+  };
 }
 
 /****************************************************************************
@@ -636,6 +671,19 @@ context::add_command_line_option (const char *optname)
   gcc_jit_context_add_command_line_option (m_inner_ctxt, optname);
 }
 
+inline void
+context::set_timer (gccjit::timer t)
+{
+  gcc_jit_context_set_timer (m_inner_ctxt, t.get_inner_timer ());
+}
+
+inline gccjit::timer
+context::get_timer () const
+{
+  return gccjit::timer (gcc_jit_context_get_timer (m_inner_ctxt));
+}
+
+
 inline location
 context::new_location (const std::string &filename,
 		       int line,
@@ -1713,6 +1761,75 @@ inline lvalue operator* (rvalue ptr)
   return ptr.dereference ();
 }
 
+// class timer
+inline
+timer::timer ()
+{
+  m_inner_timer = gcc_jit_timer_new ();
+}
+
+inline
+timer::timer (gcc_jit_timer *inner_timer)
+{
+  m_inner_timer = inner_timer;
+}
+
+inline void
+timer::push (const char *item_name)
+{
+  gcc_jit_timer_push (m_inner_timer, item_name);
+
+}
+
+inline void
+timer::pop (const char *item_name)
+{
+  gcc_jit_timer_pop (m_inner_timer, item_name);
+}
+
+inline void
+timer::print (FILE *f_out) const
+{
+  gcc_jit_timer_print (m_inner_timer, f_out);
+}
+
+inline gcc_jit_timer *
+timer::get_inner_timer () const
+{
+  return m_inner_timer;
+}
+
+inline void
+timer::release ()
+{
+  gcc_jit_timer_release (m_inner_timer);
+  m_inner_timer = NULL;
+}
+
+// class auto_time
+
+inline
+auto_time::auto_time (timer t, const char *item_name)
+  : m_timer (t),
+    m_item_name (item_name)
+{
+  t.push (item_name);
+}
+
+inline
+auto_time::auto_time (context ctxt, const char *item_name)
+  : m_timer (ctxt.get_timer ()),
+    m_item_name (item_name)
+{
+  m_timer.push (item_name);
+}
+
+inline
+auto_time::~auto_time ()
+{
+  m_timer.pop (m_item_name);
+}
+
 } // namespace gccjit
 
 #endif /* #ifndef LIBGCCJIT_PLUS_PLUS_H */
diff --git a/gcc/jit/libgccjit.c b/gcc/jit/libgccjit.c
index eee513f..eb9200c 100644
--- a/gcc/jit/libgccjit.c
+++ b/gcc/jit/libgccjit.c
@@ -24,6 +24,7 @@ along with GCC; see the file COPYING3.  If not see
 #include "opts.h"
 #include "safe-ctype.h"
 #include "typed-splay-tree.h"
+#include "timevar.h"
 
 #include "libgccjit.h"
 #include "jit-common.h"
@@ -89,6 +90,10 @@ struct gcc_jit_case : public gcc::jit::recording::case_
 {
 };
 
+struct gcc_jit_timer : public timer
+{
+};
+
 /**********************************************************************
  Error-handling.
 
@@ -2828,3 +2833,107 @@ gcc_jit_result_release (gcc_jit_result *result)
   result->log ("deleting result: %p", (void *)result);
   delete result;
 }
+
+/**********************************************************************
+ Timing support.
+ **********************************************************************/
+
+/* Create a gcc_jit_timer instance, and start timing.  */
+
+gcc_jit_timer *
+gcc_jit_timer_new (void)
+{
+  gcc_jit_timer *timer = new gcc_jit_timer ();
+  timer->start (TV_TOTAL);
+  timer->push (TV_JIT_CLIENT_CODE);
+  return timer;
+}
+
+/* Release a gcc_jit_timer instance.  */
+
+void
+gcc_jit_timer_release (gcc_jit_timer *timer)
+{
+  RETURN_IF_FAIL (timer, NULL, NULL, "NULL timer");
+
+  delete timer;
+}
+
+/* Associate a gcc_jit_timer instance with a context.  */
+
+void
+gcc_jit_context_set_timer (gcc_jit_context *ctxt,
+			   gcc_jit_timer *timer)
+{
+  RETURN_IF_FAIL (ctxt, NULL, NULL, "NULL ctxt");
+  RETURN_IF_FAIL (timer, ctxt, NULL, "NULL timer");
+
+  ctxt->set_timer (timer);
+}
+
+/* Get the timer associated with a context (if any).  */
+
+gcc_jit_timer *
+gcc_jit_context_get_timer (gcc_jit_context *ctxt)
+{
+  RETURN_NULL_IF_FAIL (ctxt, NULL, NULL, "NULL ctxt");
+
+  return (gcc_jit_timer *)ctxt->get_timer ();
+}
+
+/* Push the given item onto the timing stack.  */
+
+void
+gcc_jit_timer_push (gcc_jit_timer *timer,
+		    const char *item_name)
+{
+  RETURN_IF_FAIL (timer, NULL, NULL, "NULL timer");
+  RETURN_IF_FAIL (item_name, NULL, NULL, "NULL item_name");
+  timer->push_client_item (item_name);
+}
+
+/* Pop the top item from the timing stack.  */
+
+void
+gcc_jit_timer_pop (gcc_jit_timer *timer,
+		   const char *item_name)
+{
+  RETURN_IF_FAIL (timer, NULL, NULL, "NULL timer");
+
+  if (item_name)
+    {
+      const char *top_item_name = timer->get_topmost_item_name ();
+
+      RETURN_IF_FAIL_PRINTF1
+	(top_item_name, NULL, NULL,
+	 "pop of empty timing stack (attempting to pop: \"%s\")",
+	 item_name);
+
+      RETURN_IF_FAIL_PRINTF2
+	(0 == strcmp (item_name, top_item_name), NULL, NULL,
+	 "mismatching item_name:"
+	 " top of timing stack: \"%s\","
+	 " attempting to pop: \"%s\"",
+	 top_item_name,
+	 item_name);
+    }
+
+  timer->pop_client_item ();
+}
+
+/* Print timing information to the given stream about activity since
+   the timer was started.  */
+
+void
+gcc_jit_timer_print (gcc_jit_timer *timer,
+		     FILE *f_out)
+{
+  RETURN_IF_FAIL (timer, NULL, NULL, "NULL timer");
+  RETURN_IF_FAIL (f_out, NULL, NULL, "NULL f_out");
+
+  timer->pop (TV_JIT_CLIENT_CODE);
+  timer->stop (TV_TOTAL);
+  timer->print (f_out);
+  timer->start (TV_TOTAL);
+  timer->push (TV_JIT_CLIENT_CODE);
+}
diff --git a/gcc/jit/libgccjit.h b/gcc/jit/libgccjit.h
index 32f2a5d..88e4ff3 100644
--- a/gcc/jit/libgccjit.h
+++ b/gcc/jit/libgccjit.h
@@ -1266,6 +1266,90 @@ gcc_jit_context_enable_dump (gcc_jit_context *ctxt,
 			     const char *dumpname,
 			     char **out_ptr);
 
+/**********************************************************************
+ Timing support.
+ **********************************************************************/
+
+/* The timing API was added in LIBGCCJIT_ABI_4; you can test for its
+   presence using
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+*/
+#define LIBGCCJIT_HAVE_TIMING_API
+
+typedef struct gcc_jit_timer gcc_jit_timer;
+
+/* Create a gcc_jit_timer instance, and start timing.
+
+   This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
+   presence using
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+*/
+extern gcc_jit_timer *
+gcc_jit_timer_new (void);
+
+/* Release a gcc_jit_timer instance.
+
+   This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
+   presence using
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+*/
+extern void
+gcc_jit_timer_release (gcc_jit_timer *timer);
+
+/* Associate a gcc_jit_timer instance with a context.
+
+   This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
+   presence using
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+*/
+extern void
+gcc_jit_context_set_timer (gcc_jit_context *ctxt,
+			   gcc_jit_timer *timer);
+
+/* Get the timer associated with a context (if any).
+
+   This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
+   presence using
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+*/
+
+extern gcc_jit_timer *
+gcc_jit_context_get_timer (gcc_jit_context *ctxt);
+
+/* Push the given item onto the timing stack.
+
+   This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
+   presence using
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+*/
+
+extern void
+gcc_jit_timer_push (gcc_jit_timer *timer,
+		    const char *item_name);
+
+/* Pop the top item from the timing stack.
+
+   This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
+   presence using
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+*/
+
+extern void
+gcc_jit_timer_pop (gcc_jit_timer *timer,
+		   const char *item_name);
+
+/* Print timing information to the given stream about activity since
+   the timer was started.
+
+   This API entrypoint was added in LIBGCCJIT_ABI_4; you can test for its
+   presence using
+     #ifdef LIBGCCJIT_HAVE_TIMING_API
+*/
+
+extern void
+gcc_jit_timer_print (gcc_jit_timer *timer,
+		     FILE *f_out);
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/gcc/jit/libgccjit.map b/gcc/jit/libgccjit.map
index 3c0a0c1..e4302c6 100644
--- a/gcc/jit/libgccjit.map
+++ b/gcc/jit/libgccjit.map
@@ -128,3 +128,15 @@ LIBGCCJIT_ABI_3 {
     gcc_jit_case_as_object;
     gcc_jit_context_new_case;
 } LIBGCCJIT_ABI_2;
+
+# Add timing API.
+LIBGCCJIT_ABI_4 {
+  global:
+    gcc_jit_context_get_timer;
+    gcc_jit_context_set_timer;
+    gcc_jit_timer_new;
+    gcc_jit_timer_release;
+    gcc_jit_timer_push;
+    gcc_jit_timer_pop;
+    gcc_jit_timer_print;
+};
author	David Malcolm <dmalcolm@redhat.com>	2015-08-03 20:14:21 +0000
committer	David Malcolm <dmalcolm@gcc.gnu.org>	2015-08-03 20:14:21 +0000
commit	afed345982d5923b04d41885e868c9ca345ff3f9 (patch)
tree	b90c7df0235fa14daf2c76f22203ee08c2c32bcb /gcc/jit
parent	ef9da28d8fa1e2c0dc890f87374c0f21b18430c3 (diff)
download	gcc-afed345982d5923b04d41885e868c9ca345ff3f9.zip gcc-afed345982d5923b04d41885e868c9ca345ff3f9.tar.gz gcc-afed345982d5923b04d41885e868c9ca345ff3f9.tar.bz2