1 .. Copyright (C) 2014-2019 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <dmalcolm@redhat.com>
4 This is free software: you can redistribute it and/or modify it
5 under the terms of the GNU General Public License as published by
6 the Free Software Foundation, either version 3 of the License, or
7 (at your option) any later version.
9 This program is distributed in the hope that it will be useful, but
10 WITHOUT ANY WARRANTY; without even the implied warranty of
11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 General Public License for more details.
14 You should have received a copy of the GNU General Public License
15 along with this program. If not, see
16 <http://www.gnu.org/licenses/>.
18 .. default-domain:: cpp
23 .. class:: gccjit::context
25 The top-level of the C++ API is the :class:`gccjit::context` type.
27 A :class:`gccjit::context` instance encapsulates the state of a
30 You can set up options on it, and add types, functions and code.
31 Invoking :func:`gccjit::context::compile` on it gives you a
32 :c:type:`gcc_jit_result *`.
34 It is a thin wrapper around the C API's :c:type:`gcc_jit_context *`.
38 Contexts are the unit of lifetime-management within the API: objects
39 have their lifetime bounded by the context they are created within, and
40 cleanup of such objects is done for you when the context is released.
42 .. function:: gccjit::context gccjit::context::acquire ()
44 This function acquires a new :class:`gccjit::context` instance,
45 which is independent of any others that may be present within this
48 .. function:: void gccjit::context::release ()
50 This function releases all resources associated with the given context.
51 Both the context itself and all of its :c:type:`gccjit::object *`
52 instances are cleaned up. It should be called exactly once on a given
55 It is invalid to use the context or any of its "contextual" objects
62 .. function:: gccjit::context \
63 gccjit::context::new_child_context ()
65 Given an existing JIT context, create a child context.
67 The child inherits a copy of all option-settings from the parent.
69 The child can reference objects created within the parent, but not
72 The lifetime of the child context must be bounded by that of the
73 parent: you should release a child context before releasing the parent
76 If you use a function from a parent context within a child context,
77 you have to compile the parent context before you can compile the
78 child context, and the gccjit::result of the parent context must
79 outlive the gccjit::result of the child context.
81 This allows caching of shared initializations. For example, you could
82 create types and declarations of global functions in a parent context
83 once within a process, and then create child contexts whenever a
84 function or loop becomes hot. Each such child context can be used for
85 JIT-compiling just one function or loop, but can reference types
86 and helper functions created within the parent context.
88 Contexts can be arbitrarily nested, provided the above rules are
89 followed, but it's probably not worth going above 2 or 3 levels, and
90 there will likely be a performance hit for such nesting.
95 Instances of :class:`gccjit::context` created via
96 :func:`gccjit::context::acquire` are independent from each other:
97 only one thread may use a given context at once, but multiple threads
98 could each have their own contexts without needing locks.
100 Contexts created via :func:`gccjit::context::new_child_context` are
101 related to their parent context. They can be partitioned by their
102 ultimate ancestor into independent "family trees". Only one thread
103 within a process may use a given "family tree" of such contexts at once,
104 and if you're using multiple threads you should provide your own locking
105 around entire such context partitions.
110 .. FIXME: How does error-handling work for C++ API?
112 You can only compile and get code from a context if no errors occur.
114 In general, if an error occurs when using an API entrypoint, it returns
115 NULL. You don't have to check everywhere for NULL results, since the
116 API gracefully handles a NULL being passed in for any argument.
118 Errors are printed on stderr and can be queried using
119 :func:`gccjit::context::get_first_error`.
121 .. function:: const char *\
122 gccjit::context::get_first_error (gccjit::context *ctxt)
124 Returns the first error message that occurred on the context.
126 The returned string is valid for the rest of the lifetime of the
129 If no errors occurred, this will be NULL.
135 gccjit::context::dump_to_file (const std::string &path, \
136 int update_locations)
138 To help with debugging: dump a C-like representation to the given path,
139 describing what's been set up on the context.
141 If "update_locations" is true, then also set up :class:`gccjit::location`
142 information throughout the context, pointing at the dump file as if it
143 were a source file. This may be of use in conjunction with
144 :c:macro:`GCCJIT::BOOL_OPTION_DEBUGINFO` to allow stepping through the
148 gccjit::context::dump_reproducer_to_file (gcc_jit_context *ctxt,\
151 This is a thin wrapper around the C API
152 :c:func:`gcc_jit_context_dump_reproducer_to_file`, and hence works the
155 Note that the generated source is C code, not C++; this might be of use
156 for seeing what the C++ bindings are doing at the C level.
165 gccjit::context::set_str_option (enum gcc_jit_str_option, \
168 Set a string option of the context.
170 This is a thin wrapper around the C API
171 :c:func:`gcc_jit_context_set_str_option`; the options have the same
178 gccjit::context::set_bool_option(enum gcc_jit_bool_option, \
181 Set a boolean option of the context.
183 This is a thin wrapper around the C API
184 :c:func:`gcc_jit_context_set_bool_option`; the options have the same
188 gccjit::context::set_bool_allow_unreachable_blocks (int bool_value)
190 By default, libgccjit will issue an error about unreachable blocks
193 This entrypoint can be used to disable that error; it is a thin wrapper
195 :c:func:`gcc_jit_context_set_bool_allow_unreachable_blocks`.
197 This entrypoint was added in :ref:`LIBGCCJIT_ABI_2`; you can test for
202 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks
205 gccjit::context::set_bool_use_external_driver (int bool_value)
207 libgccjit internally generates assembler, and uses "driver" code
208 for converting it to other formats (e.g. shared libraries).
210 By default, libgccjit will use an embedded copy of the driver
213 This option can be used to instead invoke an external driver executable
214 as a subprocess; it is a thin wrapper around the C API
215 :c:func:`gcc_jit_context_set_bool_use_external_driver`.
217 This entrypoint was added in :ref:`LIBGCCJIT_ABI_5`; you can test for
222 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver
228 gccjit::context::set_int_option (enum gcc_jit_int_option, \
231 Set an integer option of the context.
233 This is a thin wrapper around the C API
234 :c:func:`gcc_jit_context_set_int_option`; the options have the same
237 Additional command-line options
238 *******************************
241 gccjit::context::add_command_line_option (const char *optname)
243 Add an arbitrary gcc command-line option to the context for use
246 This is a thin wrapper around the C API
247 :c:func:`gcc_jit_context_add_command_line_option`.
249 This entrypoint was added in :ref:`LIBGCCJIT_ABI_1`; you can test for
254 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option