.. java:import:: fr.inria.tapenade.utils ILLang .. java:import:: fr.inria.tapenade.utils TapPair .. java:import:: fr.inria.tapenade.utils TapIntList .. java:import:: fr.inria.tapenade.utils ToBool .. java:import:: fr.inria.tapenade.utils ToObject .. java:import:: fr.inria.tapenade.utils Tree RefDescriptor ============= .. java:package:: fr.inria.tapenade.representation :noindex: .. java:type:: public final class RefDescriptor Objects that hold a description of all components of a given expression Tree. Tree is most often a reference. "components" means values contained or accessed through the tree. The RefDescriptor finds and analyzes all the iterations contained in the "tree", using the type information available. The RefDescriptor chooses the way to access to all these components for a given sort of "use", e.g. a PUSH-POP, an initialization, an I-O,... Example: to initialize A(3,:), one can use vector notation for the ":" to PUSH A(:)%x(:), the two ":" cannot be vector together. Then after the "use" is chosen, the RefDescriptor can generate PUSH-POP or initialization or other standard operations working on this "tree". Two RefDescriptor's can be merged, thus sharing the iterative loops when performing some operations. NOTE: when the given expression Tree contains an array index or a C pointer-array index which is an op_dimColon instead of an op_arrayTriplet, then we consider this is a full access to this particular dimension, therefore sometimes simplifying the returned access instructions. If modifying this code, relevant nonRegression tests may be: set03/lh062 set04/lh108 set06/v322 set06/v324 set06/v325 set06/v350 Fields ------ altRootIdent ^^^^^^^^^^^^ .. java:field:: public Tree altRootIdent :outertype: RefDescriptor completeType ^^^^^^^^^^^^ .. java:field:: public WrapperTypeSpec completeType :outertype: RefDescriptor The type of "tree" seen as a whole. elementType ^^^^^^^^^^^ .. java:field:: public WrapperTypeSpec elementType :outertype: RefDescriptor The type of the elements of "tree". holdsAPointer ^^^^^^^^^^^^^ .. java:field:: public boolean holdsAPointer :outertype: RefDescriptor True when this RefDescriptor will access a pointer, i.e. in the PUSH/POP case, it will call PUSH/POPPOINTERn(). This flag is set during createNestedLoopTree(). mayProtectAccesses ^^^^^^^^^^^^^^^^^^ .. java:field:: public boolean mayProtectAccesses :outertype: RefDescriptor If true, the generated code may contain IF (ALLOCATED/ASSOCIATED(...)) tests to protect from access to unallocated memory. toBranchVariable ^^^^^^^^^^^^^^^^ .. java:field:: public TapPair toBranchVariable :outertype: RefDescriptor Because at one place, we need the variable used by the adjoint code to store the POP'ped branch. This field must be shared with the "toBranchVariable" of class FlowGraphDifferentiator. zoneInfo ^^^^^^^^ .. java:field:: public ZoneInfo zoneInfo :outertype: RefDescriptor When this RefDescriptor was built for a complete zone (instead of for a precise Tree), holds the ZoneInfo of the zone. Constructors ------------ RefDescriptor ^^^^^^^^^^^^^ .. java:constructor:: public RefDescriptor(Tree tree, ZoneInfo zoneInfo, WrapperTypeSpec type, WrapperTypeSpec expectedType, Tree hintRootTree, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, SymbolTable otherUsageSymbolTable, Tree altRootIdent, boolean isDiff, IterDescriptor multiDirIterator, Unit targetUnit) :outertype: RefDescriptor Creation of the RefDescriptor for the object given by "tree". Extended primitive that copes with the weird case: call TOTO(T(i)) with SUBROUTINE TOTO(array[1:N]) Also copes with new variables introduced by split: they may have no type therefore we use the formal type instead. When zoneInfo is passed non-null, it means that this RefDescriptor designates exactly the full contents of this zone. RefDescriptor ^^^^^^^^^^^^^ .. java:constructor:: public RefDescriptor(Tree tree, WrapperTypeSpec forcedType, Tree hintRootTree, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, SymbolTable otherUsageSymbolTable, Tree altRootIdent, boolean isDiff, IterDescriptor multiDirIterator, Unit targetUnit) :outertype: RefDescriptor Creation of the RefDescriptor for the object accessed by "tree", giving explicitly the WrapperTypeSpec that must be taken for this tree. RefDescriptor ^^^^^^^^^^^^^ .. java:constructor:: public RefDescriptor(Tree tree, Tree hintRootTree, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, SymbolTable otherUsageSymbolTable, Tree altRootIdent, boolean isDiff, IterDescriptor multiDirIterator, Unit targetUnit) :outertype: RefDescriptor Creation of the RefDescriptor for the object accessed by "tree". RefDescriptor ^^^^^^^^^^^^^ .. java:constructor:: public RefDescriptor(ZoneInfo zoneInfo, Tree zoneInfoVisibleAccessTree, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, SymbolTable otherUsageSymbolTable, Tree altRootIdent, boolean isDiff, IterDescriptor multiDirIterator, Unit targetUnit) :outertype: RefDescriptor Creation of the RefDescriptor for the object given by "zoneInfo". Methods ------- addDeref ^^^^^^^^ .. java:method:: public void addDeref() :outertype: RefDescriptor collectTrees ^^^^^^^^^^^^ .. java:method:: public TapList collectTrees(TapList collected) :outertype: RefDescriptor Collect into "collected" all the trees found at the leaves of the nestedLoopTree tree of this RefDescriptor. explicitWhenImplicitArray ^^^^^^^^^^^^^^^^^^^^^^^^^ .. java:method:: public static Tree explicitWhenImplicitArray(Tree tree, WrapperTypeSpec type, WrapperTypeSpec expectedType, SymbolTable symbolTable) :outertype: RefDescriptor Replaces actual argument T(6) as T(6:) when the formal argument is declared with dimensions. forceStaticSave ^^^^^^^^^^^^^^^ .. java:method:: public void forceStaticSave(RefDescriptor saveVarVarDescriptor) :outertype: RefDescriptor isChannelOrIO ^^^^^^^^^^^^^ .. java:method:: public boolean isChannelOrIO() :outertype: RefDescriptor returns true for special fake variables for IOstreams. makeAssign ^^^^^^^^^^ .. java:method:: public static Tree makeAssign(Unit targetUnit, Tree lhsExpr, Tree rhsExpr, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, Tree lhsAltRootIdent, Tree rhsAltRootIdent, boolean isDiff, IterDescriptor multiDirIterator) :outertype: RefDescriptor :return: an instruction Tree that assigns one reference expression into another. Namely: "lhsExpr" := "rhsExpr" Quick call that does the whole chain of creation, preparation, merging, and making Tree in one single call. Does not allow for manipulation of individual RefDescriptors. makeAssign ^^^^^^^^^^ .. java:method:: public Tree makeAssign(RefDescriptor rhsd) :outertype: RefDescriptor makeFixedControl ^^^^^^^^^^^^^^^^ .. java:method:: public void makeFixedControl(int nbControls) :outertype: RefDescriptor makeFixedControlPop ^^^^^^^^^^^^^^^^^^^ .. java:method:: public static Instruction makeFixedControlPop(Unit targetUnit, Tree expr, int nbCases, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, int ppLabel) :outertype: RefDescriptor Same as makePop, but will store a control integer using PUSH/POPCONTROL(case,nbCases). makeIncrement ^^^^^^^^^^^^^ .. java:method:: public static Tree makeIncrement(Unit targetUnit, Tree lhsExpr, Tree rhsExpr, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, Tree lhsAltRootIdent, Tree rhsAltRootIdent, boolean isDiff, IterDescriptor multiDirIterator) :outertype: RefDescriptor :return: an instruction Tree that adds one reference expression into another. Namely: "lhsExpr" := "lhsExpr"+"rhsExpr" Quick call that does the whole chain of creation, preparation, merging, and making Tree in one single call. Does not allow for manipulation of individual RefDescriptors. makeIncrement ^^^^^^^^^^^^^ .. java:method:: public Tree makeIncrement(RefDescriptor incrd, boolean needAtomic) :outertype: RefDescriptor makeInitialize ^^^^^^^^^^^^^^ .. java:method:: public static Tree makeInitialize(Unit targetUnit, ZoneInfo zoneInfo, Tree expr, WrapperTypeSpec actualArgType, WrapperTypeSpec formalArgType, Tree hintRootTree, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, SymbolTable otherUsageSymbolTable, Tree altRootIdent, boolean isDiff, IterDescriptor multiDirIterator, boolean protectAccesses, TapList ignoreStructure, boolean ignorePointed) :outertype: RefDescriptor Builds an instruction Tree that initializes reference expression "expr". Quick call that does the whole chain of creation, preparation, merging, and making Tree in one single call. Does not allow for manipulation of individual RefDescriptors. When zoneInfo is passed non-null, it indicates that we want to initialize the full corresponding zone, and then "expr" contains this zoneInfo's accessTree, possibly slightly modified (see BlockDifferentiator.makeDiffInitialization()). makeInitialize ^^^^^^^^^^^^^^ .. java:method:: public Tree makeInitialize() :outertype: RefDescriptor makeNormDiff ^^^^^^^^^^^^ .. java:method:: public static Tree makeNormDiff(Unit targetUnit, Tree cumulTree, Tree newExpr, Tree oldExpr, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, Tree newAltRootIdent, Tree oldAltRootIdent, boolean isDiff, IterDescriptor multiDirIterator) :outertype: RefDescriptor makePop ^^^^^^^ .. java:method:: public static Instruction makePop(Unit targetUnit, Tree expr, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, int ppLabel, TapPair toBranchVariable) :outertype: RefDescriptor :return: an instruction Tree that POP's expression "expr". Quick call that does the whole chain of creation, preparation, merging, and making Tree in one single call. Does not allow for manipulation of individual RefDescriptors. makePop ^^^^^^^ .. java:method:: public Tree makePop() :outertype: RefDescriptor makePopDiff ^^^^^^^^^^^ .. java:method:: public static Instruction makePopDiff(Unit targetUnit, Tree expr, Tree diffRoot, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, int ppLabel) :outertype: RefDescriptor Same as makePop(...), but replaces the root of "expr" with its derivative "diffRoot". makePush ^^^^^^^^ .. java:method:: public static Instruction makePush(Unit targetUnit, Tree expr, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, int ppLabel) :outertype: RefDescriptor :return: an instruction Tree that PUSH'es expression "expr". Quick call that does the whole chain of creation, preparation, merging, and making Tree in one single call. Does not allow for manipulation of individual RefDescriptors. makePush ^^^^^^^^ .. java:method:: public Tree makePush() :outertype: RefDescriptor makePushDiff ^^^^^^^^^^^^ .. java:method:: public static Instruction makePushDiff(Unit targetUnit, Tree expr, Tree diffRoot, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, int ppLabel) :outertype: RefDescriptor Same as makePush(...), but replaces the root of "expr" with its derivative "diffRoot". makeRebase ^^^^^^^^^^ .. java:method:: public Tree makeRebase(TapList ignorePrimal, TapList ignoreDiff, Tree diffBaseVar, int numRebase) :outertype: RefDescriptor Creates the instruction that rebases all pointers and/or their diff pointers in the expression represented by this RefDescriptor. We assume the nestedLoopTree of this RefDescriptor has been prepared by this.prepareForStack(). Ignores the primal pointers for the True leaves of "ignorePrimal". Ignores the diff pointers for the True leaves of "ignoreDiff". :param ignorePrimal: the tree of Booleans indicating the leaves for which no rebase is needed (for the primal) :param ignoreDiff: the tree of Booleans indicating the leaves for which no rebase is needed (for the diff) :param diffBaseVar: the differentiated root variable, used when some diff pointer must be rebased. :param numRebase: the "unique" number used to build a label to identify this rebase for debugAD. :return: an instruction that does the requested rebase of POPped pointers. makeRef ^^^^^^^ .. java:method:: public Tree makeRef() :outertype: RefDescriptor :return: an expression tree that refers to the contents of the current RefDescriptor. Unlike makeStack or makeAssign, this is sometimes not posible, e.g what is a single expression referring to A%x and A%z ??? makeStack ^^^^^^^^^ .. java:method:: public static Tree makeStack(Unit targetUnit, String stackOp, boolean directDirection, ZoneInfo zoneInfo, Tree zoneInfoVisibleAccessTree, SymbolTable defSymbolTable, SymbolTable usageSymbolTable, boolean protectAccesses, int ppLabel) :outertype: RefDescriptor Builds an instruction Tree that does the stack-like operation "stackOp" on the memory described by "zoneInfo". Quick call that does the whole chain of creation, preparation, merging, and making Tree in one single call. Does not allow for manipulation of individual RefDescriptors. prepareForAssignOrNormDiff ^^^^^^^^^^^^^^^^^^^^^^^^^^ .. java:method:: public void prepareForAssignOrNormDiff(RefDescriptor otherRefDescriptor, Unit targetUnit, TapList ignoreStructure, boolean ignorePointed) :outertype: RefDescriptor Jointly prepare this RefDescriptor and the "otherRefDescriptor" RefDescriptor to be used to build an assignment or a computation of square norm operation between the two trees. prepareForInitialize ^^^^^^^^^^^^^^^^^^^^ .. java:method:: public void prepareForInitialize(Unit targetUnit, TapList ignoreStructure, boolean ignorePointed) :outertype: RefDescriptor Prepares this RefDescriptor to be used to build initialization operations on the tree. prepareForStack ^^^^^^^^^^^^^^^ .. java:method:: public void prepareForStack(Unit targetUnit, int ppLabel, TapList ignoreStructure, boolean ignorePointed) :outertype: RefDescriptor Prepares this RefDescriptor to be used to build PUSH/POP operations on the tree. 1) Decides which iterations will be loops or arrays 2) Builds the tree of nested loops 3) If required, chooses a unique number for matching PUSH and POPs refTree ^^^^^^^ .. java:method:: public Tree refTree() :outertype: RefDescriptor setCompanionVarDescriptor ^^^^^^^^^^^^^^^^^^^^^^^^^ .. java:method:: public void setCompanionVarDescriptor(RefDescriptor otherVarDescriptor) :outertype: RefDescriptor setHintArrayTreeForCallSize ^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. java:method:: public void setHintArrayTreeForCallSize(Tree tree) :outertype: RefDescriptor toString ^^^^^^^^ .. java:method:: @Override public String toString() :outertype: RefDescriptor usesStaticSave ^^^^^^^^^^^^^^ .. java:method:: public boolean usesStaticSave() :outertype: RefDescriptor