LLVM  17.0.0git
llvm::CanonicalLoopInfo Class Reference

Class to represented the control flow structure of an OpenMP canonical loop. More...

#include "llvm/Frontend/OpenMP/OMPIRBuilder.h"

Public Member Functions

bool isValid () const
Returns whether this object currently represents the IR of a loop. More...

The preheader ensures that there is only a single edge entering the loop. More...

The header is the entry for each iteration. More...

BasicBlockgetCond () const
The condition block computes whether there is another loop iteration. More...

BasicBlockgetBody () const
The body block is the single entry for a loop iteration and not controlled by CanonicalLoopInfo. More...

BasicBlockgetLatch () const
Reaching the latch indicates the end of the loop body code. More...

BasicBlockgetExit () const
Reaching the exit indicates no more iterations are being executed. More...

BasicBlockgetAfter () const
The after block is intended for clean-up code such as lifetime end markers. More...

ValuegetTripCount () const
Returns the llvm::Value containing the number of loop iterations. More...

InstructiongetIndVar () const
Returns the instruction representing the current logical induction variable. More...

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

Return the insertion point for user code before the loop. More...

OpenMPIRBuilder::InsertPointTy getBodyIP () const
Return the insertion point for user code in the body. More...

OpenMPIRBuilder::InsertPointTy getAfterIP () const
Return the insertion point for user code after the loop. More...

FunctiongetFunction () const

void assertOK () const
Consistency self-check. More...

void invalidate ()
Invalidate this loop. More...

Friends

class OpenMPIRBuilder

Detailed 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.

Definition at line 2253 of file OMPIRBuilder.h.

◆ assertOK()

 void CanonicalLoopInfo::assertOK ( ) const

Consistency self-check.

Definition at line 5222 of file OMPIRBuilder.cpp.

◆ getAfter()

 BasicBlock* llvm::CanonicalLoopInfo::getAfter ( ) const
inline

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).

Definition at line 2346 of file OMPIRBuilder.h.

References assert(), llvm::BasicBlock::getSingleSuccessor(), and isValid().

◆ getAfterIP()

 OpenMPIRBuilder::InsertPointTy llvm::CanonicalLoopInfo::getAfterIP ( ) const
inline

Return the insertion point for user code after the loop.

Definition at line 2391 of file OMPIRBuilder.h.

References assert(), llvm::BasicBlock::begin(), getAfter(), and isValid().

◆ getBody()

 BasicBlock* llvm::CanonicalLoopInfo::getBody ( ) const
inline

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 Latch block.

Definition at line 2322 of file OMPIRBuilder.h.

References assert(), Cond, and isValid().

◆ getBodyIP()

 OpenMPIRBuilder::InsertPointTy llvm::CanonicalLoopInfo::getBodyIP ( ) const
inline

Return the insertion point for user code in the body.

Definition at line 2384 of file OMPIRBuilder.h.

References assert(), llvm::BasicBlock::begin(), getBody(), and isValid().

Referenced by llvm::OpenMPIRBuilder::createCanonicalLoop().

◆ getCond()

 BasicBlock* llvm::CanonicalLoopInfo::getCond ( ) const
inline

The condition block computes whether there is another loop iteration.

If yes, branches to the body; otherwise to the exit block.

Definition at line 2314 of file OMPIRBuilder.h.

References assert(), Cond, and isValid().

Referenced by llvm::OpenMPIRBuilder::applySimd().

◆ getExit()

 BasicBlock* llvm::CanonicalLoopInfo::getExit ( ) const
inline

Reaching the exit indicates no more iterations are being executed.

Definition at line 2336 of file OMPIRBuilder.h.

References assert(), and isValid().

Referenced by llvm::OpenMPIRBuilder::tileLoops().

◆ getFunction()

 Function* llvm::CanonicalLoopInfo::getFunction ( ) const
inline

Definition at line 2397 of file OMPIRBuilder.h.

References assert(), and isValid().

Referenced by llvm::OpenMPIRBuilder::applySimd(), and computeHeuristicUnrollFactor().

inline

The header is the entry for each iteration.

In the canonical control flow, it only contains the PHINode for the induction variable.

Definition at line 2307 of file OMPIRBuilder.h.

References assert(), and isValid().

Referenced by llvm::OpenMPIRBuilder::applySimd(), and computeHeuristicUnrollFactor().

◆ getIndVar()

 Instruction* llvm::CanonicalLoopInfo::getIndVar ( ) const
inline

Returns the instruction representing the current logical induction variable.

Always unsigned, always starting at 0 with an increment of one.

Definition at line 2363 of file OMPIRBuilder.h.

References assert(), and isValid().

◆ getIndVarType()

 Type* llvm::CanonicalLoopInfo::getIndVarType ( ) const
inline

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

Definition at line 2371 of file OMPIRBuilder.h.

References assert(), getIndVar(), llvm::Value::getType(), and isValid().

◆ getLatch()

 BasicBlock* llvm::CanonicalLoopInfo::getLatch ( ) const
inline

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.

Definition at line 2330 of file OMPIRBuilder.h.

References assert(), and isValid().

 BasicBlock * CanonicalLoopInfo::getPreheader ( ) const

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.

Definition at line 5168 of file OMPIRBuilder.cpp.

References assert(), isValid(), llvm_unreachable, and llvm::predecessors().

inline

Return the insertion point for user code before the loop.

Definition at line 2377 of file OMPIRBuilder.h.

References assert(), llvm::BasicBlock::end(), getPreheader(), and isValid().

Referenced by llvm::OpenMPIRBuilder::collapseLoops(), and llvm::OpenMPIRBuilder::tileLoops().

◆ getTripCount()

 Value* llvm::CanonicalLoopInfo::getTripCount ( ) const
inline

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.

Definition at line 2354 of file OMPIRBuilder.h.

References assert(), Cond, llvm::User::getOperand(), and isValid().

◆ invalidate()

 void CanonicalLoopInfo::invalidate ( )

Invalidate this loop.

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

Definition at line 5316 of file OMPIRBuilder.cpp.

References Cond.

◆ isValid()

 bool llvm::CanonicalLoopInfo::isValid ( ) const
inline

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;

Definition at line 2297 of file OMPIRBuilder.h.

◆ OpenMPIRBuilder

 friend class OpenMPIRBuilder
friend

Definition at line 2254 of file OMPIRBuilder.h.

The documentation for this class was generated from the following files: