LLVM 19.0.0git
Public Member Functions | Friends | List of all members
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.
 
BasicBlockgetPreheader () const
 The preheader ensures that there is only a single edge entering the loop.
 
BasicBlockgetHeader () const
 The header is the entry for each iteration.
 
BasicBlockgetCond () const
 The condition block computes whether there is another loop iteration.
 
BasicBlockgetBody () const
 The body block is the single entry for a loop iteration and not controlled by CanonicalLoopInfo.
 
BasicBlockgetLatch () const
 Reaching the latch indicates the end of the loop body code.
 
BasicBlockgetExit () const
 Reaching the exit indicates no more iterations are being executed.
 
BasicBlockgetAfter () const
 The after block is intended for clean-up code such as lifetime end markers.
 
ValuegetTripCount () const
 Returns the llvm::Value containing the number of loop iterations.
 
InstructiongetIndVar () const
 Returns the instruction representing the current logical induction variable.
 
TypegetIndVarType () const
 Return the type of the induction variable (and the trip count).
 
OpenMPIRBuilder::InsertPointTy getPreheaderIP () const
 Return the insertion point for user code before the loop.
 
OpenMPIRBuilder::InsertPointTy getBodyIP () const
 Return the insertion point for user code in the body.
 
OpenMPIRBuilder::InsertPointTy getAfterIP () const
 Return the insertion point for user code after the loop.
 
FunctiongetFunction () const
 
void assertOK () const
 Consistency self-check.
 
void invalidate ()
 Invalidate this loop.
 

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:

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 2742 of file OMPIRBuilder.h.

Member Function Documentation

◆ assertOK()

void CanonicalLoopInfo::assertOK ( ) const

◆ 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 2835 of file OMPIRBuilder.h.

References assert(), and isValid().

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

◆ getAfterIP()

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

Return the insertion point for user code after the loop.

Definition at line 2880 of file OMPIRBuilder.h.

References After, assert(), 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 2811 of file OMPIRBuilder.h.

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

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

◆ getBodyIP()

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

Return the insertion point for user code in the body.

Definition at line 2873 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 2803 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 2825 of file OMPIRBuilder.h.

References assert(), and isValid().

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

◆ getFunction()

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

Definition at line 2886 of file OMPIRBuilder.h.

References assert(), and isValid().

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

◆ getHeader()

BasicBlock * llvm::CanonicalLoopInfo::getHeader ( ) const
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 2796 of file OMPIRBuilder.h.

References assert(), and isValid().

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

◆ 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 2852 of file OMPIRBuilder.h.

References assert(), and isValid().

Referenced by llvm::OpenMPIRBuilder::createCanonicalLoop(), getIndVarType(), and llvm::OpenMPIRBuilder::tileLoops().

◆ getIndVarType()

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

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

Definition at line 2860 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 2819 of file OMPIRBuilder.h.

References assert(), and isValid().

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

◆ getPreheader()

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 7147 of file OMPIRBuilder.cpp.

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

Referenced by llvm::OpenMPIRBuilder::applySimd(), llvm::OpenMPIRBuilder::collapseLoops(), llvm::OpenMPIRBuilder::createCanonicalLoop(), getPreheaderIP(), llvm::OpenMPIRBuilder::tileLoops(), and workshareLoopTargetCallback().

◆ getPreheaderIP()

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

Return the insertion point for user code before the loop.

Definition at line 2866 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 2843 of file OMPIRBuilder.h.

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

Referenced by workshareLoopTargetCallback().

◆ 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 7295 of file OMPIRBuilder.cpp.

References Cond.

Referenced by workshareLoopTargetCallback().

◆ 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 2786 of file OMPIRBuilder.h.

Referenced by getAfter(), getAfterIP(), getBody(), getBodyIP(), getCond(), getExit(), getFunction(), getHeader(), getIndVar(), getIndVarType(), getLatch(), getPreheaderIP(), and getTripCount().

Friends And Related Function Documentation

◆ OpenMPIRBuilder

friend class OpenMPIRBuilder
friend

Definition at line 2743 of file OMPIRBuilder.h.


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