Data.LLVM.IR.Builders.Control

Definitions

functionDef : String -> {default emptySymbolInfo _ : SymbolInfo} -> {default Nothing _ : Maybe CallingConvention} -> {default [] _ : List Attribute} -> LType -> List FunctionArgSpec -> {default Nothing _ : Maybe AddressInfo} -> {default Nothing _ : Maybe AddressSpace} -> {default [] _ : List Attribute} -> {default Nothing _ : Maybe String} -> {default Nothing _ : Maybe String} -> {default Nothing _ : Maybe Name} -> {default Nothing _ : Maybe Int} -> {default Nothing _ : Maybe String} -> {default Nothing _ : Maybe LExpr} -> {default Nothing _ : Maybe LExpr} -> {default Nothing _ : Maybe LExpr} -> {default [] _ : List Metadata} -> List Block -> {default [] _ : List LTag} -> FunctionDef

  Create a function definition with comprehensive configuration options.
  
  Builds a complete function definition with all possible LLVM function attributes
  and metadata. Most parameters have sensible defaults to reduce verbosity.
  
  @ name The function name (identifier)
  @ symbolInfo Symbol information including linkage, preemption, visibility, and storage
  @ callingConvention The calling convention (C, FastCC, etc.)
  @ returnAttrs Attributes applied to the return value
  @ retType The return type of the function
  @ args List of function argument specifications with types and attributes
  @ addressInfo Address information for the function
  @ addressSpace Address space where the function resides
  @ fnAttributes Function-level attributes (noinline, readonly, etc.)
  @ section Optional section name for the function
  @ partition Optional partition name for the function
  @ comdat Optional COMDAT group name
  @ alignment Optional function alignment requirement
  @ gc Optional garbage collector specification
  @ fprefix Optional function prefix constant
  @ prologue Optional prologue constant
  @ personality Optional personality function for exception handling
  @ metadata List of metadata attached to the function
  @ body The function body containing statements
  @ tags Additional tags for the function

Visibility: export

functionDec : String -> {default emptySymbolInfo _ : SymbolInfo} -> {default Nothing _ : Maybe CallingConvention} -> {default [] _ : List Attribute} -> LType -> List FunctionArgSpec -> {default Nothing _ : Maybe AddressInfo} -> {default Nothing _ : Maybe Int} -> {default Nothing _ : Maybe String} -> {default Nothing _ : Maybe LExpr} -> {default Nothing _ : Maybe LExpr} -> {default [] _ : List LTag} -> FunctionDec

  Create a function declaration (forward declaration without body).
  
  Creates a function declaration that specifies the function signature
  without providing an implementation. Used for external functions
  or forward declarations.
  
  @ name The function name (identifier)
  @ symbolInfo Symbol information including linkage, preemption, visibility, and storage
  @ callingConvention The calling convention (C, FastCC, etc.)
  @ returnAttrs Attributes applied to the return value
  @ retType The return type of the function
  @ args List of function argument specifications with types and attributes
  @ addressInfo Address information for the function
  @ alignment Optional function alignment requirement
  @ gc Optional garbage collector specification
  @ fprefix Optional function prefix constant
  @ prologue Optional prologue constant
  @ tags Additional tags for the function

Visibility: export

ret : LType -> LExpr -> LStatement

  Create a return statement.
  
  Creates a return statement that returns a typed value from the current
  function. The return type must match the function's declared return type.
  
  @ ty The type of the value being returned
  @ expr The expression representing the value to return

Visibility: export

retVoid : LStatement

  Create a void return statement.
  
  Creates a return statement for functions with void return type.
  This terminates the function without returning a value.

Visibility: export

condBr : LExpr -> LExpr -> LExpr -> LStatement

  Create a conditional branch statement.
  
  Creates a conditional branch that jumps to one of two labels based
  on a boolean condition. This is the primary way to implement if-then-else
  control flow in LLVM IR.
  
  @ cond Boolean expression to test (must be i1 type)
  @ trueLabel Expression representing the label to jump to if condition is true
  @ falseLabel Expression representing the label to jump to if condition is false

