IR: Cleanup comments for Value, User, and MDNode

};

//===----------------------------------------------------------------------===//

/// MDString - a single uniqued string.

/// \brief A single uniqued string.

///

/// These are used to efficiently contain a byte sequence for metadata.

/// MDString is always unnamed.

class MDString : public Value {

  typedef StringRef::iterator iterator;

  /// begin() - Pointer to the first byte of the string.

  /// \brief Pointer to the first byte of the string.

  iterator begin() const { return getName().begin(); }

  /// end() - Pointer to one byte past the end of the string.

  /// \brief Pointer to one byte past the end of the string.

  iterator end() const { return getName().end(); }

  /// Methods for support type inquiry through isa, cast, and dyn_cast:

  /// \brief Methods for support type inquiry through isa, cast, and dyn_cast.

  static bool classof(const Value *V) {

    return V->getValueID() == MDStringVal;

  }

};

/// AAMDNodes - A collection of metadata nodes that might be associated with a

/// \brief A collection of metadata nodes that might be associated with a

/// memory access used by the alias-analysis infrastructure.

struct AAMDNodes {

  explicit AAMDNodes(MDNode *T = nullptr, MDNode *S = nullptr,

  LLVM_EXPLICIT operator bool() const { return TBAA || Scope || NoAlias; }

  /// TBAA - The tag for type-based alias analysis.

  /// \brief The tag for type-based alias analysis.

  MDNode *TBAA;

  /// Scope - The tag for alias scope specification (used with noalias).

  /// \brief The tag for alias scope specification (used with noalias).

  MDNode *Scope;

  /// NoAlias - The tag specifying the noalias scope.

  /// \brief The tag specifying the noalias scope.

  MDNode *NoAlias;

};

class MDNodeOperand;

//===----------------------------------------------------------------------===//

/// MDNode - a tuple of other values.

/// \brief A tuple of other values.

class MDNode : public Value, public FoldingSetNode {

  MDNode(const MDNode &) LLVM_DELETED_FUNCTION;

  void operator=(const MDNode &) LLVM_DELETED_FUNCTION;

  friend class LLVMContextImpl;

  friend struct FoldingSetTrait<MDNode>;

  /// Hash - If the MDNode is uniqued cache the hash to speed up lookup.

  /// \brief If the MDNode is uniqued cache the hash to speed up lookup.

  unsigned Hash;

  /// NumOperands - This many 'MDNodeOperand' items are co-allocated onto the

  /// end of this MDNode.

  /// \brief Number of co-allocated 'MDNodeOperand' items.

  unsigned NumOperands;

  // Subclass data enums.

  /// \brief Subclass data enums.

  enum {

    /// FunctionLocalBit - This bit is set if this MDNode is function local.

    /// This is true when it (potentially transitively) contains a reference to

    DestroyFlag      = 1 << 2

  };

  // FunctionLocal enums.

  /// \brief FunctionLocal enums.

  enum FunctionLocalness {

    FL_Unknown = -1,

    FL_No = 0,

    FL_Yes = 1

  };

  /// replaceOperand - Replace each instance of F from the operand list of this

  /// node with T.

  /// \brief Replace each instance of the given operand with a new value.

  void replaceOperand(MDNodeOperand *Op, Value *NewVal);

  ~MDNode();

  static MDNode *getMDNode(LLVMContext &C, ArrayRef<Value*> Vals,

                           FunctionLocalness FL, bool Insert = true);

public:

  // Constructors and destructors.

  static MDNode *get(LLVMContext &Context, ArrayRef<Value*> Vals);

  // getWhenValsUnresolved - Construct MDNode determining function-localness

  // from isFunctionLocal argument, not by analyzing Vals.

  /// \brief Construct MDNode with an explicit function-localness.

  ///

  /// Don't analyze Vals; trust isFunctionLocal.

  static MDNode *getWhenValsUnresolved(LLVMContext &Context,

                                       ArrayRef<Value*> Vals,

                                       bool isFunctionLocal);

  static MDNode *getIfExists(LLVMContext &Context, ArrayRef<Value*> Vals);

  /// getTemporary - Return a temporary MDNode, for use in constructing

  /// cyclic MDNode structures. A temporary MDNode is not uniqued,

