gcc/jit/docs/topics/results.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:: c
  19
  20 Compilation results
  21 ===================
  22
  23 .. type:: gcc_jit_result
  24
  25   A `gcc_jit_result` encapsulates the result of compiling a context,
  26   and the lifetimes of any machine code functions or globals that are
  27   within it.
  28
  29 .. function:: gcc_jit_result *\
  30               gcc_jit_context_compile (gcc_jit_context *ctxt)
  31
  32    This calls into GCC and builds the code, returning a
  33    `gcc_jit_result *`.
  34
  35    If this is non-NULL, the caller becomes responsible for
  36    calling :func:`gcc_jit_result_release` on it once they're done
  37    with it.
  38
  39 .. function:: void *\
  40               gcc_jit_result_get_code (gcc_jit_result *result,\
  41                                        const char *funcname)
  42
  43    Locate a given function within the built machine code.
  44
  45    Functions are looked up by name.  For this to succeed, a function
  46    with a name matching `funcname` must have been created on
  47    `result`'s context (or a parent context) via a call to
  48    :func:`gcc_jit_context_new_function` with `kind`
  49    :macro:`GCC_JIT_FUNCTION_EXPORTED`:
  50
  51    .. code-block:: c
  52
  53      gcc_jit_context_new_function (ctxt,
  54                                    any_location, /* or NULL */
  55                                    /* Required for func to be visible to
  56                                       gcc_jit_result_get_code: */
  57                                    GCC_JIT_FUNCTION_EXPORTED,
  58                                    any_return_type,
  59                                    /* Must string-compare equal: */
  60                                    funcname,
  61                                    /* etc */);
  62
  63    If such a function is not found (or `result` or `funcname` are
  64    ``NULL``), an error message will be emitted on stderr and
  65    ``NULL`` will be returned.
  66
  67    If the function is found, the result will need to be cast to a
  68    function pointer of the correct type before it can be called.
  69
  70    Note that the resulting machine code becomes invalid after
  71    :func:`gcc_jit_result_release` is called on the
  72    :type:`gcc_jit_result *`; attempting to call it after that may lead
  73    to a segmentation fault.
  74
  75 .. function:: void *\
  76               gcc_jit_result_get_global (gcc_jit_result *result,\
  77                                          const char *name)
  78
  79    Locate a given global within the built machine code.
  80
  81    Globals are looked up by name.  For this to succeed, a global
  82    with a name matching `name` must have been created on
  83    `result`'s context (or a parent context) via a call to
  84    :func:`gcc_jit_context_new_global` with `kind`
  85    :macro:`GCC_JIT_GLOBAL_EXPORTED`.
  86
  87    If the global is found, the result will need to be cast to a
  88    pointer of the correct type before it can be called.
  89
  90    This is a *pointer* to the global, so e.g. for an :c:type:`int` this is
  91    an :c:type:`int *`.
  92
  93    For example, given an ``int foo;`` created this way:
  94
  95    .. code-block:: c
  96
  97      gcc_jit_lvalue *exported_global =
  98        gcc_jit_context_new_global (ctxt,
  99        any_location, /* or NULL */
 100        GCC_JIT_GLOBAL_EXPORTED,
 101        int_type,
 102        "foo");
 103
 104    we can access it like this:
 105
 106    .. code-block:: c
 107
 108       int *ptr_to_foo =
 109         (int *)gcc_jit_result_get_global (result, "foo");
 110
 111    If such a global is not found (or `result` or `name` are
 112    ``NULL``), an error message will be emitted on stderr and
 113    ``NULL`` will be returned.
 114
 115    Note that the resulting address becomes invalid after
 116    :func:`gcc_jit_result_release` is called on the
 117    :type:`gcc_jit_result *`; attempting to use it after that may lead
 118    to a segmentation fault.
 119
 120 .. function:: void\
 121               gcc_jit_result_release (gcc_jit_result *result)
 122
 123    Once we're done with the code, this unloads the built .so file.
 124    This cleans up the result; after calling this, it's no longer
 125    valid to use the result, or any code or globals that were obtained
 126    by calling :func:`gcc_jit_result_get_code` or
 127    :func:`gcc_jit_result_get_global` on it.