Visibility: export

br : LExpr -> LStatement

  Create an unconditional branch statement.
  
  Creates an unconditional jump to a target label. This is used
  to implement simple control flow transfers like goto statements.
  
  @ target Expression representing the label to jump to

Visibility: export

indirectBr : LExpr -> List LExpr -> LStatement

  Create an indirect branch through computed address.
  
  Creates an indirect branch instruction that jumps to an address computed
  at runtime. The address expression must evaluate to a valid label address,
  and possible destinations must be provided for analysis.
  
  @ address Expression that computes the target address at runtime
  @ possibleDests List of possible destination labels for static analysis

Visibility: export

invoke : InvokeCall -> LStatement

  Create an invoke instruction (function call with exception handling).
  
  Creates an invoke instruction that calls a function with exception handling
  support. If the function throws an exception, control transfers to the
  unwind label; otherwise, it continues to the normal label.
  
  @ call The invoke call specification with function, arguments, and labels

Visibility: export

unreachable : LStatement

  Create an unreachable instruction.
  
  Creates an unreachable instruction indicating that this point in the code
  should never be reached during execution. This is used for optimization
  and to indicate impossible code paths.

Visibility: export

alloca : LType -> {default Nothing _ : Maybe (WithType Nat)} -> {default Nothing _ : Maybe Nat} -> {default Nothing _ : Maybe AddressSpace} -> LOperation

  Create an alloca (stack allocation) operation.
  
  Creates a stack allocation instruction that allocates memory on the
  function's stack frame. The memory is automatically deallocated when
  the function returns.
  
  @ ty The type of objects to allocate
  @ count Optional number of objects to allocate (defaults to single object)
  @ align Optional alignment requirement for the allocation
  @ addrSpace Optional address space for the allocation

Visibility: export

load : {default False _ : Bool} -> LType -> LExpr -> {default Nothing _ : Maybe Nat} -> LOperation

  Create a simple load operation.
  
  Creates a load instruction that reads a value from memory. The pointer
  must point to a valid memory location containing a value of the specified type.
  
  @ volatile Whether this is a volatile load (prevents optimization)
  @ ty The type of the value to load from memory
  @ ptr Expression representing the pointer to load from
  @ align Optional alignment requirement for the load

Visibility: export

store : {default False _ : Bool} -> WithType LExpr -> LExpr -> {default Nothing _ : Maybe Nat} -> LOperation

  Create a simple store operation.
  
  Creates a store instruction that writes a typed value to memory at the
  specified pointer location. The pointer must be valid and properly aligned.
  
  @ volatile Whether this is a volatile store (prevents optimization)
  @ value The typed value to store in memory
  @ ptr Expression representing the pointer to store to
  @ align Optional alignment requirement for the store

Visibility: export

loadAtomic : {default False _ : Bool} -> LType -> LExpr -> {default Nothing _ : Maybe String} -> {default Nothing _ : Maybe AtomicOrder} -> {default Nothing _ : Maybe Nat} -> LOperation

  Create an atomic load operation.

Visibility: export

storeAtomic : {default False _ : Bool} -> WithType LExpr -> LExpr -> {default Nothing _ : Maybe String} -> {default Nothing _ : Maybe AtomicOrder} -> {default Nothing _ : Maybe Nat} -> LOperation

  Create an atomic store operation.

Visibility: export

mkSwitch : LType -> LExpr -> Name -> List CaseBranch -> LOperation

  Create a switch statement with default case and branches.
  
  Creates a switch statement that transfers control based on the value
  of an expression. The expression is compared against each case value,
  and control transfers to the corresponding label.
  
  @ ty The type of the switch expression and case values
  @ value The expression to switch on
  @ defaultLabel The label to jump to if no cases match
  @ cases List of case branches with values and target labels

Visibility: export