  /// may be RAUW'd, and must be manually deleted with deleteTemporary.

  /// \brief Return a temporary MDNode

  ///

  /// For use in constructing cyclic MDNode structures. A temporary MDNode is

  /// not uniqued, may be RAUW'd, and must be manually deleted with

  /// deleteTemporary.

  static MDNode *getTemporary(LLVMContext &Context, ArrayRef<Value*> Vals);

  /// deleteTemporary - Deallocate a node created by getTemporary. The

  /// node must not have any users.

  /// \brief Deallocate a node created by getTemporary.

  ///

  /// The node must not have any users.

  static void deleteTemporary(MDNode *N);

  /// replaceOperandWith - Replace a specific operand.

  /// \brief Replace a specific operand.

  void replaceOperandWith(unsigned i, Value *NewVal);

  /// getOperand - Return specified operand.

  /// \brief Return specified operand.

  Value *getOperand(unsigned i) const LLVM_READONLY;

  /// getNumOperands - Return number of MDNode operands.

  /// \brief Return number of MDNode operands.

  unsigned getNumOperands() const { return NumOperands; }

  /// isFunctionLocal - Return whether MDNode is local to a function.

  /// \brief Return whether MDNode is local to a function.

  bool isFunctionLocal() const {

    return (getSubclassDataFromValue() & FunctionLocalBit) != 0;

  }

  // getFunction - If this metadata is function-local and recursively has a

  // function-local operand, return the first such operand's parent function.

  // Otherwise, return null. getFunction() should not be used for performance-

  // critical code because it recursively visits all the MDNode's operands.

  /// \brief Return the first function-local operand's function.

  ///

  /// If this metadata is function-local and recursively has a function-local

  /// operand, return the first such operand's parent function.  Otherwise,

  /// return null. getFunction() should not be used for performance- critical

  /// code because it recursively visits all the MDNode's operands.

  const Function *getFunction() const;

  /// Profile - calculate a unique identifier for this MDNode to collapse

  /// duplicates

  /// \brief Calculate a unique identifier for this MDNode.

  void Profile(FoldingSetNodeID &ID) const;

  /// Methods for support type inquiry through isa, cast, and dyn_cast:

  /// \brief Methods for support type inquiry through isa, cast, and dyn_cast:

  static bool classof(const Value *V) {

    return V->getValueID() == MDNodeVal;

  }

  /// Check whether MDNode is a vtable access.

  /// \brief Check whether MDNode is a vtable access.

  bool isTBAAVtableAccess() const;

  /// Methods for metadata merging.

  /// \brief Methods for metadata merging.

  static MDNode *concatenate(MDNode *A, MDNode *B);

  static MDNode *intersect(MDNode *A, MDNode *B);

  static MDNode *getMostGenericTBAA(MDNode *A, MDNode *B);

  static MDNode *getMostGenericFPMath(MDNode *A, MDNode *B);

  static MDNode *getMostGenericRange(MDNode *A, MDNode *B);

private:

  // destroy - Delete this node.  Only when there are no uses.

  /// \brief Delete this node.  Only when there are no uses.

  void destroy();

  bool isNotUniqued() const {

};

//===----------------------------------------------------------------------===//

/// NamedMDNode - a tuple of MDNodes. Despite its name, a NamedMDNode isn't

/// itself an MDNode. NamedMDNodes belong to modules, have names, and contain

/// lists of MDNodes.

/// \brief A tuple of MDNodes.

///

/// Despite its name, a NamedMDNode isn't itself an MDNode. NamedMDNodes belong

/// to modules, have names, and contain lists of MDNodes.

class NamedMDNode : public ilist_node<NamedMDNode> {

  friend class SymbolTableListTraits<NamedMDNode, Module>;

  friend struct ilist_traits<NamedMDNode>;

  };

public:

  /// eraseFromParent - Drop all references and remove the node from parent

  /// module.

  /// \brief Drop all references and remove the node from parent module.

  void eraseFromParent();

  /// dropAllReferences - Remove all uses and clear node vector.

  /// \brief Remove all uses and clear node vector.

  void dropAllReferences();

  /// ~NamedMDNode - Destroy NamedMDNode.

  ~NamedMDNode();

