Engine.hpp

// Copyright (c) 2015 Graphcore Ltd. All rights reserved.
 
#ifndef poplar_Engine_hpp
#define poplar_Engine_hpp
 
#include <gccs/CompilerFeatures.hpp>
#include <poplar/ArrayRef.hpp>
#include <poplar/Executable.hpp>
#include <poplar/Graph.hpp>
#include <poplar/HostFunctionCallback.hpp>
#include <poplar/Module.hpp>
#include <poplar/OptionFlags.hpp>
#include <poplar/ProfileValue.hpp>
#include <poplar/Program.hpp>
#include <poplar/Quarter.hpp>
#include <poplar/RuntimeOptions.hpp>
#include <poplar/StreamCallback.hpp>
#include <poplar/StringRef.hpp>
#include <poplar/Type.hpp>
 
#include <functional>
#include <iosfwd>
#include <memory>
#include <type_traits>
#include <vector>
 
namespace pva {
class Report;
}
namespace poplar {
namespace core {
class Engine;
class TimerTimePoint;
} // namespace core
 
class Preallocations;
 
using ProgressFunc = std::function<void(int, int)>;
 
const static unsigned WORKER_SCRATCH_SIZE = 48;
 
class Engine {
public:
  using ProgressFunc = std::function<void(int, int)>;
 
  Engine(Graph &&graph, ArrayRef<program::Program> progs,
         const OptionFlags &opt = {},
         ProgressFunc progressCallBack = ProgressFunc(),
         const DebugContext &debugContext = {});
  Engine(const Graph &graph, ArrayRef<program::Program> progs,
         const OptionFlags &opt = {},
         ProgressFunc progressCallBack = ProgressFunc(),
         const DebugContext &debugContext = {});
 
  Engine(Graph &&graph, program::Program prog, const OptionFlags &opt = {},
         ProgressFunc progressCallBack = ProgressFunc(),
         const DebugContext &debugContext = {});
  Engine(const Graph &graph, program::Program prog, const OptionFlags &opt = {},
         ProgressFunc progressCallBack = ProgressFunc(),
         const DebugContext &debugContext = {});
 
  Engine(Executable &&exe, const OptionFlags &opt = {});
 
  // Move constructor
  Engine(Engine &&) noexcept;
 
  ~Engine();
 
  void prepare(const Device &device);
 
  void prepare(const Device &device, const RuntimeOptions &runOptions);
 
  void deploy();
 
  void load(const Device &device);
 
  void run(unsigned prog = 0, const std::string &debugName = "");
 
  void stop();
 
  void run(unsigned prog, const std::string &debugName,
           const RuntimeOptions &options);
 
  void loadAndRun(const Device &device, unsigned prog = 0);
 
  class TimerTimePoint {
  public:
    TimerTimePoint() = default;
 
  private:
    std::shared_ptr<core::TimerTimePoint> impl;
    explicit TimerTimePoint(Engine &e);
    friend class Engine;
  };
 
  TimerTimePoint getTimeStamp();
 
  static std::string reportTiming(const TimerTimePoint &start,
                                  const TimerTimePoint &end);
 
  GC_DEPRECATED void resetExecutionProfile();
 
  pva::Report getReport(bool reportExecution = true);
 
  void disableExecutionProfiling();
 
  void enableExecutionProfiling();
 
  void printProfileSummary(std::ostream &outputStream,
                           const OptionFlags &opt = {});
 
  void reportIntervals(std::ostream &outputStream);
 
  void readTensor(StringRef handle, void *buf, void *bufEnd);
 
  void readTensor(StringRef handle, QuarterMetadata &metadata, void *buf,
                  void *bufEnd);
 
  template <class T>
  void readTensor(StringRef handle, gccs::ArrayRef<T> buffer) {
    using HostType = typename std::decay<T>::type;
    static_assert(not std::is_const<T>::value,
                  "readTensor requires a writable buffer");
    auto cast = [](T *p) {
      return const_cast<void *>(static_cast<const void *>(p));
    };
    copyTensor(handle, equivalent_device_type<HostType>().value, true,
               cast(buffer.begin()), cast(buffer.end()));
  }
 
  void writeTensor(StringRef handle, const void *buf, const void *bufEnd);
 
  void writeTensor(StringRef handle, const QuarterMetadata &metadata,
                   const void *buf, const void *bufEnd);
 
  template <class T> void writeTensor(StringRef handle, ArrayRef<T> buffer) {
    using HostType = typename std::decay<T>::type;
    auto cast = [](const T *p) {
      return const_cast<void *>(static_cast<const void *>(p));
    };
    copyTensor(handle, equivalent_device_type<HostType>().value, false,
               cast(buffer.begin()), cast(buffer.end()));
  }
 
  void connectStream(StringRef handle, void *begin, void *end);
 
  void connectStream(StringRef handle,
                     const gccs::ArrayRef<QuarterMetadata> &metadata,
                     void *begin, void *end);
 
  template <class T>
  void connectStream(StringRef handle, const gccs::ArrayRef<T> &buffer) {
    using HostType = typename std::decay<T>::type;
    auto cast = [](T *p) {
      return const_cast<void *>(static_cast<const void *>(p));
    };
    connectStream(handle, &equivalent_device_type<HostType>().value, {},
                  std::is_const<T>::value, cast(buffer.begin()),
                  cast(buffer.end()));
  }
 
  void connectStream(StringRef handle, void *p);
 