caseBranch : LType -> LExpr -> Label -> CaseBranch

  Create a case branch for switch statements.
  
  Defines a single case in a switch statement, mapping a value of a specific
  type to a target label. The value is compared against the switch expression,
  and if they match, control transfers to the specified label.
  
  @ tpe The type of the case value (must match switch expression type)
  @ value The constant value to match against
  @ label The target label to jump to when this case matches

Visibility: export

functionArg : LType -> {default [] _ : List Attribute} -> {default Nothing _ : Maybe String} -> FunctionArgSpec

  Create a function argument specification with optional attributes and name.
  
  Creates a function argument specification that includes type information,
  optional parameter attributes, and an optional parameter name for
  better readability and debugging.
  
  @ ty The type of the function parameter
  @ attrs Optional attributes applied to this parameter (e.g., noalias, readonly)
  @ name Optional name for the parameter (for readability)

Visibility: export

fnCall : {default NoTail _ : TailCall} -> {default [] _ : FastMath} -> {default Nothing _ : Maybe CallingConvention} -> {default [] _ : List Attribute} -> {default Nothing _ : Maybe AddressSpace} -> LType -> LExpr -> List (WithType LExpr) -> {default [] _ : List Attribute} -> FnCall

  Create a function call with configurable options.
  
  Creates a comprehensive function call specification with all possible
  call-site attributes and options. Most parameters have sensible defaults
  to simplify common use cases.
  
  @ tail Tail call optimization specification (NoTail by default)
  @ fastMath Fast math optimization flags for floating point operations
  @ cc Calling convention override for this specific call
  @ returnAttrs Attributes applied to the return value
  @ addressSpace Address space for the function call
  @ tpe The return type of the function call
  @ fnval Expression representing the function to call
  @ args List of typed arguments to pass to the function
  @ fnAttrs Additional function attributes for this call

Visibility: export

simpleFnCall : LType -> LExpr -> List (WithType LExpr) -> FnCall

  Create a simple function call with minimal arguments.
  
  Creates a basic function call without advanced options, using default
  values for tail call optimization, calling convention, and attributes.
  This is the most common way to create function calls.
  
  @ tpe The return type of the function call
  @ fnval Expression representing the function to call
  @ args List of typed arguments to pass to the function

Visibility: export

call : FnCall -> LOperation

  Create a function call operation.

Visibility: export

simpleCall : LType -> LExpr -> List (WithType LExpr) -> LOperation

  Create a simple function call operation.

Visibility: export

insertElement : WithType LExpr -> WithType LExpr -> WithType LExpr -> LOperation

  Create an insert element operation.
  
  Creates an operation that inserts a scalar element into a vector at the
  specified index position. The vector type and element type must be compatible.
  
  @ vector The typed source vector to insert into
  @ element The typed scalar element to insert
  @ index The typed index expression specifying the insertion position

Visibility: export

extractElement : WithType LExpr -> WithType LExpr -> LOperation

  Create an extract element operation.
  
  Creates an operation that extracts a scalar element from a vector at the
  specified index position. The index must be within the vector bounds.
  
  @ vector The typed source vector to extract from
  @ index The typed index expression specifying the extraction position

Visibility: export

shuffleVector : WithType LExpr -> WithType LExpr -> WithType LExpr -> LOperation

  Create a shuffle vector operation.
  
  Creates an operation that shuffles elements from two input vectors according
  to a mask vector. The mask specifies which elements from which input vectors
  to include in the result.
  
  @ vec1 The first typed input vector
  @ vec2 The second typed input vector
  @ mask The typed mask vector specifying the shuffle pattern

Visibility: export

extractValue : WithType LExpr -> Nat -> LOperation

  Create an extract value operation.
  
  Creates an operation that extracts a value from an aggregate type (struct or array)
  at the specified index. The index must be a compile-time constant and within bounds.
  
  @ aggregate The typed aggregate value to extract from
  @ index The constant index specifying which field/element to extract

Visibility: export