  /// getParent - Get the module that holds this named metadata collection.

  /// \brief Get the module that holds this named metadata collection.

  inline Module *getParent() { return Parent; }

  inline const Module *getParent() const { return Parent; }

  /// getOperand - Return specified operand.

  MDNode *getOperand(unsigned i) const;

  /// getNumOperands - Return the number of NamedMDNode operands.

  unsigned getNumOperands() const;

  /// addOperand - Add metadata operand.

  void addOperand(MDNode *M);

  /// getName - Return a constant reference to this named metadata's name.

  StringRef getName() const;

  /// print - Implement operator<< on NamedMDNode.

  void print(raw_ostream &ROS) const;

  /// dump() - Allow printing of NamedMDNodes from the debugger.

  void dump() const;

  // ---------------------------------------------------------------------------

namespace llvm {

/// OperandTraits - Compile-time customization of

/// operand-related allocators and accessors

/// for use of the User class

/// \brief Compile-time customization of User operands.

///

/// Customizes operand-related allocators and accessors.

template <class>

struct OperandTraits;

  friend struct HungoffOperandTraits;

  virtual void anchor();

protected:

  /// NumOperands - The number of values used by this User.

  ///

  /// \brief The number of values used by this User.

  unsigned NumOperands;

  /// OperandList - This is a pointer to the array of Uses for this User.

  /// \brief This is a pointer to the array of Uses for this User.

  ///

  /// For nodes of fixed arity (e.g. a binary operator) this array will live

  /// prefixed to some derived class instance.  For nodes of resizable variable

  /// arity (e.g. PHINodes, SwitchInst etc.), this memory will be dynamically

  ~User() {

    Use::zap(OperandList, OperandList + NumOperands);

  }

  /// operator delete - free memory allocated for User and Use objects

  /// \brief Free memory allocated for User and Use objects.

  void operator delete(void *Usr);

  /// placement delete - required by std, but never called.

  /// \brief Placement delete - required by std, but never called.

  void operator delete(void*, unsigned) {

    llvm_unreachable("Constructor throws?");

  }

  /// placement delete - required by std, but never called.

  /// \brief Placement delete - required by std, but never called.

  void operator delete(void*, unsigned, bool) {

    llvm_unreachable("Constructor throws?");

  }

    return const_op_range(op_begin(), op_end());

  }

  /// Convenience iterator for directly iterating over the Values in the

  /// OperandList

  /// \brief Iterator for directly iterating over the operand Values.

  struct value_op_iterator

      : iterator_adaptor_base<value_op_iterator, op_iterator,

                              std::random_access_iterator_tag, Value *,

    return iterator_range<value_op_iterator>(value_op_begin(), value_op_end());

  }

  // dropAllReferences() - This function is in charge of "letting go" of all

  // objects that this User refers to.  This allows one to

  // 'delete' a whole class at a time, even though there may be circular

  // references...  First all references are dropped, and all use counts go to

  // zero.  Then everything is deleted for real.  Note that no operations are

  // valid on an object that has "dropped all references", except operator

  // delete.

  //

  /// \brief Drop all references to operands.

  ///

  /// This function is in charge of "letting go" of all objects that this User

  /// refers to.  This allows one to 'delete' a whole class at a time, even

  /// though there may be circular references...  First all references are

  /// dropped, and all use counts go to zero.  Then everything is deleted for

  /// real.  Note that no operations are valid on an object that has "dropped

  /// all references", except operator delete.

  void dropAllReferences() {

    for (Use &U : operands())

      U.set(nullptr);

  }

  /// replaceUsesOfWith - Replaces all references to the "From" definition with

  /// references to the "To" definition.

  /// \brief Replace uses of one Value with another.

  ///

  /// Replaces all references to the "From" definition with references to the

  /// "To" definition.

  void replaceUsesOfWith(Value *From, Value *To);

  // Methods for support type inquiry through isa, cast, and dyn_cast:

  enum { NumLowBitsAvailable = 2 };

};

/// ValueHandleBase - This is the common base class of value handles.

/// \brief This is the common base class of value handles.

///

/// ValueHandle's are smart pointers to Value's that have special behavior when

/// the value is deleted or ReplaceAllUsesWith'd.  See the specific handles

