Instruction
===========

.. java:package:: fr.inria.tapenade.representation
   :noindex:

.. java:type:: public final class Instruction

   Container for an atomic instruction in a Block in a Flow Graph.

Fields
------
block
^^^^^

.. java:field:: public Block block
   :outertype: Instruction

   The basic block that contains this instruction.

directives
^^^^^^^^^^

.. java:field:: public TapList<Directive> directives
   :outertype: Instruction

   The list of Tapenade Directive's attached to this instruction, if any.

isDifferentiated
^^^^^^^^^^^^^^^^

.. java:field:: public boolean isDifferentiated
   :outertype: Instruction

   Used during differentiation to mark that this instruction has been differentiated (Specific to AD).

isPhantom
^^^^^^^^^

.. java:field:: public boolean isPhantom
   :outertype: Instruction

   Set "isPhantom" to true to ensure this Instruction will not be shown.

lineNo
^^^^^^

.. java:field:: public int lineNo
   :outertype: Instruction

   When not lost by parsing, the line number in the source file. 0 otherwise.

pointerDestsChanges
^^^^^^^^^^^^^^^^^^^

.. java:field:: public TapList<TapPair<TapIntList, BoolVector>> pointerDestsChanges
   :outertype: Instruction

   List of all the modifications brought by this instruction on the current pointers destinations info. List of TapPair's:

   ..

   * first : singleton TapIntList of pointer row index
   * second: BoolVector of the new possible destinations

postComments
^^^^^^^^^^^^

.. java:field:: public Tree postComments
   :outertype: Instruction

   The "line" comments after this instruction, e.g. comments starting with // and ending with newline.

postCommentsBlock
^^^^^^^^^^^^^^^^^

.. java:field:: public Tree postCommentsBlock
   :outertype: Instruction

   The "block" comments after this instruction, which are comments starting with a special code and ending with another special code.

preComments
^^^^^^^^^^^

.. java:field:: public Tree preComments
   :outertype: Instruction

   The "line" comments before this instruction, e.g. comments starting with // and ending with newline.

preCommentsBlock
^^^^^^^^^^^^^^^^

.. java:field:: public Tree preCommentsBlock
   :outertype: Instruction

   The "block" comments before this instruction, which are comments starting with a special code and ending with another special code.

syntaxController
^^^^^^^^^^^^^^^^

.. java:field:: public Instruction syntaxController
   :outertype: Instruction

   The deepest instruction syntactically around this instruction, if any. This is the control instruction of the deepest syntactic construct that contains this instruction.

tree
^^^^

.. java:field:: public Tree tree
   :outertype: Instruction

   The instruction's Abstract Syntax Tree.

Constructors
------------
Instruction
^^^^^^^^^^^

.. java:constructor:: public Instruction()
   :outertype: Instruction

   Create an empty Instruction.

Instruction
^^^^^^^^^^^

.. java:constructor:: public Instruction(Tree tree)
   :outertype: Instruction

   Create an Instruction containing the given tree.

Instruction
^^^^^^^^^^^

.. java:constructor:: public Instruction(Tree tree, Instruction syntaxController)
   :outertype: Instruction

   Create an Instruction containing the given tree, also giving its syntactic controller.

Instruction
^^^^^^^^^^^

.. java:constructor:: public Instruction(Tree tree, Instruction syntaxController, int lineNo)
   :outertype: Instruction

   Create an Instruction containing the given tree, also giving its syntactic controller and source code line number.

Instruction
^^^^^^^^^^^

.. java:constructor:: public Instruction(Tree tree, Instruction syntaxController, Block block)
   :outertype: Instruction

   Create an Instruction containing the given tree, also giving its syntactic controller and containing Block.

Methods
-------
addPreComments
^^^^^^^^^^^^^^

.. java:method:: public void addPreComments(String newComment)
   :outertype: Instruction

   Add the comment with text "newComment" in front of this instruction's preComments.

appendPostComments
^^^^^^^^^^^^^^^^^^

.. java:method:: public void appendPostComments(TapList<Tree> newComments)
   :outertype: Instruction

   Add the given newComments after this instruction's postComments.

appendPreComments
^^^^^^^^^^^^^^^^^

.. java:method:: public void appendPreComments(TapList<Tree> newComments)
   :outertype: Instruction

   Add the given newComments after this instruction's preComments.

containsPreComment
^^^^^^^^^^^^^^^^^^

.. java:method:: public String containsPreComment(String searched)
   :outertype: Instruction

copy
^^^^

.. java:method:: public Instruction copy(TapList<TapPair<Instruction, Instruction>> alreadyCopiedMasks)
   :outertype: Instruction

   :return: a copy of this instruction, making sure that the copy's where mask is a copy of the instruction's vectorial mask.

copyCommentsToTree
^^^^^^^^^^^^^^^^^^

.. java:method:: public void copyCommentsToTree(Tree tree)
   :outertype: Instruction

   Copy the comments that were stored in this Instruction, back as "*Comments*" annotations on the given tree