insertValue : WithType LExpr -> WithType LExpr -> Nat -> LOperation

  Create an insert value operation.
  
  Creates an operation that inserts a value into an aggregate type (struct or array)
  at the specified index, returning a new aggregate with the updated value.
  
  @ aggregate The typed aggregate value to insert into
  @ element The typed value to insert
  @ index The constant index specifying where to insert the value

Visibility: export

phi : LType -> List (LExpr, Label) -> LOperation

  Create a PHI node.
  
  Creates a PHI node for SSA form that selects a value based on which
  basic block was the predecessor. Essential for control flow merging
  in SSA form where multiple execution paths converge.
  
  @ ty The type of all the incoming values (must be the same)
  @ incomingValues List of (value, label) pairs for each predecessor block

Visibility: export

select : {default [] _ : FastMath} -> WithType LExpr -> WithType LExpr -> WithType LExpr -> LOperation

  Create a select operation.
  
  Creates a conditional select operation that chooses between two values
  based on a boolean condition. This is similar to the ternary operator
  in many languages (condition ? trueValue : falseValue).
  
  @ fastMath Optional fast math flags for floating point operations
  @ condition The typed boolean condition to test
  @ trueValue The typed value to select if condition is true
  @ falseValue The typed value to select if condition is false

Visibility: export

freeze : WithType LExpr -> LOperation

  Create a freeze operation.
  
  Creates a freeze operation that converts poison values to arbitrary
  but fixed values. This is used to prevent undefined behavior propagation
  in LLVM IR optimization.
  
  @ value The typed value to freeze

Visibility: export

invokeCall : {default Nothing _ : Maybe CallingConvention} -> {default [] _ : List Attribute} -> {default Nothing _ : Maybe AddressSpace} -> LType -> LExpr -> List LExpr -> Label -> Label -> InvokeCall

  Create an invoke call with configurable options.
  
  Creates an invoke call specification for exception-handling function calls.
  The invoke instruction calls a function and provides both a normal return
  label and an exception unwind label for proper exception handling.
  
  @ cc Optional calling convention override for this call
  @ returnAttrs Attributes applied to the return value
  @ addressSpace Optional address space for the call
  @ tpe The return type of the function being invoked
  @ fnval Expression representing the function to invoke
  @ args List of arguments to pass to the function
  @ normal Label to continue to on normal return
  @ unwind Label to unwind to on exception

Visibility: export

resume : LType -> LExpr -> LStatement

  Create a resume instruction for exception propagation.

Visibility: export

catchRet : LExpr -> Label -> LStatement

  Create a catch return instruction.

Visibility: export

cleanupRetCaller : LExpr -> LStatement

  Create a cleanup return to caller.

Visibility: export

cleanupRet : LExpr -> Label -> LStatement

  Create a cleanup return to specific label.

Visibility: export

callBR : BrCall -> LStatement

  Create a call branch instruction.

Visibility: export

landingPad : LType -> List CatchClause -> LOperation

  Create a landing pad instruction.

Visibility: export

landingPadCleanup : LType -> List CatchClause -> LOperation

  Create a landing pad with cleanup.

Visibility: export

catchPad : Name -> LExpr -> LOperation

  Create a catch pad instruction.

Visibility: export

cleanupPad : Name -> LExpr -> LOperation

  Create a cleanup pad instruction.

Visibility: export

catching : LType -> LExpr -> CatchClause

  Create a catch clause.

Visibility: export

filtering : LType -> LExpr -> CatchClause

  Create a filter clause.

Visibility: export

catchSwitch : Name -> Maybe Label -> List Label -> Maybe Label -> LStatement

  Create a catch switch instruction.

Visibility: export

brCall : {default Nothing _ : Maybe CallingConvention} -> {default [] _ : List Attribute} -> {default Nothing _ : Maybe AddressSpace} -> LType -> LExpr -> List LExpr -> Label -> List Label -> BrCall

  Create a call branch instruction call specification.

Visibility: export

fence : {default Nothing _ : Maybe String} -> {default Nothing _ : Maybe AtomicOrder} -> LOperation

  Create a fence operation.

Visibility: export