gcc/jit/docs/topics/types.rst

   1 .. Copyright (C) 2014-2017 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 Types
  21 =====
  22
  23 .. c:type:: gcc_jit_type
  24
  25    gcc_jit_type represents a type within the library.
  26
  27 .. function:: gcc_jit_object *gcc_jit_type_as_object (gcc_jit_type *type)
  28
  29    Upcast a type to an object.
  30
  31 Types can be created in several ways:
  32
  33 * fundamental types can be accessed using
  34   :func:`gcc_jit_context_get_type`:
  35
  36   .. code-block:: c
  37
  38       gcc_jit_type *int_type = gcc_jit_context_get_type (GCC_JIT_TYPE_INT);
  39
  40   See :func:`gcc_jit_context_get_type` for the available types.
  41
  42 * derived types can be accessed by using functions such as
  43   :func:`gcc_jit_type_get_pointer` and :func:`gcc_jit_type_get_const`:
  44
  45   .. code-block:: c
  46
  47     gcc_jit_type *const_int_star = gcc_jit_type_get_pointer (gcc_jit_type_get_const (int_type));
  48     gcc_jit_type *int_const_star = gcc_jit_type_get_const (gcc_jit_type_get_pointer (int_type));
  49
  50 * by creating structures (see below).
  51
  52 Standard types
  53 --------------
  54
  55 .. function:: gcc_jit_type *gcc_jit_context_get_type (gcc_jit_context *ctxt, \
  56                                                       enum gcc_jit_types type_)
  57
  58    Access a specific type.  The available types are:
  59
  60    ==========================================  ================================
  61    `enum gcc_jit_types` value                  Meaning
  62    ==========================================  ================================
  63    :c:data:`GCC_JIT_TYPE_VOID`                 C's ``void`` type.
  64    :c:data:`GCC_JIT_TYPE_VOID_PTR`             C's ``void *``.
  65    :c:data:`GCC_JIT_TYPE_BOOL`                 C++'s ``bool`` type; also C99's
  66                                                ``_Bool`` type, aka ``bool`` if
  67                                                using stdbool.h.
  68    :c:data:`GCC_JIT_TYPE_CHAR`                 C's ``char`` (of some signedness)
  69    :c:data:`GCC_JIT_TYPE_SIGNED_CHAR`          C's ``signed char``
  70    :c:data:`GCC_JIT_TYPE_UNSIGNED_CHAR`        C's ``unsigned char``
  71    :c:data:`GCC_JIT_TYPE_SHORT`                C's ``short`` (signed)
  72    :c:data:`GCC_JIT_TYPE_UNSIGNED_SHORT`       C's ``unsigned short``
  73    :c:data:`GCC_JIT_TYPE_INT`                  C's ``int`` (signed)
  74    :c:data:`GCC_JIT_TYPE_UNSIGNED_INT`         C's ``unsigned int``
  75    :c:data:`GCC_JIT_TYPE_LONG`                 C's ``long`` (signed)
  76    :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG`        C's ``unsigned long``
  77    :c:data:`GCC_JIT_TYPE_LONG_LONG`            C99's ``long long`` (signed)
  78    :c:data:`GCC_JIT_TYPE_UNSIGNED_LONG_LONG`   C99's ``unsigned long long``
  79    :c:data:`GCC_JIT_TYPE_FLOAT`
  80    :c:data:`GCC_JIT_TYPE_DOUBLE`
  81    :c:data:`GCC_JIT_TYPE_LONG_DOUBLE`
  82    :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`       C type: ``(const char *)``
  83    :c:data:`GCC_JIT_TYPE_SIZE_T`               C's ``size_t`` type
  84    :c:data:`GCC_JIT_TYPE_FILE_PTR`             C type: ``(FILE *)``
  85    :c:data:`GCC_JIT_TYPE_COMPLEX_FLOAT`        C99's ``_Complex float``
  86    :c:data:`GCC_JIT_TYPE_COMPLEX_DOUBLE`       C99's ``_Complex double``
  87    :c:data:`GCC_JIT_TYPE_COMPLEX_LONG_DOUBLE`  C99's ``_Complex long double``
  88    ==========================================  ================================
  89
  90 .. function:: gcc_jit_type *\
  91               gcc_jit_context_get_int_type (gcc_jit_context *ctxt, \
  92                                             int num_bytes, int is_signed)
  93
  94    Access the integer type of the given size.
  95
  96
  97 Pointers, `const`, and `volatile`
  98 ---------------------------------
  99
 100 .. function::  gcc_jit_type *gcc_jit_type_get_pointer (gcc_jit_type *type)
 101
 102    Given type "T", get type "T*".
 103
 104 .. function::  gcc_jit_type *gcc_jit_type_get_const (gcc_jit_type *type)
 105
 106    Given type "T", get type "const T".
 107
 108 .. function::  gcc_jit_type *gcc_jit_type_get_volatile (gcc_jit_type *type)
 109
 110    Given type "T", get type "volatile T".
 111
 112 .. function::  gcc_jit_type *\
 113                gcc_jit_context_new_array_type (gcc_jit_context *ctxt, \
 114                                                gcc_jit_location *loc, \
 115                                                gcc_jit_type *element_type, \
 116                                                int num_elements)
 117
 118    Given type "T", get type "T[N]" (for a constant N).
 119
 120 .. function::  gcc_jit_type *\
 121                gcc_jit_type_get_aligned (gcc_jit_type *type, \
 122                                          size_t alignment_in_bytes)
 123
 124    Given type "T", get type:
 125
 126    .. code-block:: c
 127
 128       T __attribute__ ((aligned (ALIGNMENT_IN_BYTES)))
 129
 130    The alignment must be a power of two.
 131
 132    This entrypoint was added in :ref:`LIBGCCJIT_ABI_7`; you can test for
 133    its presence using
 134
 135    .. code-block:: c
 136
 137       #ifdef LIBGCCJIT_HAVE_gcc_jit_type_get_aligned
 138
 139
 140 Structures and unions
 141 ---------------------
 142
 143 .. c:type:: gcc_jit_struct
 144
 145 A compound type analagous to a C `struct`.
 146
 147 .. c:type:: gcc_jit_field
 148
 149 A field within a :c:type:`gcc_jit_struct`.
 150
 151 You can model C `struct` types by creating :c:type:`gcc_jit_struct *` and
 152 :c:type:`gcc_jit_field` instances, in either order:
 153
 154 * by creating the fields, then the structure.  For example, to model:
 155
 156   .. code-block:: c
 157
 158     struct coord {double x; double y; };
 159
 160   you could call:
 161
 162   .. code-block:: c
 163
 164     gcc_jit_field *field_x =
 165       gcc_jit_context_new_field (ctxt, NULL, double_type, "x");
 166     gcc_jit_field *field_y =
 167       gcc_jit_context_new_field (ctxt, NULL, double_type, "y");
 168     gcc_jit_field *fields[2] = {field_x, field_y};
 169     gcc_jit_struct *coord =
 170       gcc_jit_context_new_struct_type (ctxt, NULL, "coord", 2, fields);
 171
 172 * by creating the structure, then populating it with fields, typically
 173   to allow modelling self-referential structs such as:
 174
 175   .. code-block:: c
 176
 177     struct node { int m_hash; struct node *m_next; };
 178
 179   like this:
 180
 181   .. code-block:: c
 182
 183     gcc_jit_type *node =
 184       gcc_jit_context_new_opaque_struct (ctxt, NULL, "node");
 185     gcc_jit_type *node_ptr =
 186       gcc_jit_type_get_pointer (node);
 187     gcc_jit_field *field_hash =
 188       gcc_jit_context_new_field (ctxt, NULL, int_type, "m_hash");
 189     gcc_jit_field *field_next =
 190       gcc_jit_context_new_field (ctxt, NULL, node_ptr, "m_next");
 191     gcc_jit_field *fields[2] = {field_hash, field_next};
 192     gcc_jit_struct_set_fields (node, NULL, 2, fields);
 193
 194 .. function:: gcc_jit_field *\
 195               gcc_jit_context_new_field (gcc_jit_context *ctxt,\
 196                                          gcc_jit_location *loc,\
 197                                          gcc_jit_type *type,\
 198                                          const char *name)
 199
 200    Construct a new field, with the given type and name.
 201
 202    The parameter ``name`` must be non-NULL.  The call takes a copy of the
 203    underlying string, so it is valid to pass in a pointer to an on-stack
 204    buffer.
 205
 206 .. function:: gcc_jit_object *\
 207               gcc_jit_field_as_object (gcc_jit_field *field)
 208
 209    Upcast from field to object.
 210
 211 .. function:: gcc_jit_struct *\
 212    gcc_jit_context_new_struct_type (gcc_jit_context *ctxt,\
 213                                     gcc_jit_location *loc,\
 214                                     const char *name,\
 215                                     int num_fields,\
 216                                     gcc_jit_field **fields)
 217
 218      Construct a new struct type, with the given name and fields.
 219
 220      The parameter ``name`` must be non-NULL.  The call takes a copy of
 221      the underlying string, so it is valid to pass in a pointer to an
 222      on-stack buffer.
 223
 224 .. function:: gcc_jit_struct *\
 225               gcc_jit_context_new_opaque_struct (gcc_jit_context *ctxt,\
 226                                                  gcc_jit_location *loc,\
 227                                                  const char *name)
 228
 229      Construct a new struct type, with the given name, but without
 230      specifying the fields.   The fields can be omitted (in which case the
 231      size of the struct is not known), or later specified using
 232      :c:func:`gcc_jit_struct_set_fields`.
 233
 234      The parameter ``name`` must be non-NULL.  The call takes a copy of
 235      the underlying string, so it is valid to pass in a pointer to an
 236      on-stack buffer.
 237
 238 .. function:: gcc_jit_type *\
 239               gcc_jit_struct_as_type (gcc_jit_struct *struct_type)
 240
 241    Upcast from struct to type.
 242
 243 .. function:: void\
 244               gcc_jit_struct_set_fields (gcc_jit_struct *struct_type,\
 245                                          gcc_jit_location *loc,\
 246                                          int num_fields,\
 247                                          gcc_jit_field **fields)
 248
 249    Populate the fields of a formerly-opaque struct type.
 250
 251    This can only be called once on a given struct type.
 252
 253 .. function:: gcc_jit_type *\
 254               gcc_jit_context_new_union_type (gcc_jit_context *ctxt,\
 255                                               gcc_jit_location *loc,\
 256                                               const char *name,\
 257                                               int num_fields,\
 258                                               gcc_jit_field **fields)
 259
 260      Construct a new union type, with the given name and fields.
 261
 262      The parameter ``name`` must be non-NULL.  It is copied, so the input
 263      buffer does not need to outlive the call.
 264
 265      Example of use:
 266
 267      .. literalinclude:: ../../../testsuite/jit.dg/test-accessing-union.c
 268        :start-after: /* Quote from here in docs/topics/types.rst.  */
 269        :end-before: /* Quote up to here in docs/topics/types.rst.  */
 270        :language: c