Debian Codegraph @

gcc/jit/docs/cp/topics/functions.rst

raw
1 .. Copyright (C) 2014-2025 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:: cpp
19
20 Creating and using functions
21 ============================
22
23 Params
24 ------
25 .. class:: gccjit::param
26
27 A `gccjit::param` represents a parameter to a function.
28
29 .. function:: gccjit::param \
30 gccjit::context::new_param (gccjit::type type,\
31 const char *name, \
32 gccjit::location loc)
33
34 In preparation for creating a function, create a new parameter of the
35 given type and name.
36
37 :class:`gccjit::param` is a subclass of :class:`gccjit::lvalue` (and thus
38 of :class:`gccjit::rvalue` and :class:`gccjit::object`). It is a thin
39 wrapper around the C API's :c:expr:`gcc_jit_param *`.
40
41 Functions
42 ---------
43
44 .. class:: gccjit::function
45
46 A `gccjit::function` represents a function - either one that we're
47 creating ourselves, or one that we're referencing.
48
49 .. function:: gccjit::function \
50 gccjit::context::new_function (enum gcc_jit_function_kind,\
51 gccjit::type return_type, \
52 const char *name, \
53 std::vector<param> &params, \
54 int is_variadic, \
55 gccjit::location loc)
56
57 Create a gcc_jit_function with the given name and parameters.
58
59 Parameters "is_variadic" and "loc" are optional.
60
61 This is a wrapper around the C API's :c:func:`gcc_jit_context_new_function`.
62
63 .. function:: gccjit::function \
64 gccjit::context::get_builtin_function (const char *name)
65
66 This is a wrapper around the C API's
67 :c:func:`gcc_jit_context_get_builtin_function`.
68
69 .. function:: gccjit::param \
70 gccjit::function::get_param (int index) const
71
72 Get the param of the given index (0-based).
73
74 .. function:: void \
75 gccjit::function::dump_to_dot (const char *path)
76
77 Emit the function in graphviz format to the given path.
78
79 .. function:: gccjit::lvalue \
80 gccjit::function::new_local (gccjit::type type,\
81 const char *name, \
82 gccjit::location loc)
83
84 Create a new local variable within the function, of the given type and
85 name.
86
87 Blocks
88 ------
89 .. class:: gccjit::block
90
91 A `gccjit::block` represents a basic block within a function i.e. a
92 sequence of statements with a single entry point and a single exit
93 point.
94
95 :class:`gccjit::block` is a subclass of :class:`gccjit::object`.
96
97 The first basic block that you create within a function will
98 be the entrypoint.
99
100 Each basic block that you create within a function must be
101 terminated, either with a conditional, a jump, a return, or
102 a switch.
103
104 It's legal to have multiple basic blocks that return within
105 one function.
106
107 .. function:: gccjit::block \
108 gccjit::function::new_block (const char *name)
109
110 Create a basic block of the given name. The name may be NULL, but
111 providing meaningful names is often helpful when debugging: it may
112 show up in dumps of the internal representation, and in error
113 messages.
114
115 Statements
116 ----------
117
118 .. function:: void\
119 gccjit::block::add_eval (gccjit::rvalue rvalue, \
120 gccjit::location loc)
121
122 Add evaluation of an rvalue, discarding the result
123 (e.g. a function call that "returns" void).
124
125 This is equivalent to this C code:
126
127 .. code-block:: c
128
129 (void)expression;
130
131 .. function:: void\
132 gccjit::block::add_assignment (gccjit::lvalue lvalue, \
133 gccjit::rvalue rvalue, \
134 gccjit::location loc)
135
136 Add evaluation of an rvalue, assigning the result to the given
137 lvalue.
138
139 This is roughly equivalent to this C code:
140
141 .. code-block:: c
142
143 lvalue = rvalue;
144
145 .. function:: void\
146 gccjit::block::add_assignment_op (gccjit::lvalue lvalue, \
147 enum gcc_jit_binary_op, \
148 gccjit::rvalue rvalue, \
149 gccjit::location loc)
150
151 Add evaluation of an rvalue, using the result to modify an
152 lvalue.
153
154 This is analogous to "+=" and friends:
155
156 .. code-block:: c
157
158 lvalue += rvalue;
159 lvalue *= rvalue;
160 lvalue /= rvalue;
161
162 etc. For example:
163
164 .. code-block:: c
165
166 /* "i++" */
167 loop_body.add_assignment_op (
168 i,
169 GCC_JIT_BINARY_OP_PLUS,
170 ctxt.one (int_type));
171
172 .. function:: void\
173 gccjit::block::add_comment (const char *text, \
174 gccjit::location loc)
175
176 Add a no-op textual comment to the internal representation of the
177 code. It will be optimized away, but will be visible in the dumps
178 seen via :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE`
179 and :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE`,
180 and thus may be of use when debugging how your project's internal
181 representation gets converted to the libgccjit IR.
182
183 Parameter "loc" is optional.
184
185 .. function:: void\
186 gccjit::block::end_with_conditional (gccjit::rvalue boolval,\
187 gccjit::block on_true,\
188 gccjit::block on_false, \
189 gccjit::location loc)
190
191 Terminate a block by adding evaluation of an rvalue, branching on the
192 result to the appropriate successor block.
193
194 This is roughly equivalent to this C code:
195
196 .. code-block:: c
197
198 if (boolval)
199 goto on_true;
200 else
201 goto on_false;
202
203 block, boolval, on_true, and on_false must be non-NULL.
204
205 .. function:: void\
206 gccjit::block::end_with_jump (gccjit::block target, \
207 gccjit::location loc)
208
209 Terminate a block by adding a jump to the given target block.
210
211 This is roughly equivalent to this C code:
212
213 .. code-block:: c
214
215 goto target;
216
217 .. function:: void\
218 gccjit::block::end_with_return (gccjit::rvalue rvalue, \
219 gccjit::location loc)
220
221 Terminate a block.
222
223 Both params are optional.
224
225 An rvalue must be provided for a function returning non-void, and
226 must not be provided by a function "returning" `void`.
227
228 If an rvalue is provided, the block is terminated by evaluating the
229 rvalue and returning the value.
230
231 This is roughly equivalent to this C code:
232
233 .. code-block:: c
234
235 return expression;
236
237 If an rvalue is not provided, the block is terminated by adding a
238 valueless return, for use within a function with "void" return type.
239
240 This is equivalent to this C code:
241
242 .. code-block:: c
243
244 return;
245
246 .. class:: gccjit::case_
247
248 A `gccjit::case_` represents a case within a switch statement, and
249 is created within a particular :class:`gccjit::context` using
250 :func:`gccjit::context::new_case`. It is a subclass of
251 :class:`gccjit::object`.
252
253 Each case expresses a multivalued range of integer values. You
254 can express single-valued cases by passing in the same value for
255 both `min_value` and `max_value`.
256
257 .. function:: gccjit::case_ *\
258 gccjit::context::new_case (gccjit::rvalue min_value,\
259 gccjit::rvalue max_value,\
260 gccjit::block dest_block)
261
262 Create a new gccjit::case for use in a switch statement.
263 `min_value` and `max_value` must be constants of an integer type,
264 which must match that of the expression of the switch statement.
265
266 `dest_block` must be within the same function as the switch
267 statement.
268
269 .. function:: void\
270 gccjit::block::end_with_switch (gccjit::rvalue expr,\
271 gccjit::block default_block,\
272 std::vector <gccjit::case_> cases,\
273 gccjit::location loc)
274
275 Terminate a block by adding evalation of an rvalue, then performing
276 a multiway branch.
277
278 This is roughly equivalent to this C code:
279
280 .. code-block:: c
281
282 switch (expr)
283 {
284 default:
285 goto default_block;
286
287 case C0.min_value ... C0.max_value:
288 goto C0.dest_block;
289
290 case C1.min_value ... C1.max_value:
291 goto C1.dest_block;
292
293 ...etc...
294
295 case C[N - 1].min_value ... C[N - 1].max_value:
296 goto C[N - 1].dest_block;
297 }
298
299 ``expr`` must be of the same integer type as all of the ``min_value``
300 and ``max_value`` within the cases.
301
302 The ranges of the cases must not overlap (or have duplicate
303 values).
304
305 The API entrypoints relating to switch statements and cases:
306
307 * :func:`gccjit::block::end_with_switch`
308
309 * :func:`gccjit::context::new_case`
310
311 were added in :ref:`LIBGCCJIT_ABI_3`; you can test for their presence
312 using
313
314 .. code-block:: c
315
316 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
317
318 Here's an example of creating a switch statement:
319
320 .. literalinclude:: ../../../../testsuite/jit.dg/test-switch.cc
321 :start-after: /* Quote from here in docs/cp/topics/functions.rst. */
322 :end-before: /* Quote up to here in docs/cp/topics/functions.rst. */
323 :language: c++