copyTreePlusComments
^^^^^^^^^^^^^^^^^^^^

.. java:method:: public Tree copyTreePlusComments()
   :outertype: Instruction

   :return: a copy (ILUtils.copy()) of this instruction's Tree, with all comments present on this instruction copied and attached to the root of the copy tree.

createUnitDefinitionStub
^^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public static Instruction createUnitDefinitionStub(Unit definedUnit, Block containerBlock)
   :outertype: Instruction

   :return: a new "unit definition stub" Instruction, used to mark the location of this Unit's definition in the code.

createUnitDefinitionStubTree
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public static Tree createUnitDefinitionStubTree(Unit definedUnit)
   :outertype: Instruction

   :return: a new "unit definition stub" Tree, used to mark the location of the given Unit's definition in the code.

declareIsMaskDefinition
^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: protected void declareIsMaskDefinition()
   :outertype: Instruction

   States that this instruction is the one that sets the mask of a WHERE.

declaredSymbolDecls
^^^^^^^^^^^^^^^^^^^

.. java:method:: public TapList<SymbolDecl> declaredSymbolDecls(SymbolTable publicSymbolTable, SymbolTable privateSymbolTable)
   :outertype: Instruction

   :return: the list of all SymbolDecl's declared by this Instruction.

declaresUnits
^^^^^^^^^^^^^

.. java:method:: public TapList<Unit> declaresUnits(SymbolTable symbolTable)
   :outertype: Instruction

differentiateChainedIncludes
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public static Instruction differentiateChainedIncludes(Instruction includeInstr, String suffix, boolean wait)
   :outertype: Instruction

   :param wait: When true, use the existing diff name if exists, but do not create it if it doesn't exist.
   :param suffix: The suffix used for differentiation. May be passed null when wait==true.

dump
^^^^

.. java:method:: public void dump() throws java.io.IOException
   :outertype: Instruction

   Prints in detail the contents of this Instruction, onto TapEnv.curOutputStream().

encloseInWhereMask
^^^^^^^^^^^^^^^^^^

.. java:method:: public void encloseInWhereMask(InstructionMask enclosingWhereMask)
   :outertype: Instruction

   Connects enclosingWhereMask as an additional enclosing where mask around this Instruction (except if it has already been connected)

forceDiffInclude
^^^^^^^^^^^^^^^^

.. java:method:: public void forceDiffInclude(String suffix)
   :outertype: Instruction

   Modify TapEnv.differentiatedIncludeNames so that this include name will be differentiated in the generated code

fromInclude
^^^^^^^^^^^

.. java:method:: public Instruction fromInclude()
   :outertype: Instruction

   When this instruction comes from an INCLUDE file.

   :return: the instruction that does the include.

fromIncludeCopy
^^^^^^^^^^^^^^^

.. java:method:: public static Instruction fromIncludeCopy(Instruction fromIncludeInstr, boolean copy)
   :outertype: Instruction

   :return: a copy of this.fromInclude.

fromIncludeRootName
^^^^^^^^^^^^^^^^^^^

.. java:method:: public String fromIncludeRootName()
   :outertype: Instruction

getPosition
^^^^^^^^^^^

.. java:method:: public int getPosition()
   :outertype: Instruction

   :return: the "position" of this instruction in the file it comes from.

getWhereMask
^^^^^^^^^^^^

.. java:method:: public InstructionMask getWhereMask()
   :outertype: Instruction

   :return: the vectorial mask of this instruction. When the instruction is a where test, the returned vectorial mask does not include this where control.

hasCommentStartingWith
^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public static String hasCommentStartingWith(Tree comment, String startString)
   :outertype: Instruction

hasCommentWith
^^^^^^^^^^^^^^

.. java:method:: public boolean hasCommentWith(String text)
   :outertype: Instruction

hasCommentWith
^^^^^^^^^^^^^^

.. java:method:: public static boolean hasCommentWith(Tree comment, String text)
   :outertype: Instruction

hasDirective
^^^^^^^^^^^^

.. java:method:: public Directive hasDirective(int kind)
   :outertype: Instruction

   Looks for a directive of the given kind attached to this instruction.

   :param kind: The searched kind of directive
   :return: The directive of the given kind, or null if not found.

hasPostCommentStartingWith
^^^^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public String hasPostCommentStartingWith(String startString)
   :outertype: Instruction

hasPreCommentStartingWith
^^^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public String hasPreCommentStartingWith(String startString)
   :outertype: Instruction

isADeclaration
^^^^^^^^^^^^^^

.. java:method:: public boolean isADeclaration()
   :outertype: Instruction

   :return: true if this instruction is a declaration statement.

isALoop
^^^^^^^

.. java:method:: public boolean isALoop()
   :outertype: Instruction

   :return: true if this instruction is loop control.

isANoOp
^^^^^^^

.. java:method:: public boolean isANoOp()
   :outertype: Instruction

   :return: true if this instruction is a no_op, i.e. a op_none, created only e.g. to hold some comments.

