Debian Codegraph @

gcc/jit/docs/topics/contexts.rst

raw
1 .. Copyright (C) 2014-2025 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:: c
19
20 Compilation contexts
21 ====================
22
23 .. type:: gcc_jit_context
24
25 The top-level of the API is the :c:type:`gcc_jit_context` type.
26
27 A :c:type:`gcc_jit_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 :c:func:`gcc_jit_context_compile` on it gives you a
32 :c:type:`gcc_jit_result`.
33
34 Lifetime-management
35 -------------------
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.
39
40 .. function:: gcc_jit_context *gcc_jit_context_acquire (void)
41
42 This function acquires a new :c:expr:`gcc_jit_context *` instance,
43 which is independent of any others that may be present within this
44 process.
45
46 .. function:: void gcc_jit_context_release (gcc_jit_context *ctxt)
47
48 This function releases all resources associated with the given context.
49 Both the context itself and all of its :c:expr:`gcc_jit_object *`
50 instances are cleaned up. It should be called exactly once on a given
51 context.
52
53 It is invalid to use the context or any of its "contextual" objects
54 after calling this.
55
56 .. code-block:: c
57
58 gcc_jit_context_release (ctxt);
59
60 .. function:: gcc_jit_context * gcc_jit_context_new_child_context (gcc_jit_context *parent_ctxt)
61
62 Given an existing JIT context, create a child context.
63
64 The child inherits a copy of all option-settings from the parent.
65
66 The child can reference objects created within the parent, but not
67 vice-versa.
68
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
71 context.
72
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.
77
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.
84
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.
88
89
90 Thread-safety
91 -------------
92 Instances of :c:expr:`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.
96
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.
103
104 .. _error-handling:
105
106 Error-handling
107 --------------
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.
111
112 Errors are printed on stderr and can be queried using
113 :c:func:`gcc_jit_context_get_first_error`.
114
115 They typically contain the name of the API entrypoint where the error
116 occurred, and pertinent information on the problem:
117
118 .. code-block:: console
119
120 ./buggy-program: error: gcc_jit_block_add_assignment: mismatching types: assignment to i (type: int) from "hello world" (type: const char *)
121
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). The first error
127 message is usually the one to pay attention to, since it is likely to
128 be responsible for all of the rest:
129
130 .. function:: const char *\
131 gcc_jit_context_get_first_error (gcc_jit_context *ctxt)
132
133 Returns the first error message that occurred on the context.
134
135 The returned string is valid for the rest of the lifetime of the
136 context.
137
138 If no errors occurred, this will be NULL.
139
140 If you are wrapping the C API for a higher-level language that supports
141 exception-handling, you may instead be interested in the last error that
142 occurred on the context, so that you can embed this in an exception:
143
144 .. function:: const char *\
145 gcc_jit_context_get_last_error (gcc_jit_context *ctxt)
146
147 Returns the last error message that occurred on the context.
148
149 If no errors occurred, this will be NULL.
150
151 If non-NULL, the returned string is only guaranteed to be valid until
152 the next call to libgccjit relating to this context.
153
154 Debugging
155 ---------
156
157 .. function:: void\
158 gcc_jit_context_dump_to_file (gcc_jit_context *ctxt,\
159 const char *path,\
160 int update_locations)
161
162 To help with debugging: dump a C-like representation to the given path,
163 describing what's been set up on the context.
164
165 If "update_locations" is true, then also set up :type:`gcc_jit_location`
166 information throughout the context, pointing at the dump file as if it
167 were a source file. This may be of use in conjunction with
168 :macro:`GCC_JIT_BOOL_OPTION_DEBUGINFO` to allow stepping through the
169 code in a debugger.
170
171 .. function:: void\
172 gcc_jit_context_set_logfile (gcc_jit_context *ctxt,\
173 FILE *logfile,\
174 int flags,\
175 int verbosity)
176
177 To help with debugging; enable ongoing logging of the context's
178 activity to the given file.
179
180 For example, the following will enable logging to stderr.
181
182 .. code-block:: c
183
184 gcc_jit_context_set_logfile (ctxt, stderr, 0, 0);
185
186 Examples of information logged include:
187
188 * API calls
189
190 * the various steps involved within compilation
191
192 * activity on any :c:type:`gcc_jit_result` instances created by
193 the context
194
195 * activity within any child contexts
196
197 An example of a log can be seen :ref:`here <example-of-log-file>`,
198 though the precise format and kinds of information logged is subject
199 to change.
200
201 The caller remains responsible for closing `logfile`, and it must not
202 be closed until all users are released. In particular, note that
203 child contexts and :c:type:`gcc_jit_result` instances created by
204 the context will use the logfile.
205
206 There may a performance cost for logging.
207
208 You can turn off logging on `ctxt` by passing `NULL` for `logfile`.
209 Doing so only affects the context; it does not affect child contexts
210 or :c:type:`gcc_jit_result` instances already created by
211 the context.
212
213 The parameters "flags" and "verbosity" are reserved for future
214 expansion, and must be zero for now.
215
216 To contrast the above: :c:func:`gcc_jit_context_dump_to_file` dumps the
217 current state of a context to the given path, whereas
218 :c:func:`gcc_jit_context_set_logfile` enables on-going logging of
219 future activies on a context to the given `FILE *`.
220
221
222 .. function:: void\
223 gcc_jit_context_dump_reproducer_to_file (gcc_jit_context *ctxt,\
224 const char *path)
225
226 Write C source code into `path` that can be compiled into a
227 self-contained executable (i.e. with libgccjit as the only dependency).
228 The generated code will attempt to replay the API calls that have been
229 made into the given context.
230
231 This may be useful when debugging the library or client code, for
232 reducing a complicated recipe for reproducing a bug into a simpler
233 form. For example, consider client code that parses some source file
234 into some internal representation, and then walks this IR, calling into
235 libgccjit. If this encounters a bug, a call to
236 `gcc_jit_context_dump_reproducer_to_file` will write out C code for
237 a much simpler executable that performs the equivalent calls into
238 libgccjit, without needing the client code and its data.
239
240 Typically you need to supply :option:`-Wno-unused-variable` when
241 compiling the generated file (since the result of each API call is
242 assigned to a unique variable within the generated C source, and not
243 all are necessarily then used).
244
245 .. function:: void\
246 gcc_jit_context_enable_dump (gcc_jit_context *ctxt,\
247 const char *dumpname, \
248 char **out_ptr)
249
250 Enable the dumping of a specific set of internal state from the
251 compilation, capturing the result in-memory as a buffer.
252
253 Parameter "dumpname" corresponds to the equivalent gcc command-line
254 option, without the "-fdump-" prefix.
255 For example, to get the equivalent of :option:`-fdump-tree-vrp1`,
256 supply ``"tree-vrp1"``:
257
258 .. code-block:: c
259
260 static char *dump_vrp1;
261
262 void
263 create_code (gcc_jit_context *ctxt)
264 {
265 gcc_jit_context_enable_dump (ctxt, "tree-vrp1", &dump_vrp1);
266 /* (other API calls omitted for brevity) */
267 }
268
269 The context directly stores the dumpname as a ``(const char *)``, so
270 the passed string must outlive the context.
271
272 :func:`gcc_jit_context_compile` will capture the dump as a
273 dynamically-allocated buffer, writing it to ``*out_ptr``.
274
275 The caller becomes responsible for calling:
276
277 .. code-block:: c
278
279 free (*out_ptr)
280
281 each time that :func:`gcc_jit_context_compile` is called.
282 ``*out_ptr`` will be written to, either with the address of a buffer,
283 or with ``NULL`` if an error occurred.
284
285 .. warning::
286
287 This API entrypoint is likely to be less stable than the others.
288 In particular, both the precise dumpnames, and the format and content
289 of the dumps are subject to change.
290
291 It exists primarily for writing the library's own test suite.
292
293 Options
294 -------
295
296 Options present in the initial release of libgccjit were handled using
297 enums, whereas those added subsequently have their own per-option API
298 entrypoints.
299
300 Adding entrypoints for each new option means that client code that use
301 the new options can be identified directly from binary metadata, which
302 would not be possible if we instead extended the various
303 ``enum gcc_jit_*_option``.
304
305 String Options
306 **************
307
308 .. function:: void gcc_jit_context_set_str_option(gcc_jit_context *ctxt, \
309 enum gcc_jit_str_option opt, \
310 const char *value)
311
312 Set a string option of the context.
313
314 .. enum:: gcc_jit_str_option
315
316 The parameter ``value`` can be NULL. If non-NULL, the call takes a
317 copy of the underlying string, so it is valid to pass in a pointer to
318 an on-stack buffer.
319
320 .. macro:: GCC_JIT_STR_OPTION_PROGNAME
321
322 The name of the program, for use as a prefix when printing error
323 messages to stderr. If `NULL`, or default, "libgccjit.so" is used.
324
325 .. macro:: GCC_JIT_STR_OPTION_SPECIAL_CHARS_IN_FUNC_NAMES
326
327 Alphabetic ASCII characters and underscores are always valid. Numeric
328 ASCII characters are always valid after the initial character of the
329 string. Use this entrypoint to specify additional ASCII characters that
330 are valid throughout function names (ex.: ".$").
331
332 Boolean options
333 ***************
334
335 .. function:: void gcc_jit_context_set_bool_option(gcc_jit_context *ctxt, \
336 enum gcc_jit_bool_option opt, \
337 int value)
338
339 Set a boolean option of the context.
340 Zero is "false" (the default), non-zero is "true".
341
342 .. enum:: gcc_jit_bool_option
343
344 .. macro:: GCC_JIT_BOOL_OPTION_DEBUGINFO
345
346 If true, :func:`gcc_jit_context_compile` will attempt to do the right
347 thing so that if you attach a debugger to the process, it will
348 be able to inspect variables and step through your code.
349
350 Note that you can't step through code unless you set up source
351 location information for the code (by creating and passing in
352 :type:`gcc_jit_location` instances).
353
354 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
355
356 If true, :func:`gcc_jit_context_compile` will dump its initial
357 "tree" representation of your code to stderr (before any
358 optimizations).
359
360 Here's some sample output (from the `square` example)::
361
362 <statement_list 0x7f4875a62cc0
363 type <void_type 0x7f4875a64bd0 VOID
364 align 8 symtab 0 alias set -1 canonical type 0x7f4875a64bd0
365 pointer_to_this <pointer_type 0x7f4875a64c78>>
366 side-effects head 0x7f4875a761e0 tail 0x7f4875a761f8 stmts 0x7f4875a62d20 0x7f4875a62d00
367
368 stmt <label_expr 0x7f4875a62d20 type <void_type 0x7f4875a64bd0>
369 side-effects
370 arg 0 <label_decl 0x7f4875a79080 entry type <void_type 0x7f4875a64bd0>
371 VOID file (null) line 0 col 0
372 align 1 context <function_decl 0x7f4875a77500 square>>>
373 stmt <return_expr 0x7f4875a62d00
374 type <integer_type 0x7f4875a645e8 public SI
375 size <integer_cst 0x7f4875a623a0 constant 32>
376 unit size <integer_cst 0x7f4875a623c0 constant 4>
377 align 32 symtab 0 alias set -1 canonical type 0x7f4875a645e8 precision 32 min <integer_cst 0x7f4875a62340 -2147483648> max <integer_cst 0x7f4875a62360 2147483647>
378 pointer_to_this <pointer_type 0x7f4875a6b348>>
379 side-effects
380 arg 0 <modify_expr 0x7f4875a72a78 type <integer_type 0x7f4875a645e8>
381 side-effects arg 0 <result_decl 0x7f4875a7a000 D.54>
382 arg 1 <mult_expr 0x7f4875a72a50 type <integer_type 0x7f4875a645e8>
383 arg 0 <parm_decl 0x7f4875a79000 i> arg 1 <parm_decl 0x7f4875a79000 i>>>>>
384
385 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE
386
387 If true, :func:`gcc_jit_context_compile` will dump the "gimple"
388 representation of your code to stderr, before any optimizations
389 are performed. The dump resembles C code:
390
391 .. code-block:: c
392
393 square (signed int i)
394 {
395 signed int D.56;
396
397 entry:
398 D.56 = i * i;
399 return D.56;
400 }
401
402 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE
403
404 If true, :func:`gcc_jit_context_compile` will dump the final
405 generated code to stderr, in the form of assembly language:
406
407 .. code-block:: gas
408
409 .file "fake.c"
410 .text
411 .globl square
412 .type square, @function
413 square:
414 .LFB0:
415 .cfi_startproc
416 pushq %rbp
417 .cfi_def_cfa_offset 16
418 .cfi_offset 6, -16
419 movq %rsp, %rbp
420 .cfi_def_cfa_register 6
421 movl %edi, -4(%rbp)
422 .L2:
423 movl -4(%rbp), %eax
424 imull -4(%rbp), %eax
425 popq %rbp
426 .cfi_def_cfa 7, 8
427 ret
428 .cfi_endproc
429 .LFE0:
430 .size square, .-square
431 .ident "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2)"
432 .section .note.GNU-stack,"",@progbits
433
434
435 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
436
437 If true, :func:`gcc_jit_context_compile` will print information to stderr
438 on the actions it is performing.
439
440 .. macro:: GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING
441
442 If true, :func:`gcc_jit_context_compile` will dump copious
443 amount of information on what it's doing to various
444 files within a temporary directory. Use
445 :macro:`GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES` (see below) to
446 see the results. The files are intended to be human-readable,
447 but the exact files and their formats are subject to change.
448
449 .. macro:: GCC_JIT_BOOL_OPTION_SELFCHECK_GC
450
451 If true, libgccjit will aggressively run its garbage collector, to
452 shake out bugs (greatly slowing down the compile). This is likely
453 to only be of interest to developers *of* the library. It is
454 used when running the selftest suite.
455
456 .. macro:: GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES
457
458 If true, the :type:`gcc_jit_context` will not clean up intermediate files
459 written to the filesystem, and will display their location on stderr.
460
461 .. function:: void \
462 gcc_jit_context_set_bool_allow_unreachable_blocks (gcc_jit_context *ctxt, \
463 int bool_value)
464
465 By default, libgccjit will issue an error about unreachable blocks
466 within a function.
467
468 This entrypoint can be used to disable that error.
469
470 This entrypoint was added in :ref:`LIBGCCJIT_ABI_2`; you can test for
471 its presence using
472
473 .. code-block:: c
474
475 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks
476
477 .. function:: void \
478 gcc_jit_context_set_bool_use_external_driver (gcc_jit_context *ctxt, \
479 int bool_value)
480
481 libgccjit internally generates assembler, and uses "driver" code
482 for converting it to other formats (e.g. shared libraries).
483
484 By default, libgccjit will use an embedded copy of the driver
485 code.
486
487 This option can be used to instead invoke an external driver executable
488 as a subprocess.
489
490 This entrypoint was added in :ref:`LIBGCCJIT_ABI_5`; you can test for
491 its presence using
492
493 .. code-block:: c
494
495 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver
496
497 .. function:: void \
498 gcc_jit_context_set_bool_print_errors_to_stderr (gcc_jit_context *ctxt, \
499 int enabled)
500
501 By default, libgccjit will print errors to stderr.
502
503 This entrypoint can be used to disable the printing.
504
505 This entrypoint was added in :ref:`LIBGCCJIT_ABI_23`; you can test for
506 its presence using
507
508 .. code-block:: c
509
510 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_print_errors_to_stderr
511
512 Integer options
513 ***************
514
515 .. function:: void gcc_jit_context_set_int_option (gcc_jit_context *ctxt, \
516 enum gcc_jit_int_option opt, \
517 int value)
518
519 Set an integer option of the context.
520
521 .. enum:: gcc_jit_int_option
522
523 There is just one integer option specified this way:
524
525 .. macro:: GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL
526
527 How much to optimize the code.
528
529 Valid values are 0-3, corresponding to GCC's command-line options
530 -O0 through -O3.
531
532 The default value is 0 (unoptimized).
533
534 Additional command-line options
535 *******************************
536
537 .. function:: void gcc_jit_context_add_command_line_option (gcc_jit_context *ctxt,\
538 const char *optname)
539
540 Add an arbitrary gcc command-line option to the context, for use
541 by :func:`gcc_jit_context_compile` and
542 :func:`gcc_jit_context_compile_to_file`.
543
544 The parameter ``optname`` must be non-NULL. The underlying buffer is
545 copied, so that it does not need to outlive the call.
546
547 Extra options added by `gcc_jit_context_add_command_line_option` are
548 applied *after* the regular options above, potentially overriding them.
549 Options from parent contexts are inherited by child contexts; options
550 from the parent are applied *before* those from the child.
551
552 For example:
553
554 .. code-block:: c
555
556 gcc_jit_context_add_command_line_option (ctxt, "-ffast-math");
557 gcc_jit_context_add_command_line_option (ctxt, "-fverbose-asm");
558
559 Note that only some options are likely to be meaningful; there is no
560 "frontend" within libgccjit, so typically only those affecting
561 optimization and code-generation are likely to be useful.
562
563 This entrypoint was added in :ref:`LIBGCCJIT_ABI_1`; you can test for
564 its presence using
565
566 .. code-block:: c
567
568 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option
569
570 .. function:: void gcc_jit_context_add_driver_option (gcc_jit_context *ctxt,\
571 const char *optname)
572
573 Add an arbitrary gcc driver option to the context, for use by
574 :func:`gcc_jit_context_compile` and
575 :func:`gcc_jit_context_compile_to_file`.
576
577 The parameter ``optname`` must be non-NULL. The underlying buffer is
578 copied, so that it does not need to outlive the call.
579
580 Extra options added by `gcc_jit_context_add_driver_option` are
581 applied *after* all other options potentially overriding them.
582 Options from parent contexts are inherited by child contexts; options
583 from the parent are applied *before* those from the child.
584
585 For example:
586
587 .. code-block:: c
588
589 gcc_jit_context_add_driver_option (ctxt, "-lm");
590 gcc_jit_context_add_driver_option (ctxt, "-fuse-linker-plugin");
591
592 gcc_jit_context_add_driver_option (ctxt, "obj.o");
593
594 gcc_jit_context_add_driver_option (ctxt, "-L.");
595 gcc_jit_context_add_driver_option (ctxt, "-lwhatever");
596
597 Note that only some options are likely to be meaningful; there is no
598 "frontend" within libgccjit, so typically only those affecting
599 assembler and linker are likely to be useful.
600
601 This entrypoint was added in :ref:`LIBGCCJIT_ABI_11`; you can test for
602 its presence using
603
604 .. code-block:: c
605
606 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option
607
608 Output options
609 **************
610
611 .. function:: void gcc_jit_context_set_output_ident (gcc_jit_context *ctxt,\
612 const char* output_ident)
613
614 Set the identifier to write in the .comment section of the output file to
615 ``output_ident``.
616
617 The parameter ``output_ident`` must be non-NULL.
618
619 This only works on some target, as you can see here:
620 https://gcc.gnu.org/onlinedocs/cpp/Other-Directives.html
621
622 Analogous to:
623
624 .. code-block:: c
625
626 #ident "My comment"
627
628 in C.
629
630 This entrypoint was added in :ref:`LIBGCCJIT_ABI_34`; you can test for
631 its presence using
632
633 .. code-block:: c
634
635 #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_output_ident