gcc/jit/docs/topics/contexts.rst

   1 .. Copyright (C) 2014-2023 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    <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    There is just one string option specified this way:
 321
 322    .. macro:: GCC_JIT_STR_OPTION_PROGNAME
 323
 324       The name of the program, for use as a prefix when printing error
 325       messages to stderr.  If `NULL`, or default, "libgccjit.so" is used.
 326
 327 Boolean options
 328 ***************
 329
 330 .. function:: void gcc_jit_context_set_bool_option(gcc_jit_context *ctxt, \
 331                                                    enum gcc_jit_bool_option opt, \
 332                                                    int value)
 333
 334   Set a boolean option of the context.
 335   Zero is "false" (the default), non-zero is "true".
 336
 337   .. enum:: gcc_jit_bool_option
 338
 339   .. macro:: GCC_JIT_BOOL_OPTION_DEBUGINFO
 340
 341      If true, :func:`gcc_jit_context_compile` will attempt to do the right
 342      thing so that if you attach a debugger to the process, it will
 343      be able to inspect variables and step through your code.
 344
 345      Note that you can't step through code unless you set up source
 346      location information for the code (by creating and passing in
 347      :type:`gcc_jit_location` instances).
 348
 349   .. macro:: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE
 350
 351      If true, :func:`gcc_jit_context_compile` will dump its initial
 352      "tree" representation of your code to stderr (before any
 353      optimizations).
 354
 355      Here's some sample output (from the `square` example)::
 356
 357         <statement_list 0x7f4875a62cc0
 358            type <void_type 0x7f4875a64bd0 VOID
 359                align 8 symtab 0 alias set -1 canonical type 0x7f4875a64bd0
 360                pointer_to_this <pointer_type 0x7f4875a64c78>>
 361            side-effects head 0x7f4875a761e0 tail 0x7f4875a761f8 stmts 0x7f4875a62d20 0x7f4875a62d00
 362
 363            stmt <label_expr 0x7f4875a62d20 type <void_type 0x7f4875a64bd0>
 364                side-effects
 365                arg 0 <label_decl 0x7f4875a79080 entry type <void_type 0x7f4875a64bd0>
 366                    VOID file (null) line 0 col 0
 367                    align 1 context <function_decl 0x7f4875a77500 square>>>
 368            stmt <return_expr 0x7f4875a62d00
 369                type <integer_type 0x7f4875a645e8 public SI
 370                    size <integer_cst 0x7f4875a623a0 constant 32>
 371                    unit size <integer_cst 0x7f4875a623c0 constant 4>
 372                    align 32 symtab 0 alias set -1 canonical type 0x7f4875a645e8 precision 32 min <integer_cst 0x7f4875a62340 -2147483648> max <integer_cst 0x7f4875a62360 2147483647>
 373                    pointer_to_this <pointer_type 0x7f4875a6b348>>
 374                side-effects
 375                arg 0 <modify_expr 0x7f4875a72a78 type <integer_type 0x7f4875a645e8>
 376                    side-effects arg 0 <result_decl 0x7f4875a7a000 D.54>
 377                    arg 1 <mult_expr 0x7f4875a72a50 type <integer_type 0x7f4875a645e8>
 378                        arg 0 <parm_decl 0x7f4875a79000 i> arg 1 <parm_decl 0x7f4875a79000 i>>>>>
 379
 380   .. macro:: GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE
 381
 382      If true, :func:`gcc_jit_context_compile` will dump the "gimple"
 383      representation of your code to stderr, before any optimizations
 384      are performed.  The dump resembles C code:
 385
 386      .. code-block:: c
 387
 388        square (signed int i)
 389        {
 390          signed int D.56;
 391
 392          entry:
 393          D.56 = i * i;
 394          return D.56;
 395        }
 396
 397   .. macro:: GCC_JIT_BOOL_OPTION_DUMP_GENERATED_CODE
 398
 399      If true, :func:`gcc_jit_context_compile` will dump the final
 400      generated code to stderr, in the form of assembly language:
 401
 402      .. code-block:: gas
 403
 404            .file    "fake.c"
 405            .text
 406            .globl    square
 407            .type    square, @function
 408        square:
 409        .LFB0:
 410            .cfi_startproc
 411            pushq    %rbp
 412            .cfi_def_cfa_offset 16
 413            .cfi_offset 6, -16
 414            movq    %rsp, %rbp
 415            .cfi_def_cfa_register 6
 416            movl    %edi, -4(%rbp)
 417        .L2:
 418            movl    -4(%rbp), %eax
 419            imull    -4(%rbp), %eax
 420            popq    %rbp
 421            .cfi_def_cfa 7, 8
 422            ret
 423            .cfi_endproc
 424        .LFE0:
 425            .size    square, .-square
 426            .ident    "GCC: (GNU) 4.9.0 20131023 (Red Hat 0.2)"
 427            .section    .note.GNU-stack,"",@progbits
 428
 429
 430   .. macro:: GCC_JIT_BOOL_OPTION_DUMP_SUMMARY
 431
 432      If true, :func:`gcc_jit_context_compile` will print information to stderr
 433      on the actions it is performing.
 434
 435   .. macro:: GCC_JIT_BOOL_OPTION_DUMP_EVERYTHING
 436
 437      If true, :func:`gcc_jit_context_compile` will dump copious
 438      amount of information on what it's doing to various
 439      files within a temporary directory.  Use
 440      :macro:`GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES` (see below) to
 441      see the results.  The files are intended to be human-readable,
 442      but the exact files and their formats are subject to change.
 443
 444   .. macro:: GCC_JIT_BOOL_OPTION_SELFCHECK_GC
 445
 446      If true, libgccjit will aggressively run its garbage collector, to
 447      shake out bugs (greatly slowing down the compile).  This is likely
 448      to only be of interest to developers *of* the library.  It is
 449      used when running the selftest suite.
 450
 451   .. macro:: GCC_JIT_BOOL_OPTION_KEEP_INTERMEDIATES
 452
 453      If true, the :type:`gcc_jit_context` will not clean up intermediate files
 454      written to the filesystem, and will display their location on stderr.
 455
 456 .. function:: void \
 457               gcc_jit_context_set_bool_allow_unreachable_blocks (gcc_jit_context *ctxt, \
 458                                                                  int bool_value)
 459
 460    By default, libgccjit will issue an error about unreachable blocks
 461    within a function.
 462
 463    This entrypoint can be used to disable that error.
 464
 465    This entrypoint was added in :ref:`LIBGCCJIT_ABI_2`; you can test for
 466    its presence using
 467
 468    .. code-block:: c
 469
 470       #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_allow_unreachable_blocks
 471
 472 .. function:: void \
 473               gcc_jit_context_set_bool_use_external_driver (gcc_jit_context *ctxt, \
 474                                                             int bool_value)
 475
 476    libgccjit internally generates assembler, and uses "driver" code
 477    for converting it to other formats (e.g. shared libraries).
 478
 479    By default, libgccjit will use an embedded copy of the driver
 480    code.
 481
 482    This option can be used to instead invoke an external driver executable
 483    as a subprocess.
 484
 485    This entrypoint was added in :ref:`LIBGCCJIT_ABI_5`; you can test for
 486    its presence using
 487
 488    .. code-block:: c
 489
 490       #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_use_external_driver
 491
 492 .. function:: void \
 493               gcc_jit_context_set_bool_print_errors_to_stderr (gcc_jit_context *ctxt, \
 494                                                                  int enabled)
 495
 496    By default, libgccjit will print errors to stderr.
 497
 498    This entrypoint can be used to disable the printing.
 499
 500    This entrypoint was added in :ref:`LIBGCCJIT_ABI_23`; you can test for
 501    its presence using
 502
 503    .. code-block:: c
 504
 505       #ifdef LIBGCCJIT_HAVE_gcc_jit_context_set_bool_print_errors_to_stderr
 506
 507 Integer options
 508 ***************
 509
 510 .. function:: void gcc_jit_context_set_int_option (gcc_jit_context *ctxt, \
 511                                                    enum gcc_jit_int_option opt, \
 512                                                    int value)
 513
 514   Set an integer option of the context.
 515
 516   .. enum:: gcc_jit_int_option
 517
 518   There is just one integer option specified this way:
 519
 520   .. macro:: GCC_JIT_INT_OPTION_OPTIMIZATION_LEVEL
 521
 522      How much to optimize the code.
 523
 524      Valid values are 0-3, corresponding to GCC's command-line options
 525      -O0 through -O3.
 526
 527      The default value is 0 (unoptimized).
 528
 529 Additional command-line options
 530 *******************************
 531
 532 .. function:: void gcc_jit_context_add_command_line_option (gcc_jit_context *ctxt,\
 533                                                             const char *optname)
 534
 535    Add an arbitrary gcc command-line option to the context, for use
 536    by :func:`gcc_jit_context_compile` and
 537    :func:`gcc_jit_context_compile_to_file`.
 538
 539    The parameter ``optname`` must be non-NULL.  The underlying buffer is
 540    copied, so that it does not need to outlive the call.
 541
 542    Extra options added by `gcc_jit_context_add_command_line_option` are
 543    applied *after* the regular options above, potentially overriding them.
 544    Options from parent contexts are inherited by child contexts; options
 545    from the parent are applied *before* those from the child.
 546
 547    For example:
 548
 549    .. code-block:: c
 550
 551       gcc_jit_context_add_command_line_option (ctxt, "-ffast-math");
 552       gcc_jit_context_add_command_line_option (ctxt, "-fverbose-asm");
 553
 554    Note that only some options are likely to be meaningful; there is no
 555    "frontend" within libgccjit, so typically only those affecting
 556    optimization and code-generation are likely to be useful.
 557
 558    This entrypoint was added in :ref:`LIBGCCJIT_ABI_1`; you can test for
 559    its presence using
 560
 561    .. code-block:: c
 562
 563       #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_command_line_option
 564
 565 .. function:: void gcc_jit_context_add_driver_option (gcc_jit_context *ctxt,\
 566                                                       const char *optname)
 567
 568    Add an arbitrary gcc driver option to the context, for use by
 569    :func:`gcc_jit_context_compile` and
 570    :func:`gcc_jit_context_compile_to_file`.
 571
 572    The parameter ``optname`` must be non-NULL.  The underlying buffer is
 573    copied, so that it does not need to outlive the call.
 574
 575    Extra options added by `gcc_jit_context_add_driver_option` are
 576    applied *after* all other options potentially overriding them.
 577    Options from parent contexts are inherited by child contexts; options
 578    from the parent are applied *before* those from the child.
 579
 580    For example:
 581
 582    .. code-block:: c
 583
 584       gcc_jit_context_add_driver_option (ctxt, "-lm");
 585       gcc_jit_context_add_driver_option (ctxt, "-fuse-linker-plugin");
 586
 587       gcc_jit_context_add_driver_option (ctxt, "obj.o");
 588
 589       gcc_jit_context_add_driver_option (ctxt, "-L.");
 590       gcc_jit_context_add_driver_option (ctxt, "-lwhatever");
 591
 592    Note that only some options are likely to be meaningful; there is no
 593    "frontend" within libgccjit, so typically only those affecting
 594    assembler and linker are likely to be useful.
 595
 596    This entrypoint was added in :ref:`LIBGCCJIT_ABI_11`; you can test for
 597    its presence using
 598
 599    .. code-block:: c
 600
 601       #ifdef LIBGCCJIT_HAVE_gcc_jit_context_add_driver_option