1.. Copyright (C) 2014-2018 Free Software Foundation, Inc. 2 Originally contributed by David Malcolm <dmalcolm@redhat.com> 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 <http://www.gnu.org/licenses/>. 17 18.. default-domain:: cpp 19 20Compilation contexts 21==================== 22 23.. class:: gccjit::context 24 25The top-level of the C++ API is the :class:`gccjit::context` type. 26 27A :class:`gccjit::context` instance encapsulates the state of a 28compilation. 29 30You can set up options on it, and add types, functions and code. 31Invoking :func:`gccjit::context::compile` on it gives you a 32:c:type:`gcc_jit_result *`. 33 34It is a thin wrapper around the C API's :c:type:`gcc_jit_context *`. 35 36Lifetime-management 37------------------- 38Contexts are the unit of lifetime-management within the API: objects 39have their lifetime bounded by the context they are created within, and 40cleanup 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 93Thread-safety 94------------- 95Instances of :class:`gccjit::context` created via 96:func:`gccjit::context::acquire` are independent from each other: 97only one thread may use a given context at once, but multiple threads 98could each have their own contexts without needing locks. 99 100Contexts created via :func:`gccjit::context::new_child_context` are 101related to their parent context. They can be partitioned by their 102ultimate ancestor into independent "family trees". Only one thread 103within a process may use a given "family tree" of such contexts at once, 104and if you're using multiple threads you should provide your own locking 105around entire such context partitions. 106 107 108Error-handling 109-------------- 110.. FIXME: How does error-handling work for C++ API? 111 112You can only compile and get code from a context if no errors occur. 113 114In general, if an error occurs when using an API entrypoint, it returns 115NULL. You don't have to check everywhere for NULL results, since the 116API gracefully handles a NULL being passed in for any argument. 117 118Errors 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 131Debugging 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 158Options 159------- 160 161String 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 174Boolean 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 224Integer 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 237Additional 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 255