Debian Codegraph @

gcc/jit/docs/topics/expressions.rst

raw
1 .. Copyright (C) 2014-2022 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <[email protected]>
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 :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 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 .. type:: 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 .. type:: 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 .. type:: 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 .. type:: 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 .. type:: 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``).