Symbol.hpp

Go to the documentation of this file.

//===- Symbol.hpp -----------------------------------------------*- C++ -*-===//
//
//  Copyright (C) 2020 GrammaTech, Inc.
//
//  This code is licensed under the MIT license. See the LICENSE file in the
//  project root for license terms.
//
//  This project is sponsored by the Office of Naval Research, One Liberty
//  Center, 875 N. Randolph Street, Arlington, VA 22203 under contract #
//  N68335-17-C-0700.  The content of the information does not necessarily
//  reflect the position or policy of the Government and no official
//  endorsement should be inferred.
//
//===----------------------------------------------------------------------===//
#ifndef GTIRB_SYMBOL_H
#define GTIRB_SYMBOL_H
 
#include <gtirb/Addr.hpp>
#include <gtirb/CodeBlock.hpp>
#include <gtirb/DataBlock.hpp>
#include <gtirb/Node.hpp>
#include <gtirb/ProxyBlock.hpp>
#include <functional>
#include <optional>
#include <type_traits>
#include <variant>
 
 
namespace gtirb {
namespace proto {
class Symbol;
}
 
template <class T> class ErrorOr;
class Module; // Forward declared for the backpointer.
class SymbolObserver;
 
class GTIRB_EXPORT_API Symbol : public Node {
  template <typename... Ts> struct TypeList {};
 
  // SFINAE overload handling a Callable with a void return type.
  template <typename Callable, typename Ty, typename CommonRetTy>
  auto visit_impl_help(Callable&& Visitor) const
      -> std::enable_if_t<std::is_void_v<CommonRetTy>, bool> {
    static_assert(std::is_invocable_v<Callable, Ty*>,
                  "Visitor must contain an overloaded function call operator "
                  "for each of the types in supported_types");
    if (Node* const* Ptr = std::get_if<Node*>(&Payload)) {
      if (Ty* Obj = dyn_cast_or_null<Ty>(*Ptr)) {
        std::invoke(Visitor, Obj);
        return true;
      }
    }
    return false;
  }
 
  // SFINAE overload handling a Callable with a non-void return type.
  template <typename Callable, typename Ty, typename CommonRetTy>
  bool
  visit_impl_help(Callable&& Visitor,
                  std::enable_if_t<!std::is_void_v<CommonRetTy>,
                                   std::optional<CommonRetTy>>& Ret) const {
    static_assert(std::is_invocable_v<Callable, Ty*>,
                  "Visitor must contain an overloaded function call operator "
                  "for each of the types in supported_types");
    if (Node* const* Ptr = std::get_if<Node*>(&Payload)) {
      if (Ty* Obj = dyn_cast_or_null<Ty>(*Ptr)) {
        Ret = std::invoke(Visitor, Obj);
        return true;
      }
    }
    return false;
  }
 
  // Helper type traits used to determine whether all of the Callable object's
  // return types agree. Note that the return types do not need to be the same,
  // but do need to be implicitly convertible to the same common type. e.g.,
  // this class is a valid Callable.
  //   struct Visitor {
  //     int operator()(Block*);
  //     long operator()(DataBlock*);
  //  };
  template <typename AlwaysVoid, typename Callable,
            template <typename...> typename TypeList, typename... Types>
  struct common_return_type_impl : std::false_type {};
 
  template <typename Callable, template <typename...> typename TypeList,
            typename... Types>
  struct common_return_type_impl<
      std::void_t<
          std::common_type_t<std::invoke_result_t<Callable, Types*>...>>,
      Callable, TypeList, Types...> : std::true_type {
    using type = std::common_type_t<std::invoke_result_t<Callable, Types*>...>;
  };
 
  template <typename Callable, template <typename...> typename TypeList,
            typename... Types>
  using common_return_type_t =
      typename common_return_type_impl<void, Callable, TypeList,
                                       Types...>::type;
 
  template <typename Callable, template <typename...> typename TypeList,
            typename... Types>
  static constexpr bool common_return_type_v =
      common_return_type_impl<void, Callable, TypeList, Types...>::value;
 