/// below for details.

///

class ValueHandleBase {

  friend class Value;

protected:

  /// HandleBaseKind - This indicates what sub class the handle actually is.

  /// \brief This indicates what sub class the handle actually is.

  ///

  /// This is to avoid having a vtable for the light-weight handle pointers. The

  /// fully general Callback version does have a vtable.

  enum HandleBaseKind {

  HandleBaseKind getKind() const { return PrevPair.getInt(); }

  void setPrevPtr(ValueHandleBase **Ptr) { PrevPair.setPointer(Ptr); }

  /// AddToExistingUseList - Add this ValueHandle to the use list for VP, where

  /// \brief Add this ValueHandle to the use list for VP.

  ///

  /// List is the address of either the head of the list or a Next node within

  /// the existing use list.

  void AddToExistingUseList(ValueHandleBase **List);

  /// AddToExistingUseListAfter - Add this ValueHandle to the use list after

  /// Node.

  /// \brief Add this ValueHandle to the use list after Node.

  void AddToExistingUseListAfter(ValueHandleBase *Node);

  /// AddToUseList - Add this ValueHandle to the use list for VP.

  /// \brief Add this ValueHandle to the use list for VP.

  void AddToUseList();

  /// RemoveFromUseList - Remove this ValueHandle from its current use list.

  /// \brief Remove this ValueHandle from its current use list.

  void RemoveFromUseList();

};

/// WeakVH - This is a value handle that tries hard to point to a Value, even

/// across RAUW operations, but will null itself out if the value is destroyed.

/// this is useful for advisory sorts of information, but should not be used as

/// the key of a map (since the map would have to rearrange itself when the

/// pointer changes).

/// \brief Value handle that is nullable, but tries to track the Value.

///

/// This is a value handle that tries hard to point to a Value, even across

/// RAUW operations, but will null itself out if the value is destroyed.  this

/// is useful for advisory sorts of information, but should not be used as the

/// key of a map (since the map would have to rearrange itself when the pointer

/// changes).

class WeakVH : public ValueHandleBase {

public:

  WeakVH() : ValueHandleBase(Weak) {}

  }

};

/// AssertingVH - This is a Value Handle that points to a value and asserts out

/// if the value is destroyed while the handle is still live.  This is very

/// useful for catching dangling pointer bugs and other things which can be

/// non-obvious.  One particularly useful place to use this is as the Key of a

/// map.  Dangling pointer bugs often lead to really subtle bugs that only occur

/// if another object happens to get allocated to the same address as the old

/// one.  Using an AssertingVH ensures that an assert is triggered as soon as

/// the bad delete occurs.

/// \brief Value handle that asserts if the Value is deleted.

///

/// This is a Value Handle that points to a value and asserts out if the value

/// is destroyed while the handle is still live.  This is very useful for

/// catching dangling pointer bugs and other things which can be non-obvious.

/// One particularly useful place to use this is as the Key of a map.  Dangling

/// pointer bugs often lead to really subtle bugs that only occur if another

/// object happens to get allocated to the same address as the old one.  Using

/// an AssertingVH ensures that an assert is triggered as soon as the bad

/// delete occurs.

///

/// Note that an AssertingVH handle does *not* follow values across RAUW

/// operations.  This means that RAUW's need to explicitly update the

};

/// TrackingVH - This is a value handle that tracks a Value (or Value subclass),

/// even across RAUW operations.

/// \brief Value handle that tracks a Value across RAUW.

///

/// TrackingVH is designed for situations where a client needs to hold a handle

/// to a Value (or subclass) across some operations which may move that value,

  ValueTy &operator*() const { return *getValPtr(); }

};

/// CallbackVH - This is a value handle that allows subclasses to define

/// callbacks that run when the underlying Value has RAUW called on it or is

/// destroyed.  This class can be used as the key of a map, as long as the user

/// takes it out of the map before calling setValPtr() (since the map has to

/// rearrange itself when the pointer changes).  Unlike ValueHandleBase, this

/// class has a vtable and a virtual destructor.

/// \brief Value handle with callbacks on RAUW and destruction.

///

/// This is a value handle that allows subclasses to define callbacks that run

/// when the underlying Value has RAUW called on it or is destroyed.  This

