pub struct FunctionBuilder<'a> {
    pub func: &'a mut Function,
    /* private fields */
}
Expand description

Temporary object used to build a single Cranelift IR Function.

Fields

func: &'a mut Function

The function currently being built. This field is public so the function can be re-borrowed.

Implementations

This module allows you to create a function in Cranelift IR in a straightforward way, hiding all the complexity of its internal representation.

The module is parametrized by one type which is the representation of variables in your origin language. It offers a way to conveniently append instruction to your program flow. You are responsible to split your instruction flow into extended blocks (declared with create_block) whose properties are:

  • branch and jump instructions can only point at the top of extended blocks;
  • the last instruction of each block is a terminator instruction which has no natural successor, and those instructions can only appear at the end of extended blocks.

The parameters of Cranelift IR instructions are Cranelift IR values, which can only be created as results of other Cranelift IR instructions. To be able to create variables redefined multiple times in your program, use the def_var and use_var command, that will maintain the correspondence between your variables and Cranelift IR SSA values.

The first block for which you call switch_to_block will be assumed to be the beginning of the function.

At creation, a FunctionBuilder instance borrows an already allocated Function which it modifies with the information stored in the mutable borrowed FunctionBuilderContext. The function passed in argument should be newly created with Function::with_name_signature(), whereas the FunctionBuilderContext can be kept as is between two function translations.

Errors

The functions below will panic in debug mode whenever you try to modify the Cranelift IR function in a way that violate the coherence of the code. For instance: switching to a new Block when you haven’t filled the current one with a terminator instruction, inserting a return instruction with arguments that don’t match the function’s signature.

Creates a new FunctionBuilder structure that will operate on a Function using a FunctionBuilderContext.

Get the block that this builder is currently at.

Set the source location that should be assigned to all new instructions.

Creates a new Block and returns its reference.

Mark a block as “cold”.

This will try to move it out of the ordinary path of execution when lowered to machine code.

Insert block in the layout after the existing block after.

After the call to this function, new instructions will be inserted into the designated block, in the order they are declared. You must declare the types of the Block arguments you will use here.

When inserting the terminator instruction (which doesn’t have a fallthrough to its immediate successor), the block will be declared filled and it will not be possible to append instructions to it.

Declares that all the predecessors of this block are known.

Function to call with block as soon as the last branch instruction to block has been created. Forgetting to call this method on every block will cause inconsistencies in the produced functions.

Effectively calls seal_block on all unsealed blocks in the function.

It’s more efficient to seal Blocks as soon as possible, during translation, but for frontends where this is impractical to do, this function can be used at the end of translating all blocks to ensure that everything is sealed.

In order to use a variable in a use_var, you need to declare its type with this method.

Returns the Cranelift IR value corresponding to the utilization at the current program position of a previously defined user variable.

Register a new definition of a user variable. The type of the value must be the same as the type registered for the variable.

Set label for Value

This will not do anything unless func.dfg.collect_debug_info is called first.

Creates a jump table in the function, to be used by br_table instructions.

Creates a stack slot in the function, to be used by stack_load, stack_store and stack_addr instructions.

Adds a signature which can later be used to declare an external function import.

Declare an external function import.

Declares a global value accessible to the function.

Declares a heap accessible to the function.

Returns an object with the InstBuilder trait that allows to conveniently append an instruction to the current Block being built.

Make sure that the current block is inserted in the layout.

Returns a FuncCursor pointed at the current position ready for inserting instructions.

This can be used to insert SSA code that doesn’t need to access locals and that doesn’t need to know about FunctionBuilder at all.

Append parameters to the given Block corresponding to the function parameters. This can be used to set up the block parameters for the entry block.

Append parameters to the given Block corresponding to the function return values. This can be used to set up the block parameters for a function exit block.

Declare that translation of the current function is complete. This resets the state of the FunctionBuilder in preparation to be used for another function.

All the functions documented in the previous block are write-only and help you build a valid Cranelift IR functions via multiple debug asserts. However, you might need to improve the performance of your translation perform more complex transformations to your Cranelift IR function. The functions below help you inspect the function you’re creating and modify it in ways that can be unsafe if used incorrectly.

Retrieves all the parameters for a Block currently inferred from the jump instructions inserted that target it and the SSA construction.

Retrieves the signature with reference sigref previously added with import_signature.

Creates a parameter for a specific Block by appending it to the list of already existing parameters.

Note: this function has to be called at the creation of the Block before adding instructions to it, otherwise this could interfere with SSA construction.

Returns the result values of an instruction.

Changes the destination of a jump instruction after creation.

Note: You are responsible for maintaining the coherence with the arguments of other jump instructions.

Returns true if and only if the current Block is sealed and has no predecessors declared.

The entry block of a function is never unreachable.

Returns true if and only if no instructions have been added since the last call to switch_to_block.

Returns true if and only if a terminator instruction has been inserted since the last call to switch_to_block.

Helper functions

Calls libc.memcpy

Copies the size bytes from src to dest, assumes that src + size won’t overlap onto dest. If dest and src overlap, the behavior is undefined. Applications in which dest and src might overlap should use call_memmove instead.

Optimised memcpy or memmove for small copies.

Codegen safety

The following properties must hold to prevent UB:

  • src_align and dest_align are an upper-bound on the alignment of src respectively dest.
  • If non_overlapping is true, then this must be correct.

Calls libc.memset

Writes size bytes of i8 value ch to memory starting at buffer.

Calls libc.memset

Writes size bytes of value ch to memory starting at buffer.

Calls libc.memmove

Copies size bytes from memory starting at source to memory starting at dest. source is always read before writing to dest.

Calls libc.memcmp

Compares size bytes from memory starting at left to memory starting at right. Returns 0 if all n bytes are equal. If the first difference is at offset i, returns a positive integer if ugt(left[i], right[i]) and a negative integer if ult(left[i], right[i]).

Returns a C int, which is currently always types::I32.

Optimised Self::call_memcmp for small copies.

This implements the byte slice comparison int_cc(left[..size], right[..size]).

left_align and right_align are the statically-known alignments of the left and right pointers respectively. These are used to know whether to mark loads as aligned. It’s always fine to pass 1 for these, but passing something higher than the true alignment may trap or otherwise misbehave as described in MemFlags::aligned.

Note that memcmp is a big-endian and unsigned comparison. As such, this panics when called with IntCC::Signed* or IntCC::*Overflow.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.