.. Copyright (C) 2014-2023 Free Software Foundation, Inc.
Originally contributed by David Malcolm <dmalcolm@redhat.com>
This is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see
<https://www.gnu.org/licenses/>.
.. default-domain:: cpp
Creating and using functions
============================
Params
------
.. class:: gccjit::param
A `gccjit::param` represents a parameter to a function.
.. function:: gccjit::param \
gccjit::context::new_param (gccjit::type type,\
const char *name, \
gccjit::location loc)
In preparation for creating a function, create a new parameter of the
given type and name.
:class:`gccjit::param` is a subclass of :class:`gccjit::lvalue` (and thus
of :class:`gccjit::rvalue` and :class:`gccjit::object`). It is a thin
wrapper around the C API's :c:expr:`gcc_jit_param *`.
Functions
---------
.. class:: gccjit::function
A `gccjit::function` represents a function - either one that we're
creating ourselves, or one that we're referencing.
.. function:: gccjit::function \
gccjit::context::new_function (enum gcc_jit_function_kind,\
gccjit::type return_type, \
const char *name, \
std::vector<param> ¶ms, \
int is_variadic, \
gccjit::location loc)
Create a gcc_jit_function with the given name and parameters.
Parameters "is_variadic" and "loc" are optional.
This is a wrapper around the C API's :c:func:`gcc_jit_context_new_function`.
.. function:: gccjit::function \
gccjit::context::get_builtin_function (const char *name)
This is a wrapper around the C API's
:c:func:`gcc_jit_context_get_builtin_function`.
.. function:: gccjit::param \
gccjit::function::get_param (int index) const
Get the param of the given index (0-based).
.. function:: void \
gccjit::function::dump_to_dot (const char *path)
Emit the function in graphviz format to the given path.
.. function:: gccjit::lvalue \
gccjit::function::new_local (gccjit::type type,\
const char *name, \
gccjit::location loc)
Create a new local variable within the function, of the given type and
name.
Blocks
------
.. class:: gccjit::block
A `gccjit::block` represents a basic block within a function i.e. a
sequence of statements with a single entry point and a single exit
point.
:class:`gccjit::block` is a subclass of :class:`gccjit::object`.
The first basic block that you create within a function will
be the entrypoint.
Each basic block that you create within a function must be
terminated, either with a conditional, a jump, a return, or
a switch.
It's legal to have multiple basic blocks that return within
one function.
.. function:: gccjit::block \
gccjit::function::new_block (const char *name)
Create a basic block of the given name. The name may be NULL, but
providing meaningful names is often helpful when debugging: it may
show up in dumps of the internal representation, and in error
messages.
Statements
----------
.. function:: void\
gccjit::block::add_eval (gccjit::rvalue rvalue, \
gccjit::location loc)
Add evaluation of an rvalue, discarding the result
(e.g. a function call that "returns" void).
This is equivalent to this C code:
.. code-block:: c
(void)expression;
.. function:: void\
gccjit::block::add_assignment (gccjit::lvalue lvalue, \
gccjit::rvalue rvalue, \
gccjit::location loc)
Add evaluation of an rvalue, assigning the result to the given
lvalue.
This is roughly equivalent to this C code:
.. code-block:: c
lvalue = rvalue;
.. function:: void\
gccjit::block::add_assignment_op (gccjit::lvalue lvalue, \
enum gcc_jit_binary_op, \
gccjit::rvalue rvalue, \
gccjit::location loc)
Add evaluation of an rvalue, using the result to modify an
lvalue.
This is analogous to "+=" and friends:
.. code-block:: c
lvalue += rvalue;
lvalue *= rvalue;
lvalue /= rvalue;
etc. For example:
.. code-block:: c
/* "i++" */
loop_body.add_assignment_op (
i,
GCC_JIT_BINARY_OP_PLUS,
ctxt.one (int_type));
.. function:: void\
gccjit::block::add_comment (const char *text, \
gccjit::location loc)
Add a no-op textual comment to the internal representation of the
code. It will be optimized away, but will be visible in the dumps
seen via :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE`
and :c:macro:`GCC_JIT_BOOL_OPTION_DUMP_INITIAL_GIMPLE`,
and thus may be of use when debugging how your project's internal
representation gets converted to the libgccjit IR.
Parameter "loc" is optional.
.. function:: void\
gccjit::block::end_with_conditional (gccjit::rvalue boolval,\
gccjit::block on_true,\
gccjit::block on_false, \
gccjit::location loc)
Terminate a block by adding evaluation of an rvalue, branching on the
result to the appropriate successor block.
This is roughly equivalent to this C code:
.. code-block:: c
if (boolval)
goto on_true;
else
goto on_false;
block, boolval, on_true, and on_false must be non-NULL.
.. function:: void\
gccjit::block::end_with_jump (gccjit::block target, \
gccjit::location loc)
Terminate a block by adding a jump to the given target block.
This is roughly equivalent to this C code:
.. code-block:: c
goto target;
.. function:: void\
gccjit::block::end_with_return (gccjit::rvalue rvalue, \
gccjit::location loc)
Terminate a block.
Both params are optional.
An rvalue must be provided for a function returning non-void, and
must not be provided by a function "returning" `void`.
If an rvalue is provided, the block is terminated by evaluating the
rvalue and returning the value.
This is roughly equivalent to this C code:
.. code-block:: c
return expression;
If an rvalue is not provided, the block is terminated by adding a
valueless return, for use within a function with "void" return type.
This is equivalent to this C code:
.. code-block:: c
return;
.. class:: gccjit::case_
A `gccjit::case_` represents a case within a switch statement, and
is created within a particular :class:`gccjit::context` using
:func:`gccjit::context::new_case`. It is a subclass of
:class:`gccjit::object`.
Each case expresses a multivalued range of integer values. You
can express single-valued cases by passing in the same value for
both `min_value` and `max_value`.
.. function:: gccjit::case_ *\
gccjit::context::new_case (gccjit::rvalue min_value,\
gccjit::rvalue max_value,\
gccjit::block dest_block)
Create a new gccjit::case for use in a switch statement.
`min_value` and `max_value` must be constants of an integer type,
which must match that of the expression of the switch statement.
`dest_block` must be within the same function as the switch
statement.
.. function:: void\
gccjit::block::end_with_switch (gccjit::rvalue expr,\
gccjit::block default_block,\
std::vector <gccjit::case_> cases,\
gccjit::location loc)
Terminate a block by adding evalation of an rvalue, then performing
a multiway branch.
This is roughly equivalent to this C code:
.. code-block:: c
switch (expr)
{
default:
goto default_block;
case C0.min_value ... C0.max_value:
goto C0.dest_block;
case C1.min_value ... C1.max_value:
goto C1.dest_block;
...etc...
case C[N - 1].min_value ... C[N - 1].max_value:
goto C[N - 1].dest_block;
}
``expr`` must be of the same integer type as all of the ``min_value``
and ``max_value`` within the cases.
The ranges of the cases must not overlap (or have duplicate
values).
The API entrypoints relating to switch statements and cases:
* :func:`gccjit::block::end_with_switch`
* :func:`gccjit::context::new_case`
were added in :ref:`LIBGCCJIT_ABI_3`; you can test for their presence
using
.. code-block:: c
#ifdef LIBGCCJIT_HAVE_SWITCH_STATEMENTS
Here's an example of creating a switch statement:
.. literalinclude:: ../../../../testsuite/jit.dg/test-switch.cc
:start-after: /* Quote from here in docs/cp/topics/functions.rst. */
:end-before: /* Quote up to here in docs/cp/topics/functions.rst. */
:language: c++