  void connectStreamToCallback(StringRef handle, StreamCallbackHandle f);
 
  void connectStreamToCallback(StringRef handle, unsigned index,
                               StreamCallbackHandle f);
 
  void connectHostFunction(StringRef handle, unsigned index,
                           HostCallbackHandle f);
 
  void copyFromRemoteBuffer(StringRef handle, void *w, uint64_t repeatIndex,
                            unsigned replicationIndex = 0);
 
  template <class T>
  void copyFromRemoteBuffer(StringRef handle, gccs::ArrayRef<T> buffer,
                            uint64_t repeatIndex,
                            unsigned replicationIndex = 0) {
    static_assert(not std::is_const<T>::value,
                  "Engine::copyFromRemoteBuffer requires a writable buffer");
    auto cast = [](T *p) {
      return const_cast<void *>(static_cast<const void *>(p));
    };
    using HostType = typename std::decay<T>::type;
    copyRemoteBuffer(handle, repeatIndex, replicationIndex,
                     &equivalent_device_type<HostType>().value, true,
                     cast(buffer.begin()), buffer.size());
  }
 
  void copyToRemoteBuffer(void *w, StringRef handle, uint64_t repeatIndex,
                          unsigned replicationIndex = 0);
 
  template <class T>
  void copyToRemoteBuffer(ArrayRef<T> buffer, StringRef handle,
                          uint64_t repeatIndex, unsigned replicationIndex = 0) {
    auto cast = [](T *p) {
      return const_cast<void *>(static_cast<const void *>(p));
    };
    using HostType = typename std::decay<T>::type;
    copyRemoteBuffer(handle, repeatIndex, replicationIndex,
                     &equivalent_device_type<HostType>().value, false,
                     cast(buffer.begin()), buffer.size());
  }
 
  std::vector<std::string> listStreams() const;
 
  void setPrintStream(std::ostream &stream);
 
  void setPrintTensorStream(std::ostream &stream);
 
  OptionFlags getEngineOptions() const;
 
  void serializeExecutable(std::ostream &out) const;
 
  void insertSimulatedError(ErrorCode error, ErrorLocation const &location);
 
  void eraseSimulatedError(ErrorLocation const &location);
 
  void clearSimulatedErrors();
 
  std::vector<ErrorLocation>
  getSimulatedErrorLocations(unsigned programId, unsigned tile = ~0) const;
 
  std::vector<ErrorLocation>
  getSimulatedErrorLocations(StringRef vertexName, unsigned tile = ~0) const;
 
  // Implementation
  Engine(std::unique_ptr<core::Engine>);
  const core::Engine &getImpl() const { return *impl; }
 
private:
  void connectStream(StringRef handle, const Type *type,
                     const gccs::ArrayRef<QuarterMetadata> &metadatas,
                     bool readOnly, void *begin, void *end);
 
  void copyTensor(StringRef handle, const Type &type, bool read, void *begin,
                  void *end);
 
  void copyTensor(StringRef handle, const Type &type, QuarterMetadata *metadata,
                  bool read, void *begin, void *end);
 
  void readTensor(StringRef handle, void *metadata, void *buf, void *bufEnd);
 
  void writeTensor(StringRef handle, void *metadata, const void *buf,
                   const void *bufEnd);
 
  void copyRemoteBuffer(StringRef handle, unsigned repeatIndex,
                        unsigned replicationIndex, const Type *type, bool read,
                        void *begin, size_t numElements);
 
  std::unique_ptr<core::Engine> impl;
};
 
Executable compileGraph(Graph &&graph, ArrayRef<program::Program> progs,
                        const OptionFlags &opt = {},
                        ProgressFunc progressCallBack = ProgressFunc(),
                        const DebugContext &debugContext = {});
Executable compileGraph(const Graph &graph, ArrayRef<program::Program> progs,
                        const OptionFlags &opt = {},
                        ProgressFunc progressCallBack = ProgressFunc(),
                        const DebugContext &debugContext = {});
 
Module compileModule(Graph &&graph, program::Program prog,
                     const OptionFlags &opt = {},
                     ProgressFunc progressCallBack = ProgressFunc(),
                     const DebugContext &debugContext = {});
Module compileModule(const Graph &graph, program::Program prog,
                     const OptionFlags &opt = {},
                     ProgressFunc progressCallBack = ProgressFunc(),
                     const DebugContext &debugContext = {});
 
Module compileModule(Graph &&graph, program::Program prog,
                     const Preallocations &preallocations,
                     const OptionFlags &opt = {},
                     ProgressFunc progressCallBack = ProgressFunc(),
                     const DebugContext &debugContext = {});
Module compileModule(const Graph &graph, program::Program prog,
                     const Preallocations &preallocations,
                     const OptionFlags &opt = {},
                     ProgressFunc progressCallBack = ProgressFunc(),
                     const DebugContext &debugContext = {});
 
Executable compileGraph(Graph &&graph, ArrayRef<program::Program> progs,
                        const Preallocations &preallocations,
                        const OptionFlags &opt = {},
                        ProgressFunc progressCallBack = ProgressFunc(),
                        const DebugContext &debugContext = {});
Executable compileGraph(const Graph &graph, ArrayRef<program::Program> progs,
                        const Preallocations &preallocations,
                        const OptionFlags &opt = {},
                        ProgressFunc progressCallBack = ProgressFunc(),
                        const DebugContext &debugContext = {});
 
} // End namespace poplar.
 
#endif // poplar_Engine_hpp