gcc/jit/docs/topics/expressions.rst

   1 .. Copyright (C) 2014-2016 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 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 :c:type:`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 :c:type:`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 :c:type:`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 Unary Operations
 130 ****************
 131
 132 .. function:: gcc_jit_rvalue * \
 133               gcc_jit_context_new_unary_op (gcc_jit_context *ctxt, \
 134                                             gcc_jit_location *loc, \
 135                                             enum gcc_jit_unary_op op, \
 136                                             gcc_jit_type *result_type, \
 137                                             gcc_jit_rvalue *rvalue)
 138
 139    Build a unary operation out of an input rvalue.
 140
 141 .. type:: enum gcc_jit_unary_op
 142
 143 The available unary operations are:
 144
 145 ==========================================  ============
 146 Unary Operation                             C equivalent
 147 ==========================================  ============
 148 :c:macro:`GCC_JIT_UNARY_OP_MINUS`           `-(EXPR)`
 149 :c:macro:`GCC_JIT_UNARY_OP_BITWISE_NEGATE`  `~(EXPR)`
 150 :c:macro:`GCC_JIT_UNARY_OP_LOGICAL_NEGATE`  `!(EXPR)`
 151 :c:macro:`GCC_JIT_UNARY_OP_ABS`             `abs (EXPR)`
 152 ==========================================  ============
 153
 154 .. c:macro:: GCC_JIT_UNARY_OP_MINUS
 155
 156     Negate an arithmetic value; analogous to:
 157
 158     .. code-block:: c
 159
 160        -(EXPR)
 161
 162     in C.
 163
 164 .. c:macro:: GCC_JIT_UNARY_OP_BITWISE_NEGATE
 165
 166     Bitwise negation of an integer value (one's complement); analogous
 167     to:
 168
 169     .. code-block:: c
 170
 171        ~(EXPR)
 172
 173     in C.
 174
 175 .. c:macro:: GCC_JIT_UNARY_OP_LOGICAL_NEGATE
 176
 177     Logical negation of an arithmetic or pointer value; analogous to:
 178
 179     .. code-block:: c
 180
 181        !(EXPR)
 182
 183     in C.
 184
 185 .. c:macro:: GCC_JIT_UNARY_OP_ABS
 186
 187     Absolute value of an arithmetic expression; analogous to:
 188
 189     .. code-block:: c
 190
 191         abs (EXPR)
 192
 193     in C.
 194
 195 Binary Operations
 196 *****************
 197
 198 .. function:: gcc_jit_rvalue *gcc_jit_context_new_binary_op (gcc_jit_context *ctxt, \
 199                                                              gcc_jit_location *loc, \
 200                                                              enum gcc_jit_binary_op op, \
 201                                                              gcc_jit_type *result_type, \
 202                                                              gcc_jit_rvalue *a, gcc_jit_rvalue *b)
 203
 204    Build a binary operation out of two constituent rvalues.
 205
 206 .. type:: enum gcc_jit_binary_op
 207
 208 The available binary operations are:
 209
 210 ========================================  ============
 211 Binary Operation                          C equivalent
 212 ========================================  ============
 213 :c:macro:`GCC_JIT_BINARY_OP_PLUS`         `x + y`
 214 :c:macro:`GCC_JIT_BINARY_OP_MINUS`        `x - y`
 215 :c:macro:`GCC_JIT_BINARY_OP_MULT`         `x * y`
 216 :c:macro:`GCC_JIT_BINARY_OP_DIVIDE`       `x / y`
 217 :c:macro:`GCC_JIT_BINARY_OP_MODULO`       `x % y`
 218 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_AND`  `x & y`
 219 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_XOR`  `x ^ y`
 220 :c:macro:`GCC_JIT_BINARY_OP_BITWISE_OR`   `x | y`
 221 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_AND`  `x && y`
 222 :c:macro:`GCC_JIT_BINARY_OP_LOGICAL_OR`   `x || y`
 223 :c:macro:`GCC_JIT_BINARY_OP_LSHIFT`       `x << y`
 224 :c:macro:`GCC_JIT_BINARY_OP_RSHIFT`       `x >> y`
 225 ========================================  ============
 226
 227 .. c:macro:: GCC_JIT_BINARY_OP_PLUS
 228
 229    Addition of arithmetic values; analogous to:
 230
 231    .. code-block:: c
 232
 233      (EXPR_A) + (EXPR_B)
 234
 235    in C.
 236
 237    For pointer addition, use :c:func:`gcc_jit_context_new_array_access`.
 238
 239 .. c:macro:: GCC_JIT_BINARY_OP_MINUS
 240
 241    Subtraction of arithmetic values; analogous to:
 242
 243    .. code-block:: c
 244
 245      (EXPR_A) - (EXPR_B)
 246
 247    in C.
 248
 249 .. c:macro:: GCC_JIT_BINARY_OP_MULT
 250
 251    Multiplication of a pair of arithmetic values; analogous to:
 252
 253    .. code-block:: c
 254
 255      (EXPR_A) * (EXPR_B)
 256
 257    in C.
 258
 259 .. c:macro:: GCC_JIT_BINARY_OP_DIVIDE
 260
 261    Quotient of division of arithmetic values; analogous to:
 262
 263    .. code-block:: c
 264
 265      (EXPR_A) / (EXPR_B)
 266
 267    in C.
 268
 269    The result type affects the kind of division: if the result type is
 270    integer-based, then the result is truncated towards zero, whereas
 271    a floating-point result type indicates floating-point division.
 272
 273 .. c:macro:: GCC_JIT_BINARY_OP_MODULO
 274
 275    Remainder of division of arithmetic values; analogous to:
 276
 277    .. code-block:: c
 278
 279      (EXPR_A) % (EXPR_B)
 280
 281    in C.
 282
 283 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_AND
 284
 285    Bitwise AND; analogous to:
 286
 287    .. code-block:: c
 288
 289      (EXPR_A) & (EXPR_B)
 290
 291    in C.
 292
 293 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_XOR
 294
 295    Bitwise exclusive OR; analogous to:
 296
 297    .. code-block:: c
 298
 299       (EXPR_A) ^ (EXPR_B)
 300
 301    in C.
 302
 303 .. c:macro:: GCC_JIT_BINARY_OP_BITWISE_OR
 304
 305    Bitwise inclusive OR; analogous to:
 306
 307    .. code-block:: c
 308
 309      (EXPR_A) | (EXPR_B)
 310
 311    in C.
 312
 313 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_AND
 314
 315    Logical AND; analogous to:
 316
 317    .. code-block:: c
 318
 319      (EXPR_A) && (EXPR_B)
 320
 321    in C.
 322
 323 .. c:macro:: GCC_JIT_BINARY_OP_LOGICAL_OR
 324
 325    Logical OR; analogous to:
 326
 327    .. code-block:: c
 328
 329      (EXPR_A) || (EXPR_B)
 330
 331    in C.
 332
 333 .. c:macro:: GCC_JIT_BINARY_OP_LSHIFT
 334
 335    Left shift; analogous to:
 336
 337    .. code-block:: c
 338
 339      (EXPR_A) << (EXPR_B)
 340
 341    in C.
 342
 343 .. c:macro:: GCC_JIT_BINARY_OP_RSHIFT
 344
 345    Right shift; analogous to:
 346
 347    .. code-block:: c
 348
 349      (EXPR_A) >> (EXPR_B)
 350
 351    in C.
 352
 353 Comparisons
 354 ***********
 355
 356 .. function:: gcc_jit_rvalue *\
 357               gcc_jit_context_new_comparison (gcc_jit_context *ctxt,\
 358                                               gcc_jit_location *loc,\
 359                                               enum gcc_jit_comparison op,\
 360                                               gcc_jit_rvalue *a, gcc_jit_rvalue *b)
 361
 362    Build a boolean rvalue out of the comparison of two other rvalues.
 363
 364 .. type:: enum gcc_jit_comparison
 365
 366 =======================================  ============
 367 Comparison                               C equivalent
 368 =======================================  ============
 369 :c:macro:`GCC_JIT_COMPARISON_EQ`         `x == y`
 370 :c:macro:`GCC_JIT_COMPARISON_NE`         `x != y`
 371 :c:macro:`GCC_JIT_COMPARISON_LT`         `x < y`
 372 :c:macro:`GCC_JIT_COMPARISON_LE`         `x <= y`
 373 :c:macro:`GCC_JIT_COMPARISON_GT`         `x > y`
 374 :c:macro:`GCC_JIT_COMPARISON_GE`         `x >= y`
 375 =======================================  ============
 376
 377
 378 Function calls
 379 **************
 380 .. function:: gcc_jit_rvalue *\
 381               gcc_jit_context_new_call (gcc_jit_context *ctxt,\
 382                                         gcc_jit_location *loc,\
 383                                         gcc_jit_function *func,\
 384                                         int numargs , gcc_jit_rvalue **args)
 385
 386    Given a function and the given table of argument rvalues, construct a
 387    call to the function, with the result as an rvalue.
 388
 389    .. note::
 390
 391       :c:func:`gcc_jit_context_new_call` merely builds a
 392       :c:type:`gcc_jit_rvalue` i.e. an expression that can be evaluated,
 393       perhaps as part of a more complicated expression.
 394       The call *won't* happen unless you add a statement to a function
 395       that evaluates the expression.
 396
 397       For example, if you want to call a function and discard the result
 398       (or to call a function with ``void`` return type), use
 399       :c:func:`gcc_jit_block_add_eval`:
 400
 401       .. code-block:: c
 402
 403          /* Add "(void)printf (arg0, arg1);".  */
 404          gcc_jit_block_add_eval (
 405            block, NULL,
 406            gcc_jit_context_new_call (
 407              ctxt,
 408              NULL,
 409              printf_func,
 410              2, args));
 411
 412 .. function:: gcc_jit_rvalue *\
 413               gcc_jit_context_new_call_through_ptr (gcc_jit_context *ctxt,\
 414                                                     gcc_jit_location *loc,\
 415                                                     gcc_jit_rvalue *fn_ptr,\
 416                                                     int numargs, \
 417                                                     gcc_jit_rvalue **args)
 418
 419    Given an rvalue of function pointer type, and the given table of
 420    argument rvalues, construct a call to the function pointer, with the
 421    result as an rvalue.
 422
 423    .. note::
 424
 425       The same caveat as for :c:func:`gcc_jit_context_new_call` applies.
 426
 427 .. function:: void\
 428               gcc_jit_rvalue_set_bool_require_tail_call (gcc_jit_rvalue *call,\
 429                                                          int require_tail_call)
 430
 431    Given an :c:type:`gcc_jit_rvalue *` for a call created through
 432    :c:func:`gcc_jit_context_new_call` or
 433    :c:func:`gcc_jit_context_new_call_through_ptr`, mark/clear the
 434    call as needing tail-call optimization.  The optimizer will
 435    attempt to optimize the call into a jump instruction; if it is
 436    unable to do do, an error will be emitted.
 437
 438    This may be useful when implementing functions that use the
 439    continuation-passing style (e.g. for functional programming
 440    languages), in which every function "returns" by calling a
 441    "continuation" function pointer.  This call must be
 442    guaranteed to be implemented as a jump, otherwise the program
 443    could consume an arbitrary amount of stack space as it executed.
 444
 445    This entrypoint was added in :ref:`LIBGCCJIT_ABI_6`; you can test for
 446    its presence using
 447
 448    .. code-block:: c
 449
 450       #ifdef LIBGCCJIT_HAVE_gcc_jit_rvalue_set_bool_require_tail_call
 451
 452 Type-coercion
 453 *************
 454
 455 .. function:: gcc_jit_rvalue *\
 456               gcc_jit_context_new_cast (gcc_jit_context *ctxt,\
 457                                         gcc_jit_location *loc,\
 458                                         gcc_jit_rvalue *rvalue,\
 459                                         gcc_jit_type *type)
 460
 461    Given an rvalue of T, construct another rvalue of another type.
 462
 463    Currently only a limited set of conversions are possible:
 464
 465      * int <-> float
 466      * int <-> bool
 467      * P*  <-> Q*, for pointer types P and Q
 468
 469 Lvalues
 470 -------
 471
 472 .. type:: gcc_jit_lvalue
 473
 474 An lvalue is something that can of the *left*-hand side of an assignment:
 475 a storage area (such as a variable).  It is also usable as an rvalue,
 476 where the rvalue is computed by reading from the storage area.
 477
 478 .. function:: gcc_jit_object *\
 479               gcc_jit_lvalue_as_object (gcc_jit_lvalue *lvalue)
 480
 481    Upcast an lvalue to be an object.
 482
 483 .. function:: gcc_jit_rvalue *\
 484               gcc_jit_lvalue_as_rvalue (gcc_jit_lvalue *lvalue)
 485
 486    Upcast an lvalue to be an rvalue.
 487
 488 .. function:: gcc_jit_rvalue *\
 489               gcc_jit_lvalue_get_address (gcc_jit_lvalue *lvalue,\
 490                                           gcc_jit_location *loc)
 491
 492    Take the address of an lvalue; analogous to:
 493
 494    .. code-block:: c
 495
 496      &(EXPR)
 497
 498    in C.
 499
 500 Global variables
 501 ****************
 502
 503 .. function:: gcc_jit_lvalue *\
 504               gcc_jit_context_new_global (gcc_jit_context *ctxt,\
 505                                           gcc_jit_location *loc,\
 506                                           enum gcc_jit_global_kind kind,\
 507                                           gcc_jit_type *type,\
 508                                           const char *name)
 509
 510    Add a new global variable of the given type and name to the context.
 511
 512    The parameter ``name`` must be non-NULL.  The call takes a copy of the
 513    underlying string, so it is valid to pass in a pointer to an on-stack
 514    buffer.
 515
 516    The "kind" parameter determines the visibility of the "global" outside
 517    of the :c:type:`gcc_jit_result`:
 518
 519    .. type:: enum gcc_jit_global_kind
 520
 521    .. c:macro:: GCC_JIT_GLOBAL_EXPORTED
 522
 523       Global is defined by the client code and is visible
 524       by name outside of this JIT context via
 525       :c:func:`gcc_jit_result_get_global` (and this value is required for
 526       the global to be accessible via that entrypoint).
 527
 528    .. c:macro:: GCC_JIT_GLOBAL_INTERNAL
 529
 530       Global is defined by the client code, but is invisible
 531       outside of it.  Analogous to a "static" global within a .c file.
 532       Specifically, the variable will only be visible within this
 533       context and within child contexts.
 534
 535    .. c:macro:: GCC_JIT_GLOBAL_IMPORTED
 536
 537       Global is not defined by the client code; we're merely
 538       referring to it.  Analogous to using an "extern" global from a
 539       header file.
 540
 541 Working with pointers, structs and unions
 542 -----------------------------------------
 543
 544 .. function:: gcc_jit_lvalue *\
 545               gcc_jit_rvalue_dereference (gcc_jit_rvalue *rvalue,\
 546                                           gcc_jit_location *loc)
 547
 548    Given an rvalue of pointer type ``T *``, dereferencing the pointer,
 549    getting an lvalue of type ``T``.  Analogous to:
 550
 551    .. code-block:: c
 552
 553      *(EXPR)
 554
 555    in C.
 556
 557 Field access is provided separately for both lvalues and rvalues.
 558
 559 .. function:: gcc_jit_lvalue *\
 560               gcc_jit_lvalue_access_field (gcc_jit_lvalue *struct_,\
 561                                            gcc_jit_location *loc,\
 562                                            gcc_jit_field *field)
 563
 564    Given an lvalue of struct or union type, access the given field,
 565    getting an lvalue of the field's type.  Analogous to:
 566
 567    .. code-block:: c
 568
 569       (EXPR).field = ...;
 570
 571    in C.
 572
 573 .. function:: gcc_jit_rvalue *\
 574               gcc_jit_rvalue_access_field (gcc_jit_rvalue *struct_,\
 575                                            gcc_jit_location *loc,\
 576                                            gcc_jit_field *field)
 577
 578    Given an rvalue of struct or union type, access the given field
 579    as an rvalue.  Analogous to:
 580
 581    .. code-block:: c
 582
 583       (EXPR).field
 584
 585    in C.
 586
 587 .. function:: gcc_jit_lvalue *\
 588               gcc_jit_rvalue_dereference_field (gcc_jit_rvalue *ptr,\
 589                                                 gcc_jit_location *loc,\
 590                                                 gcc_jit_field *field)
 591
 592    Given an rvalue of pointer type ``T *`` where T is of struct or union
 593    type, access the given field as an lvalue.  Analogous to:
 594
 595    .. code-block:: c
 596
 597       (EXPR)->field
 598
 599    in C, itself equivalent to ``(*EXPR).FIELD``.
 600
 601 .. function:: gcc_jit_lvalue *\
 602               gcc_jit_context_new_array_access (gcc_jit_context *ctxt,\
 603                                                 gcc_jit_location *loc,\
 604                                                 gcc_jit_rvalue *ptr,\
 605                                                 gcc_jit_rvalue *index)
 606
 607    Given an rvalue of pointer type ``T *``, get at the element `T` at
 608    the given index, using standard C array indexing rules i.e. each
 609    increment of ``index`` corresponds to ``sizeof(T)`` bytes.
 610    Analogous to:
 611
 612    .. code-block:: c
 613
 614       PTR[INDEX]
 615
 616    in C (or, indeed, to ``PTR + INDEX``).