Creating and using functions

Params

gcc_jit_param

A gcc_jit_param represents a parameter to a function.

gcc_jit_param * gcc_jit_context_new_param(gcc_jit_context *ctxt, gcc_jit_location *loc, gcc_jit_type *type, const char *name)

In preparation for creating a function, create a new parameter of the given type and name.

Parameters are lvalues, and thus are also rvalues (and objects), so the following upcasts are available:

gcc_jit_lvalue * gcc_jit_param_as_lvalue(gcc_jit_param *param)

Upcasting from param to lvalue.

gcc_jit_rvalue * gcc_jit_param_as_rvalue(gcc_jit_param *param)

Upcasting from param to rvalue.

gcc_jit_object * gcc_jit_param_as_object(gcc_jit_param *param)

Upcasting from param to object.

Functions

gcc_jit_function

A gcc_jit_function represents a function - either one that we’re creating ourselves, or one that we’re referencing.

gcc_jit_function * gcc_jit_context_new_function(gcc_jit_context *ctxt, gcc_jit_location *loc, enum gcc_jit_function_kind kind, gcc_jit_type *return_type, const char *name, int num_params, gcc_jit_param **params, int is_variadic)

Create a gcc_jit_function with the given name and parameters.

enum gcc_jit_function_kind

This enum controls the kind of function created, and has the following values:

GCC_JIT_FUNCTION_EXPORTED

Function is defined by the client code and visible by name outside of the JIT.

GCC_JIT_FUNCTION_INTERNAL

Function is defined by the client code, but is invisible outside of the JIT. Analogous to a “static” function.

GCC_JIT_FUNCTION_IMPORTED

Function is not defined by the client code; we’re merely referring to it. Analogous to using an “extern” function from a header file.

GCC_JIT_FUNCTION_ALWAYS_INLINE

Function is only ever inlined into other functions, and is invisible outside of the JIT.

Analogous to prefixing with inline and adding __attribute__((always_inline))

Inlining will only occur when the optimization level is above 0; when optimization is off, this is essentially the same as GCC_JIT_FUNCTION_INTERNAL.

gcc_jit_function *gcc_jit_context_get_builtin_function(gcc_jit_context *ctxt, const char *name)

gcc_jit_object * gcc_jit_function_as_object(gcc_jit_function *func)

Upcasting from function to object.

gcc_jit_param * gcc_jit_function_get_param(gcc_jit_function *func, int index)

Get the param of the given index (0-based).

void gcc_jit_function_dump_to_dot(gcc_jit_function *func, const char *path)

Emit the function in graphviz format to the given path.

gcc_jit_lvalue * gcc_jit_function_new_local(gcc_jit_function *func, gcc_jit_location *loc, gcc_jit_type *type, const char *name)

Create a new local variable within the function, of the given type and name.

Blocks

gcc_jit_block

A gcc_jit_block represents a basic block within a function i.e. a sequence of statements with a single entry point and a single exit point.

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, or a return.

It’s legal to have multiple basic blocks that return within one function.

gcc_jit_block * gcc_jit_function_new_block(gcc_jit_function *func, 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.

gcc_jit_object * gcc_jit_block_as_object(gcc_jit_block *block)

Upcast from block to object.

gcc_jit_function * gcc_jit_block_get_function(gcc_jit_block *block)

Which function is this block within?

Statements

void gcc_jit_block_add_eval(gcc_jit_block *block, gcc_jit_location *loc, gcc_jit_rvalue *rvalue)

Add evaluation of an rvalue, discarding the result (e.g. a function call that “returns” void).

This is equivalent to this C code:

(void)expression;

void gcc_jit_block_add_assignment(gcc_jit_block *block, gcc_jit_location *loc, gcc_jit_lvalue *lvalue, gcc_jit_rvalue *rvalue)

Add evaluation of an rvalue, assigning the result to the given lvalue.

This is roughly equivalent to this C code:

lvalue = rvalue;

void gcc_jit_block_add_assignment_op(gcc_jit_block *block, gcc_jit_location *loc, gcc_jit_lvalue *lvalue, enum gcc_jit_binary_op op, gcc_jit_rvalue *rvalue)

Add evaluation of an rvalue, using the result to modify an lvalue.

This is analogous to “+=” and friends:

lvalue += rvalue;
lvalue *= rvalue;
lvalue /= rvalue;

etc. For example:

/* "i++" */
gcc_jit_block_add_assignment_op (
  loop_body, NULL,
  i,
  GCC_JIT_BINARY_OP_PLUS,
  gcc_jit_context_one (ctxt, int_type));

void gcc_jit_block_add_comment(gcc_jit_block *block, gcc_jit_location *loc, const char *text)

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 GCC_JIT_BOOL_OPTION_DUMP_INITIAL_TREE and 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.

void gcc_jit_block_end_with_conditional(gcc_jit_block *block, gcc_jit_location *loc, gcc_jit_rvalue *boolval, gcc_jit_block *on_true, gcc_jit_block *on_false)

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:

if (boolval)
  goto on_true;
else
  goto on_false;

block, boolval, on_true, and on_false must be non-NULL.

void gcc_jit_block_end_with_jump(gcc_jit_block *block, gcc_jit_location *loc, gcc_jit_block *target)

Terminate a block by adding a jump to the given target block.

This is roughly equivalent to this C code:

goto target;

void gcc_jit_block_end_with_return(gcc_jit_block *block, gcc_jit_location *loc, gcc_jit_rvalue *rvalue)

Terminate a block by adding evaluation of an rvalue, returning the value.

This is roughly equivalent to this C code:

return expression;

void gcc_jit_block_end_with_void_return(gcc_jit_block *block, gcc_jit_location *loc)

Terminate a block by adding a valueless return, for use within a function with “void” return type.

This is equivalent to this C code:

return;