var_handle.h

//   Copyright (c) 2018 PaddlePaddle Authors. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

#pragma once
#include <sstream>
#include <string>
#include <unordered_set>
#include <utility>

#include "paddle/fluid/platform/place.h"

namespace paddle {
namespace framework {
namespace details {
class OpHandleBase;

// VarHandleBase is the var node in the dependency graph.
// A variable can only be generated by a single operator. i.e.
// This is a single assignment graph.
struct VarHandleBase {
  virtual ~VarHandleBase();
  virtual std::string DebugString() const = 0;

  // The operator who generate this variable. nullptr if the variable
  // is a root node.
  OpHandleBase* generated_op_{nullptr};

  // Operators which depend on this variable ready.
  std::unordered_set<OpHandleBase*> pending_ops_;
};

// VarHandle is actually a single version of Runtime Variable.
// Variable in Runtime mapped to many VarHandles in Graph.
// Each assignment will generate a new var handle with newer version.
//
// NOTE: runtime variables have place.
struct VarHandle : public VarHandleBase {
  std::string DebugString() const override;

  VarHandle(size_t version, size_t scope_index, std::string name,
            platform::Place place)
      : version_(version),
        scope_idx_(scope_index),
        name_(std::move(name)),
        place_(std::move(place)) {}

  // version field currently is not used, however, just store the version to
  // debug easily.
  size_t version_;
  size_t scope_idx_;
  std::string name_;
  platform::Place place_;

  // NOTE(zcd): Strictly speaking, if the two var_handle is equal, the four
  // member
  // variables(version_, scope_id_, name_, place_) must be equal. But sometimes
  // judging whether the two var_handle is equal is actually to determine
  // whether
  // the two Variables that represented by var_handle is the same. And the same
  // Variable may have many different var_handles, the version_ of these
  // var_handles
  // is different. So I don't take care of version_ temporarily when overloading
  // equal.
  bool operator==(const VarHandle& o) const {
    return o.generated_op_ == generated_op_ && o.name_ == name_ &&
           o.scope_idx_ == scope_idx_;
  }

  bool operator!=(const VarHandle& o) const { return !this->operator==(o); }
};

// Dummy Variable. It is used to represent dependencies between operators
struct DummyVarHandle : public VarHandleBase {
  std::string DebugString() const override;
};

}  // namespace details
}  // namespace framework
}  // namespace paddle