Mercurial > hg > CbC > CbC_gcc

comparison gcc/jit/docs/cp/topics/contexts.rst @ 111:04ced10e8804

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
gcc 7
author kono
date Fri, 27 Oct 2017 22:46:09 +0900
parents
children 84e7813d76e9
comparison
equal deleted inserted replaced
68:561a7518be6b 111:04ced10e8804
1 .. Copyright (C) 2014-2017 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
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