1 .. Copyright (C) 2014-2016 Free Software Foundation, Inc.
2 Originally contributed by David Malcolm <dmalcolm@redhat.com>
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.
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.
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/>.
18 .. default-domain:: cpp
20 Creating and using functions
21 ============================
25 .. class:: gccjit::param
27 A `gccjit::param` represents a parameter to a function.
29 .. function:: gccjit::param \
30 gccjit::context::new_param (gccjit::type type,\
34 In preparation for creating a function, create a new parameter of the
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:type:`gcc_jit_param *`.
44 .. class:: gccjit::function
46 A `gccjit::function` represents a function - either one that we're
47 creating ourselves, or one that we're referencing.
49 .. function:: gccjit::function \
50 gccjit::context::new_function (enum gcc_jit_function_kind,\
51 gccjit::type return_type, \
53 std::vector<param> ¶ms, \
57 Create a gcc_jit_function with the given name and parameters.
59 Parameters "is_variadic" and "loc" are optional.
61 This is a wrapper around the C API's :c:func:`gcc_jit_context_new_function`.
63 .. function:: gccjit::function \
64 gccjit::context::get_builtin_function (const char *name)
66 This is a wrapper around the C API's
67 :c:func:`gcc_jit_context_get_builtin_function`.
69 .. function:: gccjit::param \
70 gccjit::function::get_param (int index) const
72 Get the param of the given index (0-based).
75 gccjit::function::dump_to_dot (const char *path)
77 Emit the function in graphviz format to the given path.
79 .. function:: gccjit::lvalue \
80 gccjit::function::new_local (gccjit::type type,\
84 Create a new local variable within the function, of the given type and
89 .. class:: gccjit::block
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
95 :class:`gccjit::block` is a subclass of :class:`gccjit::object`.
97 The first basic block that you create within a function will
100 Each basic block that you create within a function must be
101 terminated, either with a conditional, a jump, a return, or
104 It's legal to have multiple basic blocks that return within
107 .. function:: gccjit::block \
108 gccjit::function::new_block (const char *name)
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
119 gccjit::block::add_eval (gccjit::rvalue rvalue, \
120 gccjit::location loc)
122 Add evaluation of an rvalue, discarding the result
123 (e.g. a function call that "returns" void).
125 This is equivalent to this C code:
132 gccjit::block::add_assignment (gccjit::lvalue lvalue, \
133 gccjit::rvalue rvalue, \
134 gccjit::location loc)
136 Add evaluation of an rvalue, assigning the result to the given
139 This is roughly equivalent to this C code:
146 gccjit::block::add_assignment_op (gccjit::lvalue lvalue, \
147 enum gcc_jit_binary_op, \
148 gccjit::rvalue rvalue, \
149 gccjit::location loc)
151 Add evaluation of an rvalue, using the result to modify an
154 This is analogous to "+=" and friends:
167 loop_body.add_assignment_op (
169 GCC_JIT_BINARY_OP_PLUS,
170 ctxt.one (int_type));
173 gccjit::block::add_comment (const char *text, \
174 gccjit::location loc)
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.
183 Parameter "loc" is optional.
186 gccjit::block::end_with_conditional (gccjit::rvalue boolval,\
187 gccjit::block on_true,\
188 gccjit::block on_false, \
189 gccjit::location loc)
191 Terminate a block by adding evaluation of an rvalue, branching on the
192 result to the appropriate successor block.
194 This is roughly equivalent to this C code:
203 block, boolval, on_true, and on_false must be non-NULL.
206 gccjit::block::end_with_jump (gccjit::block target, \
207 gccjit::location loc)
209 Terminate a block by adding a jump to the given target block.
211 This is roughly equivalent to this C code:
218 gccjit::block::end_with_return (gccjit::rvalue rvalue, \
219 gccjit::location loc)
223 Both params are optional.
225 An rvalue must be provided for a function returning non-void, and
226 must not be provided by a function "returning" `void`.
228 If an rvalue is provided, the block is terminated by evaluating the
229 rvalue and returning the value.
231 This is roughly equivalent to this C code:
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.
240 This is equivalent to this C code:
247 gccjit::block::end_with_switch (gccjit::rvalue expr,\
248 gccjit::block default_block,\
249 std::vector <gccjit::case_> cases,\
250 gccjit::location loc)
252 Terminate a block by adding evalation of an rvalue, then performing
255 This is roughly equivalent to this C code:
264 case C0.min_value ... C0.max_value:
267 case C1.min_value ... C1.max_value:
272 case C[N - 1].min_value ... C[N - 1].max_value:
273 goto C[N - 1].dest_block;
276 ``expr`` must be of the same integer type as all of the ``min_value``
277 and ``max_value`` within the cases.
279 The ranges of the cases must not overlap (or have duplicate
282 The API entrypoints relating to switch statements and cases:
284 * :func:`gccjit::block::end_with_switch`
286 * :func:`gccjit::context::new_case`
288 were added in :ref:`LIBGCCJIT_ABI_3`; you can test for their presence
293 #ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
295 .. class:: gccjit::case_
297 A `gccjit::case_` represents a case within a switch statement, and
298 is created within a particular :class:`gccjit::context` using
299 :func:`gccjit::context::new_case`. It is a subclass of
300 :class:`gccjit::object`.
302 Each case expresses a multivalued range of integer values. You
303 can express single-valued cases by passing in the same value for
304 both `min_value` and `max_value`.
306 .. function:: gccjit::case_ *\
307 gccjit::context::new_case (gccjit::rvalue min_value,\
308 gccjit::rvalue max_value,\
309 gccjit::block dest_block)
311 Create a new gccjit::case for use in a switch statement.
312 `min_value` and `max_value` must be constants of an integer type,
313 which must match that of the expression of the switch statement.
315 `dest_block` must be within the same function as the switch
318 Here's an example of creating a switch statement:
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. */