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