1 .. Copyright (C) 2014 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/>.
23 .. type:: gcc_jit_context
25 The top-level of the API is the :c:type:`gcc_jit_context` type.
27 A :c:type:`gcc_jit_context` instance encapsulates the state of a
30 You can set up options on it, and add types, functions and code.
31 Invoking :c:func:`gcc_jit_context_compile` on it gives you a
32 :c:type:`gcc_jit_result`.
36 Contexts are the unit of lifetime-management within the API: objects
37 have their lifetime bounded by the context they are created within, and
38 cleanup of such objects is done for you when the context is released.
40 .. function:: gcc_jit_context *gcc_jit_context_acquire (void)
42 This function acquires a new :c:type:`gcc_jit_object *` instance,
43 which is independent of any others that may be present within this
46 .. function:: void gcc_jit_context_release (gcc_jit_context *ctxt)
48 This function releases all resources associated with the given context.
49 Both the context itself and all of its :c:type:`gcc_jit_object *`
50 instances are cleaned up. It should be called exactly once on a given
53 It is invalid to use the context or any of its "contextual" objects
58 gcc_jit_context_release (ctxt);
60 .. function:: gcc_jit_context * gcc_jit_context_new_child_context (gcc_jit_context *parent_ctxt)
62 Given an existing JIT context, create a child context.
64 The child inherits a copy of all option-settings from the parent.
66 The child can reference objects created within the parent, but not
69 The lifetime of the child context must be bounded by that of the
70 parent: you should release a child context before releasing the parent
73 If you use a function from a parent context within a child context,
74 you have to compile the parent context before you can compile the
75 child context, and the gcc_jit_result of the parent context must
76 outlive the gcc_jit_result of the child context.
78 This allows caching of shared initializations. For example, you could
79 create types and declarations of global functions in a parent context
80 once within a process, and then create child contexts whenever a
81 function or loop becomes hot. Each such child context can be used for
82 JIT-compiling just one function or loop, but can reference types
83 and helper functions created within the parent context.
85 Contexts can be arbitrarily nested, provided the above rules are
86 followed, but it's probably not worth going above 2 or 3 levels, and
87 there will likely be a performance hit for such nesting.
92 Instances of :c:type:`gcc_jit_context *` created via
93 :c:func:`gcc_jit_context_acquire` are independent from each other:
94 only one thread may use a given context at once, but multiple threads
95 could each have their own contexts without needing locks.
97 Contexts created via :c:func:`gcc_jit_context_new_child_context` are
98 related to their parent context. They can be partitioned by their
99 ultimate ancestor into independent "family trees". Only one thread
100 within a process may use a given "family tree" of such contexts at once,
101 and if you're using multiple threads you should provide your own locking
102 around entire such context partitions.
108 Various kinds of errors are possible when using the API, such as
109 mismatched types in an assignment. You can only compile and get code from
110 a context if no errors occur.
112 Errors are printed on stderr and can be queried using
113 :c:func:`gcc_jit_context_get_first_error`.
115 They typically contain the name of the API entrypoint where the error
116 occurred, and pertinent information on the problem:
118 .. code-block:: console
120 ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
122 In general, if an error occurs when using an API entrypoint, the
123 entrypoint returns NULL. You don't have to check everywhere for NULL
124 results, since the API handles a NULL being passed in for any
125 argument by issuing another error. This typically leads to a cascade of
126 followup error messages, but is safe (albeit verbose).
128 .. function:: const char *\
129 gcc_jit_context_get_first_error (gcc_jit_context *ctxt)
131 Returns the first error message that occurred on the context.
133 The returned string is valid for the rest of the lifetime of the
136 If no errors occurred, this will be NULL.
142 gcc_jit_context_dump_to_file (gcc_jit_context *ctxt,\
144 int update_locations)
146 To help with debugging: dump a C-like representation to the given path,
147 describing what's been set up on the context.
149 If "update_locations" is true, then also set up :type:`gcc_jit_location`
150 information throughout the context, pointing at the dump file as if it
151 were a source file. This may be of use in conjunction with
152 :macro:`GCC_JIT_BOOL_OPTION_DEBUGINFO` to allow stepping through the
156 gcc_jit_context_enable_dump (gcc_jit_context *ctxt,\
157 const char *dumpname, \
160 Enable the dumping of a specific set of internal state from the
161 compilation, capturing the result in-memory as a buffer.
163 Parameter "dumpname" corresponds to the equivalent gcc command-line
164 option, without the "-fdump-" prefix.
165 For example, to get the equivalent of :option:`-fdump-tree-vrp1`,
166 supply ``"tree-vrp1"``:
170 static char *dump_vrp1;
173 create_code (gcc_jit_context *ctxt)
175 gcc_jit_context_enable_dump (ctxt, "tree-vrp1", &dump_vrp1);
176 /* (other API calls omitted for brevity) */
179 The context directly stores the dumpname as a ``(const char *)``, so
180 the passed string must outlive the context.
182 :func:`gcc_jit_context_compile` will capture the dump as a
183 dynamically-allocated buffer, writing it to ``*out_ptr``.
185 The caller becomes responsible for calling:
191 each time that :func:`gcc_jit_context_compile` is called.
192 ``*out_ptr`` will be written to, either with the address of a buffer,
193 or with ``NULL`` if an error occurred.
197 This API entrypoint is likely to be less stable than the others.
198 In particular, both the precise dumpnames, and the format and content
199 of the dumps are subject to change.
201 It exists primarily for writing the library's own test suite.
209 .. function:: void gcc_jit_context_set_str_option(gcc_jit_context *ctxt, \
210 enum gcc_jit_str_option opt, \
213 Set a string option of the context.
215 .. type:: enum gcc_jit_str_option
217 There is currently just one string option:
219 .. macro:: GCC_JIT_STR_OPTION_PROGNAME
221 The name of the program, for use as a prefix when printing error
222 messages to stderr. If `NULL`, or default, "libgccjit.so" is used.
227 .. function:: void gcc_jit_context_set_bool_option(gcc_jit_context *ctxt, \
228 enum gcc_jit_bool_option opt, \
231 Set a boolean option of the context.
232 Zero is "false" (the default), non-zero is "true".
234 .. type:: enum gcc_jit_bool_option
236 .. macro:: GCC_JIT_BOOL_OPTION_DEBUGINFO
238 If true, :func:`gcc_jit_context_compile` will attempt to do the right
239 thing so that if you attach a debugger to the process, it will
240 be able to inspect variables and step through your code.
242 Note that you can't step through code unless you set up source
243 location information for the code (by creating and passing in
244 :type:`gcc_jit_location` instances).
246 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
248 If true, :func:`gcc_jit_context_compile` will dump its initial
249 "tree" representation of your code to stderr (before any
252 Here's some sample output (from the `square` example)::
254 <statement_list 0x7f4875a62cc0
255 type <void_type 0x7f4875a64bd0 VOID
256 align 8 symtab 0 alias set -1 canonical type 0x7f4875a64bd0
257 pointer_to_this <pointer_type 0x7f4875a64c78>>
258 side-effects head 0x7f4875a761e0 tail 0x7f4875a761f8 stmts 0x7f4875a62d20 0x7f4875a62d00
260 stmt <label_expr 0x7f4875a62d20 type <void_type 0x7f4875a64bd0>
262 arg 0 <label_decl 0x7f4875a79080 entry type <void_type 0x7f4875a64bd0>
263 VOID file (null) line 0 col 0
264 align 1 context <function_decl 0x7f4875a77500 square>>>
265 stmt <return_expr 0x7f4875a62d00
266 type <integer_type 0x7f4875a645e8 public SI
267 size <integer_cst 0x7f4875a623a0 constant 32>
268 unit size <integer_cst 0x7f4875a623c0 constant 4>
269 align 32 symtab 0 alias set -1 canonical type 0x7f4875a645e8 precision 32 min <integer_cst 0x7f4875a62340 -2147483648> max <integer_cst 0x7f4875a62360 2147483647>
270 pointer_to_this <pointer_type 0x7f4875a6b348>>
272 arg 0 <modify_expr 0x7f4875a72a78 type <integer_type 0x7f4875a645e8>
273 side-effects arg 0 <result_decl 0x7f4875a7a000 D.54>
274 arg 1 <mult_expr 0x7f4875a72a50 type <integer_type 0x7f4875a645e8>
275 arg 0 <parm_decl 0x7f4875a79000 i> arg 1 <parm_decl 0x7f4875a79000 i>>>>>
277 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE
279 If true, :func:`gcc_jit_context_compile` will dump the "gimple"
280 representation of your code to stderr, before any optimizations
281 are performed. The dump resembles C code:
285 square (signed int i)
294 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE
296 If true, :func:`gcc_jit_context_compile` will dump the final
297 generated code to stderr, in the form of assembly language:
304 .type square, @function
309 .cfi_def_cfa_offset 16
312 .cfi_def_cfa_register 6
322 .size square, .-square
323 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.1-%{gcc_release})"
324 .section .note.GNU-stack,"",@progbits
327 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
329 If true, :func:`gcc_jit_context_compile` will print information to stderr
330 on the actions it is performing, followed by a profile showing
331 the time taken and memory usage of each phase.
333 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING
335 If true, :func:`gcc_jit_context_compile` will dump copious
336 amount of information on what it's doing to various
337 files within a temporary directory. Use
338 :macro:`GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES` (see below) to
339 see the results. The files are intended to be human-readable,
340 but the exact files and their formats are subject to change.
342 .. macro:: GCC_JIT_BOOL_OPTION_SELFCHECK_GC
344 If true, libgccjit will aggressively run its garbage collector, to
345 shake out bugs (greatly slowing down the compile). This is likely
346 to only be of interest to developers *of* the library. It is
347 used when running the selftest suite.
349 .. macro:: GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES
351 If true, the :type:`gcc_jit_context` will not clean up intermediate files
352 written to the filesystem, and will display their location on stderr.
357 .. function:: void gcc_jit_context_set_int_option (gcc_jit_context *ctxt, \
358 enum gcc_jit_int_option opt, \
361 Set an integer option of the context.
363 .. type:: enum gcc_jit_int_option
365 There is currently just one integer option:
367 .. macro:: GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL
369 How much to optimize the code.
371 Valid values are 0-3, corresponding to GCC's command-line options
374 The default value is 0 (unoptimized).