/// class can be used as the key of a map, as long as the user takes it out of

/// the map before calling setValPtr() (since the map has to rearrange itself

/// when the pointer changes).  Unlike ValueHandleBase, this class has a vtable

/// and a virtual destructor.

class CallbackVH : public ValueHandleBase {

  virtual void anchor();

protected:

    return getValPtr();

  }

  /// Called when this->getValPtr() is destroyed, inside ~Value(), so you may

  /// call any non-virtual Value method on getValPtr(), but no subclass methods.

  /// If WeakVH were implemented as a CallbackVH, it would use this method to

  /// call setValPtr(NULL).  AssertingVH would use this method to cause an

  /// assertion failure.

  /// \brief Callback for Value destruction.

  ///

  /// Called when this->getValPtr() is destroyed, inside ~Value(), so you

  /// may call any non-virtual Value method on getValPtr(), but no subclass

  /// methods.  If WeakVH were implemented as a CallbackVH, it would use this

  /// method to call setValPtr(NULL).  AssertingVH would use this method to

  /// cause an assertion failure.

  ///

  /// All implementations must remove the reference from this object to the

  /// Value that's being destroyed.

  virtual void deleted() { setValPtr(nullptr); }

  /// \brief Callback for Value RAUW.

  ///

  /// Called when this->getValPtr()->replaceAllUsesWith(new_value) is called,

  /// _before_ any of the uses have actually been replaced.  If WeakVH were

  /// implemented as a CallbackVH, it would use this method to call

    this->setAsFirstOperand(IsFirst);

  }

  /// setAsFirstOperand - Accessor method to mark the operand as the first in

  /// the list.

  /// \brief Accessor method to mark the operand as the first in the list.

  void setAsFirstOperand(unsigned V) { this->setValPtrInt(V); }

  void deleted() override;

// MDNode implementation.

//

/// getOperandPtr - Helper function to get the MDNodeOperand's coallocated on

/// the end of the MDNode.

/// \brief Get the MDNodeOperand's coallocated on the end of the MDNode.

static MDNodeOperand *getOperandPtr(MDNode *N, unsigned Op) {

  // Use <= instead of < to permit a one-past-the-end address.

  assert(Op <= N->getNumOperands() && "Invalid operand number");

  free(this);

}

/// isFunctionLocalValue - Return true if this is a value that would require a

/// function-local MDNode.

/// \brief Check if the Value  would require a function-local MDNode.

static bool isFunctionLocalValue(Value *V) {

  return isa<Instruction>(V) || isa<Argument>(V) || isa<BasicBlock>(V) ||

         (isa<MDNode>(V) && cast<MDNode>(V)->isFunctionLocal());

  N->destroy();

}

/// getOperand - Return specified operand.

/// \brief Return specified operand.

Value *MDNode::getOperand(unsigned i) const {

  assert(i < getNumOperands() && "Invalid operand number");

  return *getOperandPtr(const_cast<MDNode*>(this), i);

  delete &getNMDOps(Operands);

}

/// getNumOperands - Return number of NamedMDNode operands.

unsigned NamedMDNode::getNumOperands() const {

  return (unsigned)getNMDOps(Operands).size();

}

/// getOperand - Return specified operand.

MDNode *NamedMDNode::getOperand(unsigned i) const {

  assert(i < getNumOperands() && "Invalid Operand number!");

  return dyn_cast<MDNode>(&*getNMDOps(Operands)[i]);

}

/// addOperand - Add metadata Operand.

void NamedMDNode::addOperand(MDNode *M) {

  assert(!M->isFunctionLocal() &&

         "NamedMDNode operands must not be function-local!");

  getNMDOps(Operands).push_back(TrackingVH<MDNode>(M));

}

/// eraseFromParent - Drop all references and remove the node from parent

/// module.

void NamedMDNode::eraseFromParent() {

  getParent()->eraseNamedMetadata(this);

}

/// dropAllReferences - Remove all uses and clear node vector.

void NamedMDNode::dropAllReferences() {

  getNMDOps(Operands).clear();

}

/// getName - Return a constant reference to this named metadata's name.

StringRef NamedMDNode::getName() const {

  return StringRef(Name);

}