  // Helper function to unpack all of the types in the type list and attempt to
  // visit Callable once per type. Verifies that the Callable objects all share
  // a compatible return type.
  //
  // SFINAE overload handling a Callable where there is a common, non-void
  // return type. Returns a std::optional<common_type>.
  template <typename Callable, template <typename...> typename TypeList,
            typename... Types>
  auto visit_impl(Callable&& Visitor, TypeList<Types...>) const
      -> std::enable_if_t<
          !std::is_void_v<common_return_type_t<Callable, TypeList, Types...>>,
          std::optional<common_return_type_t<Callable, TypeList, Types...>>> {
    // If this assertion fails, the return values from the Callable object are
    // not compatible enough. This can happen if they return incompatible types
    // or if there is not an overload for each referent type.
    static_assert(common_return_type_v<Callable, TypeList, Types...>,
                  "incompatible return types for the Callable object");
    // Instantiate a call to the Visitor once for each of the listed types, but
    // only issue the call at runtime if the Referent can be dynamically cast to
    // the given type. In this way, the Visitor needs to be able to handle any
    // of the supported types, but will only be called once for the concrete
    // type of the Referent.
    //
    // If you get an error about there being no matching overloaded function for
    // the call to visit_impl_help, that is most likely because there are one
    // or more overloads missing for each referent type.
    std::optional<common_return_type_t<Callable, TypeList, Types...>> Res;
    (... ||
     visit_impl_help<Callable, Types, typename decltype(Res)::value_type>(
         std::forward<Callable>(Visitor), Res));
    return Res;
  }
 
  // SFINAE overload handling a Callable where every return type is void.
  // Returns void.
  template <typename Callable, template <typename...> typename TypeList,
            typename... Types>
  auto visit_impl(Callable&& Visitor, TypeList<Types...>) const
      -> std::enable_if_t<
          std::is_void_v<common_return_type_t<Callable, TypeList, Types...>>,
          void> {
    // Call each of the overloads on Callable, but there is no value to be
    // returned from any of the calls.
    (... ||
     visit_impl_help<Callable, Types, void>(std::forward<Callable>(Visitor)));
  }
 
  // Helper function that determines whether the passed NodeTy is the same as
  // any of the types in the Types... list.
  template <typename NodeTy, template <typename...> typename TypeList,
            typename... Types>
  static constexpr bool is_supported_type_impl(TypeList<Types...>) {
    return (... || std::is_same_v<NodeTy, Types>);
  }
 
public:
  // Helper function that determines whether the passed NodeTy is one of the
  // supported referent types.
  template <typename NodeTy> static constexpr bool is_supported_type() {
    return is_supported_type_impl<NodeTy>(
        std::decay_t<supported_referent_types>{});
  }
 
  using supported_referent_types = TypeList<CodeBlock, DataBlock, ProxyBlock>;
 
  template <typename Callable> auto visit(Callable&& Visitor) const {
    return visit_impl(std::forward<Callable>(Visitor),
                      std::decay_t<supported_referent_types>{});
  }
 
  static Symbol* Create(Context& C) { return C.Create<Symbol>(C); }
 
  static Symbol* Create(Context& C, const std::string& Name,
                        bool AtEnd = false) {
    return C.Create<Symbol>(C, Name, AtEnd);
  }
 
  static Symbol* Create(Context& C, Addr X, const std::string& Name,
                        bool AtEnd = false) {
    return C.Create<Symbol>(C, X, Name, AtEnd);
  }
 
  template <typename NodeTy>
  static Symbol* Create(Context& C, NodeTy* Referent, const std::string& Name,
                        bool AtEnd = false) {
    static_assert(is_supported_type<NodeTy>(), "unsupported referent type");
    return C.Create<Symbol>(C, Referent, Name, AtEnd);
  }
 
  Module* getModule() { return Parent; }
  const Module* getModule() const { return Parent; }
 
  std::optional<Addr> getAddress() const;
 
  const std::string& getName() const { return Name; }
 
  template <typename NodeTy> NodeTy* getReferent() {
    if (Node* const* Ptr = std::get_if<Node*>(&Payload))
      return dyn_cast_or_null<NodeTy>(*Ptr);
    return nullptr;
  }
 
  template <typename NodeTy> const NodeTy* getReferent() const {
    if (Node* const* Ptr = std::get_if<Node*>(&Payload))
      return dyn_cast_or_null<NodeTy>(*Ptr);
    return nullptr;
  }
 
  bool hasReferent() const { return std::holds_alternative<Node*>(Payload); }
 
  void setName(const std::string& N);
 
