| 1 |
.. Copyright (C) 2014-2022 Free Software Foundation, Inc. |
| 2 |
Originally contributed by David Malcolm <[email protected]> |
| 3 |
|
| 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. |
| 8 |
|
| 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. |
| 13 |
|
| 14 |
You should have received a copy of the GNU General Public License |
| 15 |
along with this program. If not, see |
| 16 |
<https://www.gnu.org/licenses/>. |
| 17 |
|
| 18 |
.. default-domain:: cpp |
| 19 |
|
| 20 |
Compilation contexts |
| 21 |
==================== |
| 22 |
|
| 23 |
.. class:: gccjit::context |
| 24 |
|
| 25 |
The top-level of the C++ API is the :class:`gccjit::context` type. |
| 26 |
|
| 27 |
A :class:`gccjit::context` instance encapsulates the state of a |
| 28 |
compilation. |
| 29 |
|
| 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 *`. |
| 33 |
|
| 34 |
It is a thin wrapper around the C API's :c:type:`gcc_jit_context *`. |
| 35 |
|
| 36 |
Lifetime-management |
| 37 |
------------------- |
| 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. |
| 41 |
|
| 42 |
.. function:: gccjit::context gccjit::context::acquire () |
| 43 |
|
| 44 |
This function acquires a new :class:`gccjit::context` instance, |
| 45 |
which is independent of any others that may be present within this |
| 46 |
process. |
| 47 |
|
| 48 |
.. function:: void gccjit::context::release () |
| 49 |
|
| 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 |
| 53 |
context. |
| 54 |
|
| 55 |
It is invalid to use the context or any of its "contextual" objects |
| 56 |
after calling this. |
| 57 |
|
| 58 |
.. code-block:: c++ |
| 59 |
|
| 60 |
ctxt.release (); |
| 61 |
|
| 62 |
.. function:: gccjit::context \ |
| 63 |
gccjit::context::new_child_context () |
| 64 |
|
| 65 |
Given an existing JIT context, create a child context. |
| 66 |
|
| 67 |
The child inherits a copy of all option-settings from the parent. |
| 68 |
|
| 69 |
The child can reference objects created within the parent, but not |
| 70 |
vice-versa. |
| 71 |
|
| 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 |
| 74 |
context. |
| 75 |
|
| 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. |
| 80 |
|
| 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. |
| 87 |
|
| 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. |
| 91 |
|
| 92 |
|
| 93 |
Thread-safety |
| 94 |
------------- |
| 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. |
| 99 |
|
| 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. |
| 106 |
|
| 107 |
|
| 108 |
Error-handling |
| 109 |
-------------- |
| 110 |
.. FIXME: How does error-handling work for C++ API? |
| 111 |
|
| 112 |
You can only compile and get code from a context if no errors occur. |
| 113 |
|
| 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. |
| 117 |
|
| 118 |
Errors are printed on stderr and can be queried using |
| 119 |
:func:`gccjit::context::get_first_error`. |
| 120 |
|
| 121 |
.. function:: const char *\ |
| 122 |
gccjit::context::get_first_error (gccjit::context *ctxt) |
| 123 |
|
| 124 |
Returns the first error message that occurred on the context. |
| 125 |
|
| 126 |
The returned string is valid for the rest of the lifetime of the |
| 127 |
context. |
| 128 |
|
| 129 |
If no errors occurred, this will be NULL. |
| 130 |
|
| 131 |
Debugging |
| 132 |
--------- |
| 133 |
|
| 134 |
.. function:: void\ |
| 135 |
gccjit::context::dump_to_file (const std::string &path, \ |
| 136 |
int update_locations) |
| 137 |
|
| 138 |
To help with debugging: dump a C-like representation to the given path, |
| 139 |
describing what's been set up on the context. |
| 140 |
|
| 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 |
| 145 |
code in a debugger. |
| 146 |
|
| 147 |
.. function:: void\ |
| 148 |
gccjit::context::dump_reproducer_to_file (gcc_jit_context *ctxt,\ |
| 149 |
const char *path) |
| 150 |
|
| 151 |
This is a thin wrapper around the C API |
| 152 |
:c:func:`gcc_jit_context_dump_reproducer_to_file`, and hence works the |
| 153 |
same way. |
| 154 |
|
| 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. |
| 157 |
|
| 158 |
Options |
| 159 |
------- |
| 160 |
|
| 161 |
String Options |
| 162 |
************** |
| 163 |
|
| 164 |
.. function:: void \ |
| 165 |
gccjit::context::set_str_option (enum gcc_jit_str_option, \ |
| 166 |
const char *value) |
| 167 |
|
| 168 |
Set a string option of the context. |
| 169 |
|
| 170 |
This is a thin wrapper around the C API |
| 171 |
:c:func:`gcc_jit_context_set_str_option`; the options have the same |
| 172 |
meaning. |
| 173 |
|
| 174 |
Boolean options |
| 175 |
*************** |
| 176 |
|
| 177 |
.. function:: void \ |
| 178 |
gccjit::context::set_bool_option(enum gcc_jit_bool_option, \ |
| 179 |
int value) |
| 180 |
|
| 181 |
Set a boolean option of the context. |
| 182 |
|
| 183 |
This is a thin wrapper around the C API |
| 184 |
:c:func:`gcc_jit_context_set_bool_option`; the options have the same |
| 185 |
meaning. |
| 186 |
|
| 187 |
.. function:: void \ |
| 188 |
gccjit::context::set_bool_allow_unreachable_blocks (int bool_value) |
| 189 |
|
| 190 |
By default, libgccjit will issue an error about unreachable blocks |
| 191 |
within a function. |
| 192 |
|
| 193 |
This entrypoint can be used to disable that error; it is a thin wrapper |
| 194 |
around the C API |
| 195 |
:c:func:`gcc_jit_context_set_bool_allow_unreachable_blocks`. |
| 196 |
|
| 197 |
This entrypoint was added in :ref:`LIBGCCJIT_ABI_2`; you can test for |
| 198 |
its presence using |
| 199 |
|
| 200 |
.. code-block:: c |
| 201 |
|
| 202 |
#ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks |
| 203 |
|
| 204 |
.. function:: void \ |
| 205 |
gccjit::context::set_bool_use_external_driver (int bool_value) |
| 206 |
|
| 207 |
libgccjit internally generates assembler, and uses "driver" code |
| 208 |
for converting it to other formats (e.g. shared libraries). |
| 209 |
|
| 210 |
By default, libgccjit will use an embedded copy of the driver |
| 211 |
code. |
| 212 |
|
| 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`. |
| 216 |
|
| 217 |
This entrypoint was added in :ref:`LIBGCCJIT_ABI_5`; you can test for |
| 218 |
its presence using |
| 219 |
|
| 220 |
.. code-block:: c |
| 221 |
|
| 222 |
#ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver |
| 223 |
|
| 224 |
Integer options |
| 225 |
*************** |
| 226 |
|
| 227 |
.. function:: void \ |
| 228 |
gccjit::context::set_int_option (enum gcc_jit_int_option, \ |
| 229 |
int value) |
| 230 |
|
| 231 |
Set an integer option of the context. |
| 232 |
|
| 233 |
This is a thin wrapper around the C API |
| 234 |
:c:func:`gcc_jit_context_set_int_option`; the options have the same |
| 235 |
meaning. |
| 236 |
|
| 237 |
Additional command-line options |
| 238 |
******************************* |
| 239 |
|
| 240 |
.. function:: void \ |
| 241 |
gccjit::context::add_command_line_option (const char *optname) |
| 242 |
|
| 243 |
Add an arbitrary gcc command-line option to the context for use |
| 244 |
when compiling. |
| 245 |
|
| 246 |
This is a thin wrapper around the C API |
| 247 |
:c:func:`gcc_jit_context_add_command_line_option`. |
| 248 |
|
| 249 |
This entrypoint was added in :ref:`LIBGCCJIT_ABI_1`; you can test for |
| 250 |
its presence using |
| 251 |
|
| 252 |
.. code-block:: c |
| 253 |
|
| 254 |
#ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option |