]>
Commit | Line | Data |
---|---|---|
a5544970 | 1 | .. Copyright (C) 2014-2019 Free Software Foundation, Inc. |
29df5715 DM |
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 | ||
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 | ||
86d0ac88 DM |
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. | |
29df5715 DM |
157 | |
158 | Options | |
159 | ------- | |
160 | ||
35291c7d DM |
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. | |
29df5715 DM |
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 | ||
6a3603e3 DM |
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 | ||
9376dd63 DM |
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 | ||
29df5715 DM |
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. | |
fa22c20d DM |
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 |