3.1.2 Tutorial part 2: Creating a trivial machine code function ¶

Consider this C function:

int square (int i)
{
  return i * i;
}

How can we construct this at run-time using libgccjit’s C++ API?

First we need to include the relevant header:

#include <libgccjit++.h>

All state associated with compilation is associated with a gccjit;;context, which is a thin C++ wrapper around the C API’s gcc_jit_context *.

Create one using gccjit;;context;;acquire():

gccjit::context ctxt;
ctxt = gccjit::context::acquire ();

The JIT library has a system of types. It is statically-typed: every expression is of a specific type, fixed at compile-time. In our example, all of the expressions are of the C int type, so let’s obtain this from the context, as a gccjit;;type, using gccjit;;context;;get_type():

gccjit::type int_type = ctxt.get_type (GCC_JIT_TYPE_INT);

gccjit;;type is an example of a “contextual” object: every entity in the API is associated with a gccjit;;context.

Memory management is easy: all such “contextual” objects are automatically cleaned up for you when the context is released, using gccjit;;context;;release():

ctxt.release ();

so you don’t need to manually track and cleanup all objects, just the contexts.

All of the C++ classes in the API are thin wrappers around pointers to types in the C API.

The C++ class hierarchy within the gccjit namespace looks like this:

+- object
    +- location
    +- type
       +- struct
    +- field
    +- function
    +- block
    +- rvalue
        +- lvalue
           +- param

One thing you can do with a gccjit;;object is to ask it for a human-readable description as a std::string, using gccjit;;object;;get_debug_string():

printf ("obj: %s\n", obj.get_debug_string ().c_str ());

giving this text on stdout:

obj: int

This is invaluable when debugging.

Let’s create the function. To do so, we first need to construct its single parameter, specifying its type and giving it a name, using gccjit;;context;;new_param():

gccjit::param param_i = ctxt.new_param (int_type, "i");

and we can then make a vector of all of the params of the function, in this case just one:

std::vector<gccjit::param> params;
params.push_back (param_i);

Now we can create the function, using gccjit::context::new_function():

gccjit::function func =
  ctxt.new_function (GCC_JIT_FUNCTION_EXPORTED,
                     int_type,
                     "square",
                     params,
                     0);

To define the code within the function, we must create basic blocks containing statements.

Every basic block contains a list of statements, eventually terminated by a statement that either returns, or jumps to another basic block.

Our function has no control-flow, so we just need one basic block:

gccjit::block block = func.new_block ();

Our basic block is relatively simple: it immediately terminates by returning the value of an expression.

We can build the expression using gccjit;;context;;new_binary_op():

gccjit::rvalue expr =
  ctxt.new_binary_op (
    GCC_JIT_BINARY_OP_MULT, int_type,
    param_i, param_i);

A gccjit;;rvalue is another example of a gccjit;;object subclass. As before, we can print it with gccjit;;object;;get_debug_string().

printf ("expr: %s\n", expr.get_debug_string ().c_str ());

giving this output:

expr: i * i

Note that gccjit;;rvalue provides numerous overloaded operators which can be used to dramatically reduce the amount of typing needed. We can build the above binary operation more directly with this one-liner:

gccjit::rvalue expr = param_i * param_i;

Creating the expression in itself doesn’t do anything; we have to add this expression to a statement within the block. In this case, we use it to build a return statement, which terminates the basic block:

block.end_with_return (expr);

OK, we’ve populated the context. We can now compile it using gccjit;;context;;compile():

gcc_jit_result *result;
result = ctxt.compile ();

and get a gcc_jit_result *.

We can now use gcc_jit_result_get_code() to look up a specific machine code routine within the result, in this case, the function we created above.

void *fn_ptr = gcc_jit_result_get_code (result, "square");
if (!fn_ptr)
  {
    fprintf (stderr, "NULL fn_ptr");
    goto error;
  }

We can now cast the pointer to an appropriate function pointer type, and then call it:

typedef int (*fn_type) (int);
fn_type square = (fn_type)fn_ptr;
printf ("result: %d", square (5));

result: 25

• Options
• Full example