gcc/jit/docs/topics/expressions.rst

   1 .. Copyright (C) 2014-2022 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 Expressions
  21 ===========
  22
  23 Rvalues
  24 -------
  25 .. type:: gcc_jit_rvalue
  26
  27 A :c:type:`gcc_jit_rvalue` is an expression that can be computed.
  28
  29 It can be simple, e.g.:
  30
  31   * an integer value e.g. `0` or `42`
  32   * a string literal e.g. `"Hello world"`
  33   * a variable e.g. `i`.  These are also lvalues (see below).
  34
  35 or compound e.g.:
  36
  37   * a unary expression e.g. `!cond`
  38   * a binary expression e.g. `(a + b)`
  39   * a function call e.g. `get_distance (&player_ship, &target)`
  40   * etc.
  41
  42 Every rvalue has an associated type, and the API will check to ensure
  43 that types match up correctly (otherwise the context will emit an error).
  44
  45 .. function:: gcc_jit_type *gcc_jit_rvalue_get_type (gcc_jit_rvalue *rvalue)
  46
  47   Get the type of this rvalue.
  48
  49 .. function:: gcc_jit_object *gcc_jit_rvalue_as_object (gcc_jit_rvalue *rvalue)
  50
  51   Upcast the given rvalue to be an object.
  52
  53
  54 Simple expressions
  55 ******************
  56
  57 .. function:: gcc_jit_rvalue *\
  58               gcc_jit_context_new_rvalue_from_int (gcc_jit_context *ctxt, \
  59                                                    gcc_jit_type *numeric_type, \
  60                                                    int value)
  61
  62    Given a numeric type (integer or floating point), build an rvalue for
  63    the given constant :expr:`int` value.
  64
  65 .. function:: gcc_jit_rvalue *\
  66               gcc_jit_context_new_rvalue_from_long (gcc_jit_context *ctxt, \
  67                                                     gcc_jit_type *numeric_type, \
  68                                                     long value)
  69
  70    Given a numeric type (integer or floating point), build an rvalue for
  71    the given constant :expr:`long` value.
  72
  73 .. function::  gcc_jit_rvalue *gcc_jit_context_zero (gcc_jit_context *ctxt, \
  74                                                      gcc_jit_type *numeric_type)
  75
  76    Given a numeric type (integer or floating point), get the rvalue for
  77    zero.  Essentially this is just a shortcut for:
  78
  79    .. code-block:: c
  80
  81       gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 0)
  82
  83 .. function::  gcc_jit_rvalue *gcc_jit_context_one (gcc_jit_context *ctxt, \
  84                                                     gcc_jit_type *numeric_type)
  85
  86    Given a numeric type (integer or floating point), get the rvalue for
  87    one.  Essentially this is just a shortcut for:
  88
  89    .. code-block:: c
  90
  91       gcc_jit_context_new_rvalue_from_int (ctxt, numeric_type, 1)
  92
  93 .. function::  gcc_jit_rvalue *\
  94                gcc_jit_context_new_rvalue_from_double (gcc_jit_context *ctxt, \
  95                                                        gcc_jit_type *numeric_type, \
  96                                                        double value)
  97
  98    Given a numeric type (integer or floating point), build an rvalue for
  99    the given constant :expr:`double` value.
 100
 101 .. function:: gcc_jit_rvalue *\
 102               gcc_jit_context_new_rvalue_from_ptr (gcc_jit_context *ctxt, \
 103                                                    gcc_jit_type *pointer_type, \
 104                                                    void *value)
 105
 106    Given a pointer type, build an rvalue for the given address.
 107
 108 .. function:: gcc_jit_rvalue *gcc_jit_context_null (gcc_jit_context *ctxt, \
 109                                                     gcc_jit_type *pointer_type)
 110
 111    Given a pointer type, build an rvalue for ``NULL``.  Essentially this
 112    is just a shortcut for:
 113
 114    .. code-block:: c
 115
 116       gcc_jit_context_new_rvalue_from_ptr (ctxt, pointer_type, NULL)
 117
 118 .. function:: gcc_jit_rvalue *\
 119               gcc_jit_context_new_string_literal (gcc_jit_context *ctxt, \
 120                                                   const char *value)
 121
 122    Generate an rvalue for the given NIL-terminated string, of type
 123    :c:data:`GCC_JIT_TYPE_CONST_CHAR_PTR`.
 124
 125    The parameter ``value`` must be non-NULL.  The call takes a copy of the
 126    underlying string, so it is valid to pass in a pointer to an on-stack
 127    buffer.
 128
 129 Constructor expressions
 130 ***********************
 131
 132    The following functions make constructors for array, struct and union
 133    types.
 134
 135    The constructor rvalue can be used for assignment to locals.
 136    It can be used to initialize global variables with
 137    :func:`gcc_jit_global_set_initializer_rvalue`. It can also be used as a
 138    temporary value for function calls and return values, but its address
 139    can't be taken.
 140
 141    Note that arrays in libgccjit do not collapse to pointers like in
 142    C. I.e. if an array constructor is used as e.g. a return value, the whole
 143    array would be returned by value - array constructors can be assigned to
 144    array variables.
 145
 146    The constructor can contain nested constructors.
 147
 148    Note that a string literal rvalue can't be used to construct a char array;
 149    the latter needs one rvalue for each char.
 150
 151    These entrypoints were added in :ref:`LIBGCCJIT_ABI_19`; you can test for
 152    their presence using:
 153
 154    .. code-block:: c
 155
 156      #ifdef LIBGCCJIT_HAVE_CTORS
 157
 158 .. function:: gcc_jit_rvalue *\
 159               gcc_jit_context_new_array_constructor (gcc_jit_context *ctxt,\
 160                                                      gcc_jit_location *loc,\
 161                                                      gcc_jit_type *type,\
 162                                                      size_t num_values,\
 163                                                      gcc_jit_rvalue **values)
 164
 165    Create a constructor for an array as an rvalue.
 166
 167    Returns NULL on error. ``values`` are copied and
 168    do not have to outlive the context.
 169
 170    ``type`` specifies what the constructor will build and has to be
 171    an array.
 172
 173    ``num_values`` specifies the number of elements in ``values`` and
 174    it can't have more elements than the array type.
 175
 176    Each value in ``values`` sets the corresponding value in the array.
 177    If the array type itself has more elements than ``values``, the
 178    left-over elements will be zeroed.
 179
 180    Each value in ``values`` need to be the same unqualified type as the
 181    array type's element type.
 182
 183    If ``num_values`` is 0, the ``values`` parameter will be
 184    ignored and zero initialization will be used.
 185
 186    This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
 187    presence using:
 188
 189    .. code-block:: c
 190
 191      #ifdef LIBGCCJIT_HAVE_CTORS
 192
 193 .. function:: gcc_jit_rvalue *\
 194               gcc_jit_context_new_struct_constructor (gcc_jit_context *ctxt,\
 195                                                       gcc_jit_location *loc,\
 196                                                       gcc_jit_type *type,\
 197                                                       size_t num_values,\
 198                                                       gcc_jit_field **fields,\
 199                                                       gcc_jit_rvalue **values)
 200
 201
 202    Create a constructor for a struct as an rvalue.
 203
 204    Returns NULL on error. The two parameter arrays are copied and
 205    do not have to outlive the context.
 206
 207    ``type`` specifies what the constructor will build and has to be
 208    a struct.
 209
 210    ``num_values`` specifies the number of elements in ``values``.
 211
 212    ``fields`` need to have the same length as ``values``, or be NULL.
 213
 214    If ``fields`` is null, the values are applied in definition order.
 215
 216    Otherwise, each field in ``fields`` specifies which field in the struct to
 217    set to the corresponding value in ``values``. ``fields`` and ``values``
 218    are paired by index.
 219
 220    The fields in ``fields`` have to be in definition order, but there
 221    can be gaps. Any field in the struct that is not specified in
 222    ``fields`` will be zeroed.
 223
 224    The fields in ``fields`` need to be the same objects that were used
 225    to create the struct.
 226
 227    Each value has to have have the same unqualified type as the field
 228    it is applied to.
 229
 230    A NULL value element  in ``values`` is a shorthand for zero initialization
 231    of the corresponding field.
 232
 233    If ``num_values`` is 0, the array parameters will be
 234    ignored and zero initialization will be used.
 235
 236    This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
 237    presence using:
 238
 239    .. code-block:: c
 240
 241      #ifdef LIBGCCJIT_HAVE_CTORS
 242
 243 .. function:: gcc_jit_rvalue *\
 244               gcc_jit_context_new_union_constructor (gcc_jit_context *ctxt,\
 245                                                      gcc_jit_location *loc,\
 246                                                      gcc_jit_type *type,\
 247                                                      gcc_jit_field *field,\
 248                                                      gcc_jit_rvalue *value)
 249
 250    Create a constructor for a union as an rvalue.
 251
 252    Returns NULL on error.
 253
 254    ``type`` specifies what the constructor will build and has to be
 255    an union.
 256
 257    ``field`` specifies which field to set. If it is NULL, the first
 258    field in the union will be set.``field`` need to be the same object
 259    that were used to create the union.
 260
 261    ``value`` specifies what value to set the corresponding field to.
 262    If ``value`` is NULL, zero initialization will be used.
 263
 264    Each value has to have have the same unqualified type as the field
 265    it is applied to.
 266
 267    This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
 268    presence using:
 269
 270    .. code-block:: c
 271
 272      #ifdef LIBGCCJIT_HAVE_CTORS
 273
 274 Vector expressions
 275 ******************
 276
 277 .. function:: gcc_jit_rvalue * \
 278               gcc_jit_context_new_rvalue_from_vector (gcc_jit_context *ctxt, \
 279                                                       gcc_jit_location *loc, \
 280                                                       gcc_jit_type *vec_type, \
 281                                                       size_t num_elements, \
 282                                                       gcc_jit_rvalue **elements)
 283
 284    Build a vector rvalue from an array of elements.
 285
 286    "vec_type" should be a vector type, created using
 287    :func:`gcc_jit_type_get_vector`.
 288
 289    "num_elements" should match that of the vector type.
 290
 291    This entrypoint was added in :ref:`LIBGCCJIT_ABI_10`; you can test for
 292    its presence using
 293
 294    .. code-block:: c
 295
 296       #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_rvalue_from_vector
 297
 298 Unary Operations
 299 ****************
 300
 301 .. function:: gcc_jit_rvalue * \
 302               gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, \
 303                                             gcc_jit_location *loc, \
 304                                             enum gcc_jit_unary_op op, \
 305                                             gcc_jit_type *result_type, \
 306                                             gcc_jit_rvalue *rvalue)
 307
 308    Build a unary operation out of an input rvalue.
 309
 310    The parameter ``result_type`` must be a numeric type.
 311
 312 .. enum:: gcc_jit_unary_op
 313
 314 The available unary operations are:
 315
 316 ==========================================  ============
 317 Unary Operation                             C equivalent
 318 ==========================================  ============
 319 :c:macro:`GCC_JIT_UNARY_OP_MINUS`           `-(EXPR)`
 320 :c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE`  `~(EXPR)`
 321 :c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE`  `!(EXPR)`
 322 :c:macro:`GCC_JIT_UNARY_OP_ABS`             `abs (EXPR)`
 323 ==========================================  ============
 324
 325 .. c:macro:: GCC_JIT_UNARY_OP_MINUS
 326
 327     Negate an arithmetic value; analogous to:
 328
 329     .. code-block:: c
 330
 331        -(EXPR)
 332
 333     in C.
 334
 335 .. c:macro:: GCC_JIT_UNARY_OP_BITWISE_NEGATE
 336
 337     Bitwise negation of an integer value (one's complement); analogous
 338     to:
 339
 340     .. code-block:: c
 341
 342        ~(EXPR)
 343
 344     in C.
 345
 346 .. c:macro:: GCC_JIT_UNARY_OP_LOGICAL_NEGATE
 347
 348     Logical negation of an arithmetic or pointer value; analogous to:
 349
 350     .. code-block:: c
 351
 352        !(EXPR)
 353
 354     in C.
 355
 356 .. c:macro:: GCC_JIT_UNARY_OP_ABS
 357
 358     Absolute value of an arithmetic expression; analogous to:
 359
 360     .. code-block:: c
 361
 362         abs (EXPR)
 363
 364     in C.
 365
 366 Binary Operations
 367 *****************
 368
 369 .. function:: gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, \
 370                                                              gcc_jit_location *loc, \
 371                                                              enum gcc_jit_binary_op op, \
 372                                                              gcc_jit_type *result_type, \
 373                                                              gcc_jit_rvalue *a, gcc_jit_rvalue *b)
 374
 375    Build a binary operation out of two constituent rvalues.
 376
 377    The parameter ``result_type`` must be a numeric type.
 378
 379 .. enum:: gcc_jit_binary_op
 380
 381 The available binary operations are:
 382
 383 ========================================  ============
 384 Binary Operation                          C equivalent
 385 ========================================  ============
 386 :c:macro:`GCC_JIT_BINARY_OP_PLUS`         `x + y`
 387 :c:macro:`GCC_JIT_BINARY_OP_MINUS`        `x - y`
 388 :c:macro:`GCC_JIT_BINARY_OP_MULT`         `x * y`
 389 :c:macro:`GCC_JIT_BINARY_OP_DIVIDE`       `x / y`
 390 :c:macro:`GCC_JIT_BINARY_OP_MODULO`       `x % y`
 391 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND`  `x & y`
 392 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR`  `x ^ y`
 393 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR`   `x | y`
 394 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND`  `x && y`
 395 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR`   `x || y`
 396 :c:macro:`GCC_JIT_BINARY_OP_LSHIFT`       `x << y`
 397 :c:macro:`GCC_JIT_BINARY_OP_RSHIFT`       `x >> y`
 398 ========================================  ============
 399
 400 .. c:macro:: GCC_JIT_BINARY_OP_PLUS
 401
 402    Addition of arithmetic values; analogous to:
 403
 404    .. code-block:: c
 405
 406      (EXPR_A) + (EXPR_B)
 407
 408    in C.
 409
 410    For pointer addition, use :c:func:`gcc_jit_context_new_array_access`.
 411
 412 .. c:macro:: GCC_JIT_BINARY_OP_MINUS
 413
 414    Subtraction of arithmetic values; analogous to:
 415
 416    .. code-block:: c
 417
 418      (EXPR_A) - (EXPR_B)
 419
 420    in C.
 421
 422 .. c:macro:: GCC_JIT_BINARY_OP_MULT
 423
 424    Multiplication of a pair of arithmetic values; analogous to:
 425
 426    .. code-block:: c
 427
 428      (EXPR_A) * (EXPR_B)
 429
 430    in C.
 431
 432 .. c:macro:: GCC_JIT_BINARY_OP_DIVIDE
 433
 434    Quotient of division of arithmetic values; analogous to:
 435
 436    .. code-block:: c
 437
 438      (EXPR_A) / (EXPR_B)
 439
 440    in C.
 441
 442    The result type affects the kind of division: if the result type is
 443    integer-based, then the result is truncated towards zero, whereas
 444    a floating-point result type indicates floating-point division.
 445
 446 .. c:macro:: GCC_JIT_BINARY_OP_MODULO
 447
 448    Remainder of division of arithmetic values; analogous to:
 449
 450    .. code-block:: c
 451
 452      (EXPR_A) % (EXPR_B)
 453
 454    in C.
 455
 456 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_AND
 457
 458    Bitwise AND; analogous to:
 459
 460    .. code-block:: c
 461
 462      (EXPR_A) & (EXPR_B)
 463
 464    in C.
 465
 466 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_XOR
 467
 468    Bitwise exclusive OR; analogous to:
 469
 470    .. code-block:: c
 471
 472       (EXPR_A) ^ (EXPR_B)
 473
 474    in C.
 475
 476 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_OR
 477
 478    Bitwise inclusive OR; analogous to:
 479
 480    .. code-block:: c
 481
 482      (EXPR_A) | (EXPR_B)
 483
 484    in C.
 485
 486 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_AND
 487
 488    Logical AND; analogous to:
 489
 490    .. code-block:: c
 491
 492      (EXPR_A) && (EXPR_B)
 493
 494    in C.
 495
 496 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_OR
 497
 498    Logical OR; analogous to:
 499
 500    .. code-block:: c
 501
 502      (EXPR_A) || (EXPR_B)
 503
 504    in C.
 505
 506 .. c:macro:: GCC_JIT_BINARY_OP_LSHIFT
 507
 508    Left shift; analogous to:
 509
 510    .. code-block:: c
 511
 512      (EXPR_A) << (EXPR_B)
 513
 514    in C.
 515
 516 .. c:macro:: GCC_JIT_BINARY_OP_RSHIFT
 517
 518    Right shift; analogous to:
 519
 520    .. code-block:: c
 521
 522      (EXPR_A) >> (EXPR_B)
 523
 524    in C.
 525
 526 Comparisons
 527 ***********
 528
 529 .. function:: gcc_jit_rvalue *\
 530               gcc_jit_context_new_comparison (gcc_jit_context *ctxt,\
 531                                               gcc_jit_location *loc,\
 532                                               enum gcc_jit_comparison op,\
 533                                               gcc_jit_rvalue *a, gcc_jit_rvalue *b)
 534
 535    Build a boolean rvalue out of the comparison of two other rvalues.
 536
 537 .. enum:: gcc_jit_comparison
 538
 539 =======================================  ============
 540 Comparison                               C equivalent
 541 =======================================  ============
 542 :c:macro:`GCC_JIT_COMPARISON_EQ`         `x == y`
 543 :c:macro:`GCC_JIT_COMPARISON_NE`         `x != y`
 544 :c:macro:`GCC_JIT_COMPARISON_LT`         `x < y`
 545 :c:macro:`GCC_JIT_COMPARISON_LE`         `x <= y`
 546 :c:macro:`GCC_JIT_COMPARISON_GT`         `x > y`
 547 :c:macro:`GCC_JIT_COMPARISON_GE`         `x >= y`
 548 =======================================  ============
 549
 550
 551 Function calls
 552 **************
 553 .. function:: gcc_jit_rvalue *\
 554               gcc_jit_context_new_call (gcc_jit_context *ctxt,\
 555                                         gcc_jit_location *loc,\
 556                                         gcc_jit_function *func,\
 557                                         int numargs , gcc_jit_rvalue **args)
 558
 559    Given a function and the given table of argument rvalues, construct a
 560    call to the function, with the result as an rvalue.
 561
 562    .. note::
 563
 564       :c:func:`gcc_jit_context_new_call` merely builds a
 565       :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated,
 566       perhaps as part of a more complicated expression.
 567       The call *won't* happen unless you add a statement to a function
 568       that evaluates the expression.
 569
 570       For example, if you want to call a function and discard the result
 571       (or to call a function with ``void`` return type), use
 572       :c:func:`gcc_jit_block_add_eval`:
 573
 574       .. code-block:: c
 575
 576          /* Add "(void)printf (arg0, arg1);".  */
 577          gcc_jit_block_add_eval (
 578            block, NULL,
 579            gcc_jit_context_new_call (
 580              ctxt,
 581              NULL,
 582              printf_func,
 583              2, args));
 584
 585 .. function:: gcc_jit_rvalue *\
 586               gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,\
 587                                                     gcc_jit_location *loc,\
 588                                                     gcc_jit_rvalue *fn_ptr,\
 589                                                     int numargs, \
 590                                                     gcc_jit_rvalue **args)
 591
 592    Given an rvalue of function pointer type (e.g. from
 593    :c:func:`gcc_jit_context_new_function_ptr_type`), and the given table of
 594    argument rvalues, construct a call to the function pointer, with the
 595    result as an rvalue.
 596
 597    .. note::
 598
 599       The same caveat as for :c:func:`gcc_jit_context_new_call` applies.
 600
 601 .. function:: void\
 602               gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call,\
 603                                                          int require_tail_call)
 604
 605    Given an :c:type:`gcc_jit_rvalue` for a call created through
 606    :c:func:`gcc_jit_context_new_call` or
 607    :c:func:`gcc_jit_context_new_call_through_ptr`, mark/clear the
 608    call as needing tail-call optimization.  The optimizer will
 609    attempt to optimize the call into a jump instruction; if it is
 610    unable to do do, an error will be emitted.
 611
 612    This may be useful when implementing functions that use the
 613    continuation-passing style (e.g. for functional programming
 614    languages), in which every function "returns" by calling a
 615    "continuation" function pointer.  This call must be
 616    guaranteed to be implemented as a jump, otherwise the program
 617    could consume an arbitrary amount of stack space as it executed.
 618
 619    This entrypoint was added in :ref:`LIBGCCJIT_ABI_6`; you can test for
 620    its presence using
 621
 622    .. code-block:: c
 623
 624       #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call
 625
 626 Function pointers
 627 *****************
 628
 629 Function pointers can be obtained:
 630
 631   * from a :c:type:`gcc_jit_function` using
 632     :c:func:`gcc_jit_function_get_address`, or
 633
 634   * from an existing function using
 635     :c:func:`gcc_jit_context_new_rvalue_from_ptr`,
 636     using a function pointer type obtained using
 637     :c:func:`gcc_jit_context_new_function_ptr_type`.
 638
 639 Type-coercion
 640 *************
 641
 642 .. function:: gcc_jit_rvalue *\
 643               gcc_jit_context_new_cast (gcc_jit_context *ctxt,\
 644                                         gcc_jit_location *loc,\
 645                                         gcc_jit_rvalue *rvalue,\
 646                                         gcc_jit_type *type)
 647
 648    Given an rvalue of T, construct another rvalue of another type.
 649
 650    Currently only a limited set of conversions are possible:
 651
 652      * int <-> float
 653      * int <-> bool
 654      * P*  <-> Q*, for pointer types P and Q
 655
 656 .. function:: gcc_jit_rvalue *\
 657               gcc_jit_context_new_bitcast (gcc_jit_context *ctxt,\
 658                                            gcc_jit_location *loc,\
 659                                            gcc_jit_rvalue *rvalue,\
 660                                            gcc_jit_type *type)
 661
 662    Given an rvalue of T, bitcast it to another type, meaning that this will
 663    generate a new rvalue by interpreting the bits of ``rvalue`` to the layout
 664    of ``type``.
 665
 666    The type of rvalue must be the same size as the size of ``type``.
 667
 668    This entrypoint was added in :ref:`LIBGCCJIT_ABI_21`; you can test for
 669    its presence using
 670
 671    .. code-block:: c
 672
 673       #ifdef LIBGCCJIT_HAVE_gcc_jit_context_new_bitcast
 674
 675 Lvalues
 676 -------
 677
 678 .. type:: gcc_jit_lvalue
 679
 680 An lvalue is something that can of the *left*-hand side of an assignment:
 681 a storage area (such as a variable).  It is also usable as an rvalue,
 682 where the rvalue is computed by reading from the storage area.
 683
 684 .. function:: gcc_jit_object *\
 685               gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue)
 686
 687    Upcast an lvalue to be an object.
 688
 689 .. function:: gcc_jit_rvalue *\
 690               gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue)
 691
 692    Upcast an lvalue to be an rvalue.
 693
 694 .. function:: gcc_jit_rvalue *\
 695               gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,\
 696                                           gcc_jit_location *loc)
 697
 698    Take the address of an lvalue; analogous to:
 699
 700    .. code-block:: c
 701
 702      &(EXPR)
 703
 704    in C.
 705
 706 .. function:: void\
 707               gcc_jit_lvalue_set_tls_model (gcc_jit_lvalue *lvalue,\
 708                                             enum gcc_jit_tls_model model)
 709
 710    Make a variable a thread-local variable.
 711
 712    The "model" parameter determines the thread-local storage model of the "lvalue":
 713
 714    .. enum:: gcc_jit_tls_model
 715
 716    .. c:macro:: GCC_JIT_TLS_MODEL_NONE
 717
 718       Don't set the TLS model.
 719
 720    .. c:macro:: GCC_JIT_TLS_MODEL_GLOBAL_DYNAMIC
 721
 722    .. c:macro:: GCC_JIT_TLS_MODEL_LOCAL_DYNAMIC
 723
 724    .. c:macro:: GCC_JIT_TLS_MODEL_INITIAL_EXEC
 725
 726    .. c:macro:: GCC_JIT_TLS_MODEL_LOCAL_EXEC
 727
 728    This is analogous to:
 729
 730    .. code-block:: c
 731
 732      _Thread_local int foo __attribute__ ((tls_model("MODEL")));
 733
 734    in C.
 735
 736    This entrypoint was added in :ref:`LIBGCCJIT_ABI_17`; you can test for
 737    its presence using
 738
 739    .. code-block:: c
 740
 741       #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_tls_model
 742
 743 .. function:: void\
 744               gcc_jit_lvalue_set_link_section (gcc_jit_lvalue *lvalue,\
 745                                                const char *section_name)
 746
 747    Set the link section of a variable.
 748    The parameter ``section_name`` must be non-NULL and must contain the
 749    leading dot. Analogous to:
 750
 751    .. code-block:: c
 752
 753      int variable __attribute__((section(".section")));
 754
 755    in C.
 756
 757    This entrypoint was added in :ref:`LIBGCCJIT_ABI_18`; you can test for
 758    its presence using
 759
 760    .. code-block:: c
 761
 762       #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_link_section
 763
 764 .. function:: void\
 765               gcc_jit_lvalue_set_register_name (gcc_jit_lvalue *lvalue,\
 766                                                 const char *reg_name);
 767
 768    Set the register name of a variable.
 769    The parameter ``reg_name`` must be non-NULL. Analogous to:
 770
 771    .. code-block:: c
 772
 773      register int variable asm ("r12");
 774
 775    in C.
 776
 777    This entrypoint was added in :ref:`LIBGCCJIT_ABI_22`; you can test for
 778    its presence using
 779
 780    .. code-block:: c
 781
 782       #ifdef LIBGCCJIT_HAVE_gcc_jit_lvalue_set_register_name
 783
 784 .. function:: void\
 785               gcc_jit_lvalue_set_alignment (gcc_jit_lvalue *lvalue,\
 786                                             unsigned bytes)
 787
 788    Set the alignment of a variable, in bytes.
 789    Analogous to:
 790
 791    .. code-block:: c
 792
 793      int variable __attribute__((aligned (16)));
 794
 795    in C.
 796
 797    This entrypoint was added in :ref:`LIBGCCJIT_ABI_24`; you can test for
 798    its presence using
 799
 800    .. code-block:: c
 801
 802       #ifdef LIBGCCJIT_HAVE_ALIGNMENT
 803
 804 .. function:: unsigned\
 805               gcc_jit_lvalue_get_alignment (gcc_jit_lvalue *lvalue)
 806
 807    Return the alignment of a variable set by ``gcc_jit_lvalue_set_alignment``.
 808    Return 0 if the alignment was not set. Analogous to:
 809
 810    .. code-block:: c
 811
 812      _Alignof (variable)
 813
 814    in C.
 815
 816    This entrypoint was added in :ref:`LIBGCCJIT_ABI_24`; you can test for
 817    its presence using
 818
 819    .. code-block:: c
 820
 821       #ifdef LIBGCCJIT_HAVE_ALIGNMENT
 822
 823 Global variables
 824 ****************
 825
 826 .. function:: gcc_jit_lvalue *\
 827               gcc_jit_context_new_global (gcc_jit_context *ctxt,\
 828                                           gcc_jit_location *loc,\
 829                                           enum gcc_jit_global_kind kind,\
 830                                           gcc_jit_type *type,\
 831                                           const char *name)
 832
 833    Add a new global variable of the given type and name to the context.
 834
 835    The parameter ``type`` must be non-`void`.
 836
 837    The parameter ``name`` must be non-NULL.  The call takes a copy of the
 838    underlying string, so it is valid to pass in a pointer to an on-stack
 839    buffer.
 840
 841    The "kind" parameter determines the visibility of the "global" outside
 842    of the :c:type:`gcc_jit_result`:
 843
 844    .. enum:: gcc_jit_global_kind
 845
 846    .. c:macro:: GCC_JIT_GLOBAL_EXPORTED
 847
 848       Global is defined by the client code and is visible
 849       by name outside of this JIT context via
 850       :c:func:`gcc_jit_result_get_global` (and this value is required for
 851       the global to be accessible via that entrypoint).
 852
 853    .. c:macro:: GCC_JIT_GLOBAL_INTERNAL
 854
 855       Global is defined by the client code, but is invisible
 856       outside of it.  Analogous to a "static" global within a .c file.
 857       Specifically, the variable will only be visible within this
 858       context and within child contexts.
 859
 860    .. c:macro:: GCC_JIT_GLOBAL_IMPORTED
 861
 862       Global is not defined by the client code; we're merely
 863       referring to it.  Analogous to using an "extern" global from a
 864       header file.
 865
 866 .. function:: gcc_jit_lvalue *\
 867               gcc_jit_global_set_initializer (gcc_jit_lvalue *global,\
 868                                               const void *blob,\
 869                                               size_t num_bytes)
 870
 871    Set an initializer for ``global`` using the memory content pointed
 872    by ``blob`` for ``num_bytes``.  ``global`` must be an array of an
 873    integral type.  Return the global itself.
 874
 875    The parameter ``blob`` must be non-NULL. The call copies the memory
 876    pointed by ``blob`` for ``num_bytes`` bytes, so it is valid to pass
 877    in a pointer to an on-stack buffer.  The content will be stored in
 878    the compilation unit and used as initialization value of the array.
 879
 880    This entrypoint was added in :ref:`LIBGCCJIT_ABI_14`; you can test for
 881    its presence using
 882
 883    .. code-block:: c
 884
 885       #ifdef LIBGCCJIT_HAVE_gcc_jit_global_set_initializer
 886
 887 .. function:: gcc_jit_lvalue *\
 888               gcc_jit_global_set_initializer_rvalue (gcc_jit_lvalue *global,\
 889                                                      gcc_jit_rvalue *init_value)
 890
 891    Set the initial value of a global with an rvalue.
 892
 893    The rvalue needs to be a constant expression, e.g. no function calls.
 894
 895    The global can't have the ``kind`` :c:macro:`GCC_JIT_GLOBAL_IMPORTED`.
 896
 897    As a non-comprehensive example it is OK to do the equivalent of:
 898
 899    .. code-block:: c
 900
 901        int foo = 3 * 2; /* rvalue from gcc_jit_context_new_binary_op.  */
 902        int arr[] = {1,2,3,4}; /* rvalue from gcc_jit_context_new_constructor.  */
 903        int *bar = &arr[2] + 1; /* rvalue from nested "get address" of "array access".  */
 904        const int baz = 3; /* rvalue from gcc_jit_context_rvalue_from_int.  */
 905        int boz = baz; /* rvalue from gcc_jit_lvalue_as_rvalue.  */
 906
 907    Use together with :c:func:`gcc_jit_context_new_struct_constructor`,
 908    :c:func:`gcc_jit_context_new_union_constructor`, :c:func:`gcc_jit_context_new_array_constructor`
 909    to initialize structs, unions and arrays.
 910
 911    On success, returns the ``global`` parameter unchanged. Otherwise, ``NULL``.
 912
 913    This entrypoint was added in :ref:`LIBGCCJIT_ABI_19`; you can test for its
 914    presence using:
 915
 916    .. code-block:: c
 917
 918       #ifdef LIBGCCJIT_HAVE_CTORS
 919
 920 Working with pointers, structs and unions
 921 -----------------------------------------
 922
 923 .. function:: gcc_jit_lvalue *\
 924               gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,\
 925                                           gcc_jit_location *loc)
 926
 927    Given an rvalue of pointer type ``T *``, dereferencing the pointer,
 928    getting an lvalue of type ``T``.  Analogous to:
 929
 930    .. code-block:: c
 931
 932      *(EXPR)
 933
 934    in C.
 935
 936 Field access is provided separately for both lvalues and rvalues.
 937
 938 .. function:: gcc_jit_lvalue *\
 939               gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_,\
 940                                            gcc_jit_location *loc,\
 941                                            gcc_jit_field *field)
 942
 943    Given an lvalue of struct or union type, access the given field,
 944    getting an lvalue of the field's type.  Analogous to:
 945
 946    .. code-block:: c
 947
 948       (EXPR).field = ...;
 949
 950    in C.
 951
 952 .. function:: gcc_jit_rvalue *\
 953               gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_,\
 954                                            gcc_jit_location *loc,\
 955                                            gcc_jit_field *field)
 956
 957    Given an rvalue of struct or union type, access the given field
 958    as an rvalue.  Analogous to:
 959
 960    .. code-block:: c
 961
 962       (EXPR).field
 963
 964    in C.
 965
 966 .. function:: gcc_jit_lvalue *\
 967               gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,\
 968                                                 gcc_jit_location *loc,\
 969                                                 gcc_jit_field *field)
 970
 971    Given an rvalue of pointer type ``T *`` where T is of struct or union
 972    type, access the given field as an lvalue.  Analogous to:
 973
 974    .. code-block:: c
 975
 976       (EXPR)->field
 977
 978    in C, itself equivalent to ``(*EXPR).FIELD``.
 979
 980 .. function:: gcc_jit_lvalue *\
 981               gcc_jit_context_new_array_access (gcc_jit_context *ctxt,\
 982                                                 gcc_jit_location *loc,\
 983                                                 gcc_jit_rvalue *ptr,\
 984                                                 gcc_jit_rvalue *index)
 985
 986    Given an rvalue of pointer type ``T *``, get at the element `T` at
 987    the given index, using standard C array indexing rules i.e. each
 988    increment of ``index`` corresponds to ``sizeof(T)`` bytes.
 989    Analogous to:
 990
 991    .. code-block:: c
 992
 993       PTR[INDEX]
 994
 995    in C (or, indeed, to ``PTR + INDEX``).