gcc/jit/docs/cp/topics/contexts.rst

   1 .. Copyright (C) 2014-2015 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 Integer options
 188 ***************
 189
 190 .. function:: void \
 191               gccjit::context::set_int_option (enum gcc_jit_int_option, \
 192                                                int value)
 193
 194   Set an integer option of the context.
 195
 196   This is a thin wrapper around the C API
 197   :c:func:`gcc_jit_context_set_int_option`; the options have the same
 198   meaning.