  template <typename NodeTy>
  std::enable_if_t<is_supported_type<NodeTy>()> setReferent(NodeTy* N) {
    setReferentFromNode(N);
  }
 
  void setAddress(Addr A);
 
  bool getAtEnd() const { return AtEnd; }
 
  void setAtEnd(bool AE) { AtEnd = AE; }
 
  static bool classof(const Node* N) { return N->getKind() == Kind::Symbol; }
 
private:
  Symbol(Context& C) : Node(C, Kind::Symbol) {}
  Symbol(Context& C, const std::string& N, bool AE)
      : Node(C, Kind::Symbol), Name(N), AtEnd(AE) {}
  Symbol(Context& C, const std::string& N, bool AE, const UUID& U)
      : Node(C, Kind::Symbol, U), Name(N), AtEnd(AE) {}
  Symbol(Context& C, Addr X, const std::string& N, bool AE)
      : Node(C, Kind::Symbol), Payload(X), Name(N), AtEnd(AE) {}
  template <typename NodeTy>
  Symbol(Context& C, NodeTy* R, const std::string& N, bool AE)
      : Node(C, Kind::Symbol), Payload(R), Name(N), AtEnd(AE) {
    if (!R) {
      Payload = std::monostate{};
    }
  }
 
  static Symbol* Create(Context& C, const std::string& Name, bool AtEnd,
                        const UUID& U) {
    return C.Create<Symbol>(C, Name, AtEnd, U);
  }
 
  void setParent(Module* M, SymbolObserver* O) {
    Parent = M;
    Observer = O;
  }
 
  void setReferentFromNode(Node* N);
 
  using MessageType = proto::Symbol;
 
  void toProtobuf(MessageType* Message) const;
 
  static ErrorOr<Symbol*> fromProtobuf(Context& C, const MessageType& Message);
 
  // Present for testing purposes only.
  void save(std::ostream& Out) const;
 
  // Present for testing purposes only.
  static Symbol* load(Context& C, std::istream& In);
 
  Module* Parent{nullptr};
  SymbolObserver* Observer{nullptr};
  std::variant<std::monostate, Addr, Node*> Payload;
  std::string Name;
  bool AtEnd = false;
 
  friend class Context; // Allow Context to construct Symbols.
  friend class Module;  // Allow Module to call setModule, Create, etc.
  // Allows serializaton from Module via containerToProtobuf.
  template <typename T> friend typename T::MessageType toProtobuf(const T&);
  friend class SerializationTestHarness; // Testing support.
};
 
 
class GTIRB_EXPORT_API SymbolObserver {
public:
  virtual ~SymbolObserver() = default;
 
  virtual ChangeStatus nameChange(Symbol* S, const std::string& OldName,
                                  const std::string& NewName) = 0;
 
  virtual ChangeStatus
  referentChange(Symbol* S,
                 std::variant<std::monostate, Addr, Node*> OldReferent,
                 std::variant<std::monostate, Addr, Node*> NewReferent) = 0;
};
 
inline void Symbol::setName(const std::string& N) {
  if (Observer) {
    std::string OldName(N);
    std::swap(Name, OldName);
    [[maybe_unused]] ChangeStatus Status =
        Observer->nameChange(this, OldName, Name);
    assert(Status != ChangeStatus::Rejected &&
           "recovering from rejected name change is unsupported");
  } else {
    Name = N;
  }
}
 
inline void Symbol::setAddress(Addr A) {
  if (Observer) {
    std::variant<std::monostate, Addr, Node*> OldValue = Payload;
    Payload = A;
    [[maybe_unused]] ChangeStatus Status =
        Observer->referentChange(this, OldValue, Payload);
    assert(Status != ChangeStatus::Rejected &&
           "recovering from rejected address change is unsupported");
  } else {
    Payload = A;
  }
}
 
inline void Symbol::setReferentFromNode(Node* N) {
  std::variant<std::monostate, Addr, Node*> OldValue = Payload;
  if (N) {
    Payload = N;
  } else {
    Payload = std::monostate{};
  }
  if (Observer) {
    [[maybe_unused]] ChangeStatus Status =
        Observer->referentChange(this, OldValue, Payload);
    assert(Status != ChangeStatus::Rejected &&
           "recovering from rejected referent change is unsupported");
  }
}
 
} // namespace gtirb
 
#endif // GTIRB_SYMBOL_H