gcc/jit/docs/topics/objects.rst

   1 .. Copyright (C) 2014-2024 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 Objects
  21 =======
  22
  23 .. type:: gcc_jit_object
  24
  25 Almost every entity in the API (with the exception of
  26 :c:expr:`gcc_jit_context *` and :c:expr:`gcc_jit_result *`) is a
  27 "contextual" object, a :c:expr:`gcc_jit_object *`
  28
  29 A JIT object:
  30
  31   * is associated with a :c:expr:`gcc_jit_context *`.
  32
  33   * is automatically cleaned up for you when its context is released so
  34     you don't need to manually track and cleanup all objects, just the
  35     contexts.
  36
  37 Although the API is C-based, there is a form of class hierarchy, which
  38 looks like this::
  39
  40   +- gcc_jit_object
  41       +- gcc_jit_location
  42       +- gcc_jit_type
  43          +- gcc_jit_struct
  44       +- gcc_jit_field
  45       +- gcc_jit_function
  46       +- gcc_jit_block
  47       +- gcc_jit_rvalue
  48           +- gcc_jit_lvalue
  49              +- gcc_jit_param
  50       +- gcc_jit_case
  51       +- gcc_jit_extended_asm
  52
  53 There are casting methods for upcasting from subclasses to parent classes.
  54 For example, :c:func:`gcc_jit_type_as_object`:
  55
  56 .. code-block:: c
  57
  58    gcc_jit_object *obj = gcc_jit_type_as_object (int_type);
  59
  60 The object "base class" has the following operations:
  61
  62 .. function:: gcc_jit_context *gcc_jit_object_get_context (gcc_jit_object *obj)
  63
  64   Which context is "obj" within?
  65
  66
  67 .. function:: const char *gcc_jit_object_get_debug_string (gcc_jit_object *obj)
  68
  69   Generate a human-readable description for the given object.
  70
  71   For example,
  72
  73   .. code-block:: c
  74
  75      printf ("obj: %s\n", gcc_jit_object_get_debug_string (obj));
  76
  77   might give this text on stdout:
  78
  79   .. code-block:: bash
  80
  81      obj: 4.0 * (float)i
  82
  83   .. note::
  84
  85      If you call this on an object, the `const char *` buffer is allocated
  86      and generated on the first call for that object, and the buffer will
  87      have the same lifetime as the object  i.e. it will exist until the
  88      object's context is released.