class CanonicalLoopInfo

Declaration

class CanonicalLoopInfo { /* full declaration omitted */ };

Description

Class to represented the control flow structure of an OpenMP canonical loop. The control-flow structure is standardized for easy consumption by directives associated with loops. For instance, the worksharing-loop construct may change this control flow such that each loop iteration is executed on only one thread. The constraints of a canonical loop in brief are: * The number of loop iterations must have been computed before entering the loop. * Has an (unsigned) logical induction variable that starts at zero and increments by one. * The loop's CFG itself has no side-effects. The OpenMP specification itself allows side-effects, but the order in which they happen, including how often or whether at all, is unspecified. We expect that the frontend will emit those side-effect instructions somewhere (e.g. before the loop) such that the CanonicalLoopInfo itself can be side-effect free. Keep in mind that CanonicalLoopInfo is meant to only describe a repeated execution of a loop body that satifies these constraints. It does NOT represent arbitrary SESE regions that happen to contain a loop. Do not use CanonicalLoopInfo for such purposes. The control flow can be described as follows: Preheader | /-> Header | | | Cond--- \ /// | | | | Body | | | | | | < ...> | | | | | \ --Latch | | Exit | After The loop is thought to start at PreheaderIP (at the Preheader's terminator, including) and end at AfterIP (at the After's first instruction, excluding). That is, instructions in the Preheader and After blocks (except the Preheader's terminator) are out of CanonicalLoopInfo's control and may have side-effects. Typically, the Preheader is used to compute the loop's trip count. The instructions from BodyIP (at the Body block's first instruction, excluding) until the Latch are also considered outside CanonicalLoopInfo's control and thus can have side-effects. The body block is the single entry point into the loop body, which may contain arbitrary control flow as long as all control paths eventually branch to the Latch block. TODO: Consider adding another standardized BasicBlock between Body CFG and Latch to guarantee that there is only a single edge to the latch. It would make loop transformations easier to not needing to consider multiple predecessors of the latch (See redirectAllPredecessorsTo) and would give us an equivalant to PreheaderIP, AfterIP and BodyIP for inserting code that executes after each body iteration. There must be no loop-carried dependencies through llvm::Values. This is equivalant to that the Latch has no PHINode and the Header's only PHINode is for the induction variable. All code in Header, Cond, Latch and Exit (plus the terminator of the Preheader) are CanonicalLoopInfo's responsibility and their build-up checked by assertOK(). They are expected to not be modified unless explicitly modifying the CanonicalLoopInfo through a methods that applies a OpenMP loop-associated construct such as applyWorkshareLoop, tileLoops, unrollLoop, etc. These methods usually invalidate the CanonicalLoopInfo and re-use its basic blocks. After invalidation, the CanonicalLoopInfo must not be used anymore as its underlying control flow may not exist anymore. Loop-transformation methods such as tileLoops, collapseLoops and unrollLoop may also return a new CanonicalLoopInfo that can be passed to other loop-associated construct implementing methods. These loop-transforming methods may either create a new CanonicalLoopInfo usually using createLoopSkeleton and invalidate the input CanonicalLoopInfo, or reuse and modify one of the input CanonicalLoopInfo and return it as representing the modified loop. What is done is an implementation detail of transformation-implementing method and callers should always assume that the CanonicalLoopInfo passed to it is invalidated and a new object is returned. Returned CanonicalLoopInfo have the same structure and guarantees as the one created by createCanonicalLoop, such that transforming methods do not have to special case where the CanonicalLoopInfo originated from. Generally, methods consuming CanonicalLoopInfo do not need an OpenMPIRBuilder::InsertPointTy as argument, but use the locations of the CanonicalLoopInfo to insert new or modify existing instructions. Unless documented otherwise, methods consuming CanonicalLoopInfo do not invalidate any InsertPoint that is outside CanonicalLoopInfo's control. Specifically, any InsertPoint in the Preheader, After or Block can still be used after calling such a method. TODO: Provide mechanisms for exception handling and cancellation points. Defined outside OpenMPIRBuilder because nested classes cannot be forward-declared, e.g. to avoid having to include the entire OMPIRBuilder.h.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1664

Member Variables

private llvm::BasicBlock* Header = nullptr
private llvm::BasicBlock* Cond = nullptr
private llvm::BasicBlock* Latch = nullptr
private llvm::BasicBlock* Exit = nullptr

Method Overview

Methods

void assertOK() const

Description

Consistency self-check.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1814

void collectControlBlocks(
    SmallVectorImpl<llvm::BasicBlock*>& BBs)

Description

Add the control blocks of this loop to \p BBs. This does not include any block from the body, including the one returned by getBody(). FIXME: This currently includes the Preheader and After blocks even though their content is (mostly) not under CanonicalLoopInfo's control. Re-evaluated whether this makes sense.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1681

Parameters

SmallVectorImpl<llvm::BasicBlock*>& BBs

llvm::BasicBlock* getAfter() const

Description

The after block is intended for clean-up code such as lifetime end markers. It is separate from the exit block to ensure, analogous to the preheader, it having just a single entry edge and being free from PHI nodes should there be multiple loop exits (such as from break statements/cancellations).

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1757

OpenMPIRBuilder::InsertPointTy getAfterIP() const

Description

Return the insertion point for user code after the loop.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1802

llvm::BasicBlock* getBody() const

Description

The body block is the single entry for a loop iteration and not controlled by CanonicalLoopInfo. It can contain arbitrary control flow but must eventually branch to the \p Latch block.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1733

OpenMPIRBuilder::InsertPointTy getBodyIP() const

Description

Return the insertion point for user code in the body.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1795

llvm::BasicBlock* getCond() const

Description

The condition block computes whether there is another loop iteration. If yes, branches to the body; otherwise to the exit block.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1725

llvm::BasicBlock* getExit() const

Description

Reaching the exit indicates no more iterations are being executed.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1747

llvm::Function* getFunction() const

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1808

llvm::BasicBlock* getHeader() const

Description

The header is the entry for each iteration. In the canonical control flow, it only contains the PHINode for the induction variable.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1718

llvm::Instruction* getIndVar() const

Description

Returns the instruction representing the current logical induction variable. Always unsigned, always starting at 0 with an increment of one.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1774

llvm::Type* getIndVarType() const

Description

Return the type of the induction variable (and the trip count).

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1782

llvm::BasicBlock* getLatch() const

Description

Reaching the latch indicates the end of the loop body code. In the canonical control flow, it only contains the increment of the induction variable.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1741

llvm::BasicBlock* getPreheader() const

Description

The preheader ensures that there is only a single edge entering the loop. Code that must be execute before any loop iteration can be emitted here, such as computing the loop trip count and begin lifetime markers. Code in the preheader is not considered part of the canonical loop.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1714

OpenMPIRBuilder::InsertPointTy getPreheaderIP()
    const

Description

Return the insertion point for user code before the loop.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1788

llvm::Value* getTripCount() const

Description

Returns the llvm::Value containing the number of loop iterations. It must be valid in the preheader and always interpreted as an unsigned integer of any bit-width.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1765

void invalidate()

Description

Invalidate this loop. That is, the underlying IR does not fulfill the requirements of an OpenMP canonical loop anymore.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1818

bool isValid() const

Description

Returns whether this object currently represents the IR of a loop. If returning false, it may have been consumed by a loop transformation or not been intialized. Do not use in this case;

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1708

void mapIndVar(
    llvm::function_ref<Value*(Instruction*)>
        Updater)

Description

Replace all uses of the canonical induction variable in the loop body with a new one. The intended use case is to update the induction variable for an updated iteration space such that it can stay normalized in the 0...tripcount-1 range. The \p Updater is called with the (presumable updated) current normalized induction variable and is expected to return the value that uses of the pre-updated induction values should use instead, typically dependent on the new induction variable. This is a lambda (instead of e.g. just passing the new value) to be able to distinguish the uses of the pre-updated induction variable and uses of the induction varible to compute the updated induction variable value.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1702

Parameters

llvm::function_ref<Value*(Instruction*)> Updater

void setTripCount(llvm::Value* TripCount)

Description

Sets the number of loop iterations to the given value. This value must be valid in the condition block (i.e., defined in the preheader) and is interpreted as an unsigned integer.

Declared at: llvm/include/llvm/Frontend/OpenMP/OMPIRBuilder.h:1686

Parameters

llvm::Value* TripCount