isAProcedure
^^^^^^^^^^^^

.. java:method:: public boolean isAProcedure()
   :outertype: Instruction

isAWhereControl
^^^^^^^^^^^^^^^

.. java:method:: public boolean isAWhereControl()
   :outertype: Instruction

   :return: true if this instruction is a where control instruction.

isInStdCInclude
^^^^^^^^^^^^^^^

.. java:method:: public boolean isInStdCInclude()
   :outertype: Instruction

isInStdInclude
^^^^^^^^^^^^^^

.. java:method:: public boolean isInStdInclude()
   :outertype: Instruction

isMaskDefinition
^^^^^^^^^^^^^^^^

.. java:method:: public boolean isMaskDefinition()
   :outertype: Instruction

   :return: true when this instruction is the one that sets the mask of a WHERE.

isUnitDefinitionStub
^^^^^^^^^^^^^^^^^^^^

.. java:method:: public Unit isUnitDefinitionStub()
   :outertype: Instruction

replaceTree
^^^^^^^^^^^

.. java:method:: public Tree replaceTree(Tree oldTree, Tree newTree)
   :outertype: Instruction

   Replaces the given oldTree by the given newTree in-place inside the tree of this Instruction. Does nothing when newTree is null or equals oldTree. When necessary, the tree of this Instruction is itself modified.

   :return: the newTree.

setFromInclude
^^^^^^^^^^^^^^

.. java:method:: public void setFromInclude(Instruction incl)
   :outertype: Instruction

setFromIncludeCopy
^^^^^^^^^^^^^^^^^^

.. java:method:: public void setFromIncludeCopy(Instruction origInclude, boolean copy)
   :outertype: Instruction

   Declare that this Instruction belongs to the include file "origInclude".

setIncludeOfDiffInstructions
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public void setIncludeOfDiffInstructions(Instruction primalInstruction, boolean primalIsRewritten, TapList<Instruction>[] diffInstructionSR, String suffix)
   :outertype: Instruction

   Decorates the given primalInstruction and each of diffInstructionS, with the "fromInclude" info built by differentiation of this Instruction ("this" Instruction is the "fromInclude" of the original non-differentiated instruction). Keeps track of the correspondence between non-diff and diff include file names through TapEnv.get().differentiatedIncludeNames.

   :param primalInstruction: the primal copy of the original source instruction
   :param primalIsRewritten: true when the primal copy is created specifically for the diff code (e.g. foo_nodiff), instead of being just a reference to the source (e.g. foo)
   :param diffInstructionSR: the (array of (replicas)) list of new differentiated instructions.
   :param suffix: The suffix used for differentiation. May be passed null when this is called not for differentiation but during fixImplicits preliminary phase.

setInterfaceUnits
^^^^^^^^^^^^^^^^^

.. java:method:: public void setInterfaceUnits(TapList<Unit> units)
   :outertype: Instruction

   Sets the interface Units associated to this interface declaration Instruction.

setPosition
^^^^^^^^^^^

.. java:method:: public void setPosition(Instruction refInstr)
   :outertype: Instruction

   Sets the "position" of this instruction to the same as of refInstr.

setTree
^^^^^^^

.. java:method:: public void setTree(Tree newTree)
   :outertype: Instruction

   Places newTree into this Instruction, and accordingly set annotation from newTree to Instruction

setWhereMask
^^^^^^^^^^^^

.. java:method:: public void setWhereMask(InstructionMask whereMask)
   :outertype: Instruction

   Sets a vectorial mask on this instruction.

syntaxControls
^^^^^^^^^^^^^^

.. java:method:: public boolean syntaxControls(Instruction controlled)
   :outertype: Instruction

   :return: true if this instruction syntactically controls "controlled".

thisCallIsCheckpointed
^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public boolean thisCallIsCheckpointed(Unit calledUnit)
   :outertype: Instruction

   :return: true if this instruction is a call that must be checkpointed (aka "joint mode")

toString
^^^^^^^^

.. java:method:: @Override public String toString()
   :outertype: Instruction

updateUnitDefinitionStub
^^^^^^^^^^^^^^^^^^^^^^^^

.. java:method:: public void updateUnitDefinitionStub(Unit definedUnit)
   :outertype: Instruction

   Update the given Instruction (which is a unit definition stub) so that it becomes a stub for this definedUnit.

usedUnits
^^^^^^^^^

.. java:method:: public static TapList<Unit> usedUnits(Tree tree, TapList<Unit> collected, SymbolTable symbolTable)
   :outertype: Instruction

whereMask
^^^^^^^^^

.. java:method:: public InstructionMask whereMask()
   :outertype: Instruction

   :return: the vectorial mask of this instruction, if any.

whereMaskDepth
^^^^^^^^^^^^^^

.. java:method:: public int whereMaskDepth()
   :outertype: Instruction

   :return: the nesting depth of this instruction's vectorial masks.