Add tint::Program as a wrapper of tint::ast::Module.

`tint::Program` will become the new public API object for a parsed shader program.
For now, have Program be a simple wrapper around ast::Module so we can migrate Dawn's use of the public tint API.

Add new Program variants of public APIs for places that returned or took a Module.

Remove Reset() methods from Generators, they aren't used, and make the migration harder.

Change-Id: Ic5bee46ceb109ea591ba7fec33685220b244a1ae
Reviewed-on: https://dawn-review.googlesource.com/c/tint/+/38540
Reviewed-by: dan sinclair <dsinclair@chromium.org>
Commit-Queue: Ben Clayton <bclayton@google.com>

BUILD.gn

@@ -373,6 +373,7 @@ source_set("libtint_core_src") {
     "src/inspector/scalar.h",
     "src/namer.cc",
     "src/namer.h",
+    "src/program.h",
     "src/reader/reader.cc",
     "src/reader/reader.h",
     "src/scope_stack.h",

src/CMakeLists.txt

@@ -187,6 +187,7 @@ set(TINT_LIB_SRCS
   inspector/scalar.h
   namer.cc
   namer.h
+  program.h
   reader/reader.cc
   reader/reader.h
   scope_stack.h

src/inspector/inspector.cc

@@ -45,6 +45,8 @@ namespace inspector {
 
 Inspector::Inspector(const ast::Module& module) : module_(module) {}
 
+Inspector::Inspector(const Program* program) : Inspector(program->module) {}
+
 Inspector::~Inspector() = default;
 
 std::vector<EntryPoint> Inspector::GetEntryPoints() {

src/inspector/inspector.h

@@ -25,6 +25,7 @@
 #include "src/ast/pipeline_stage.h"
 #include "src/inspector/entry_point.h"
 #include "src/inspector/scalar.h"
+#include "src/program.h"
 
 namespace tint {
 namespace inspector {
@@ -73,6 +74,12 @@ class Inspector {
   /// Constructor
   /// @param module Shader module to extract information from.
   explicit Inspector(const ast::Module& module);
+
+  /// Constructor
+  /// @param program Shader program to extract information from.
+  explicit Inspector(const Program* program);
+
+  /// Destructor
   ~Inspector();
 
   /// @returns error messages from the Inspector

src/program.h

@@ -0,0 +1,41 @@
+// Copyright 2021 The Tint Authors.
+//
+// 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.
+
+#ifndef SRC_PROGRAM_H_
+#define SRC_PROGRAM_H_
+
+#include <string>
+
+#include "src/ast/module.h"
+
+namespace tint {
+
+/// Program is (currently) a simple wrapper of to ast::Module.
+/// This wrapper is used as a stepping stone to having Dawn use tint::Program
+/// instead of tint::ast::Module.
+class Program {
+ public:
+  /// The wrapped module
+  ast::Module module;
+
+  /// @returns true if all required fields in the module are present.
+  bool IsValid() const { return module.IsValid(); }
+
+  /// @return a deep copy of this program
+  Program Clone() const { return Program{module.Clone()}; }
+};
+
+}  // namespace tint
+
+#endif  // SRC_PROGRAM_H_

src/reader/reader.h

@@ -21,6 +21,7 @@
 #include "src/ast/module.h"
 #include "src/diagnostic/diagnostic.h"
 #include "src/diagnostic/formatter.h"
+#include "src/program.h"
 
 namespace tint {
 namespace reader {
@@ -49,6 +50,9 @@ class Reader {
   /// @returns the module. The module in the parser will be reset after this.
   virtual ast::Module module() = 0;
 
+  /// @returns the program. The module in the parser will be reset after this.
+  Program program() { return Program{module()}; }
+
  protected:
   /// Constructor
   Reader();

src/transform/manager.h

@@ -46,6 +46,14 @@ class Manager : public Transform {
   /// @returns the transformed module and diagnostics
   Output Run(ast::Module* module) override;
 
+  /// Runs the transform on `program`, returning the transformation result.
+  /// @note Users of Tint should register the transform with transform manager
+  /// and invoke its Run(), instead of directly calling the transform's Run().
+  /// Calling Run() directly does not perform program state cleanup operations.
+  /// @param program the source program to transform
+  /// @returns the transformation result
+  Output Run(Program* program) { return Run(&program->module); }
+
  private:
   std::vector<std::unique_ptr<Transform>> transforms_;
 };

src/transform/transform.cc

@@ -21,7 +21,27 @@
 namespace tint {
 namespace transform {
 
+Transform::Output::Output() = default;
+
+Transform::Output::Output(ast::Module&& mod) : program{std::move(mod)} {}
+
+Transform::Output::Output(ast::Module&& mod, diag::List&& d)
+    : program{std::move(mod)}, diagnostics(std::move(d)) {}
+
+Transform::Output::~Output() = default;
+
+Transform::Output::Output(Output&& rhs)
+    : program(std::move(rhs.program)),
+      diagnostics(std::move(rhs.diagnostics)) {}
+
+Transform::Output& Transform::Output::operator=(Output&& rhs) {
+  program = std::move(rhs.program);
+  diagnostics = std::move(rhs.diagnostics);
+  return *this;
+}
+
 Transform::Transform() = default;
+
 Transform::~Transform() = default;
 
 ast::Function* Transform::CloneWithStatementsAtStart(

src/transform/transform.h

@@ -21,6 +21,7 @@
 
 #include "src/ast/module.h"
 #include "src/diagnostic/diagnostic.h"
+#include "src/program.h"
 
 namespace tint {
 namespace transform {
@@ -35,10 +36,36 @@ class Transform {
 
   /// The return type of Run()
   struct Output {
-    /// The transformed module. May be empty on error.
-    ast::Module module;
+    /// Constructor
+    Output();
+
+    /// Constructor
+    /// @param module the module to move into this Output
+    explicit Output(ast::Module&& module);
+
+    /// Constructor
+    /// @param module the module to move into this Output
+    /// @param diags the list of diagnostics to move into this Output
+    Output(ast::Module&& module, diag::List&& diags);
+
+    /// Move constructor
+    /// @param output the output to move into this Output
+    Output(Output&& output);
+
+    /// Destructor
+    ~Output();
+
+    /// Move assignment operator
+    /// @param rhs the Output to move into this Output
+    /// @returns this Output
+    Output& operator=(Output&& rhs);
+
+    /// The transformed program. May be empty on error.
+    Program program;
     /// Diagnostics raised while running the Transform.
     diag::List diagnostics;
+    /// The transformed module. May be empty on error.
+    ast::Module& module{program.module};
   };
 
   /// Runs the transform on `module`, returning the transformation result.
@@ -49,6 +76,14 @@ class Transform {
   /// @returns the transformation result
   virtual Output Run(ast::Module* module) = 0;
 
+  /// Runs the transform on `program`, returning the transformation result.
+  /// @note Users of Tint should register the transform with transform manager
+  /// and invoke its Run(), instead of directly calling the transform's Run().
+  /// Calling Run() directly does not perform program state cleanup operations.
+  /// @param program the source program to transform
+  /// @returns the transformation result
+  Output Run(Program* program) { return Run(&program->module); }
+
  protected:
   /// Clones the function `in` adding `statements` to the beginning of the
   /// cloned function body.

src/type_determiner.cc

@@ -61,6 +61,9 @@ namespace tint {
 
 TypeDeterminer::TypeDeterminer(ast::Module* mod) : mod_(mod) {}
 
+TypeDeterminer::TypeDeterminer(Program* program)
+    : TypeDeterminer(&program->module) {}
+
 TypeDeterminer::~TypeDeterminer() = default;
 
 void TypeDeterminer::set_error(const Source& src, const std::string& msg) {

src/type_determiner.h

@@ -20,6 +20,7 @@
 #include <vector>
 
 #include "src/ast/module.h"
+#include "src/program.h"
 #include "src/scope_stack.h"
 #include "src/type/storage_texture_type.h"
 
@@ -45,6 +46,12 @@ class TypeDeterminer {
   /// Constructor
   /// @param mod the module to update with typing information
   explicit TypeDeterminer(ast::Module* mod);
+
+  /// Constructor
+  /// @param program the module to update with typing information
+  explicit TypeDeterminer(Program* program);
+
+  /// Destructor
   ~TypeDeterminer();
 
   /// @returns error messages from the type determiner

src/validator/validator.h

@@ -24,6 +24,7 @@
 #include "src/ast/statement.h"
 #include "src/diagnostic/diagnostic.h"
 #include "src/diagnostic/formatter.h"
+#include "src/program.h"
 
 namespace tint {
 
@@ -39,6 +40,11 @@ class Validator {
   /// @returns true if the validation was successful
   bool Validate(const ast::Module* module);
 
+  /// Runs the validator
+  /// @param program the program to validate
+  /// @returns true if the validation was successful
+  bool Validate(const Program* program) { return Validate(&program->module); }
+
   /// @returns error messages from the validator
   std::string error() {
     diag::Formatter formatter{{false, false, false, false}};

src/writer/hlsl/generator.cc

@@ -21,16 +21,13 @@ namespace writer {
 namespace hlsl {
 
 Generator::Generator(ast::Module module)
-    : Text(std::move(module)),
+    : module_(std::move(module)),
       impl_(std::make_unique<GeneratorImpl>(&module_)) {}
 
-Generator::~Generator() = default;
+Generator::Generator(Program* program)
+    : impl_(std::make_unique<GeneratorImpl>(&program->module)) {}
 
-void Generator::Reset() {
-  set_error("");
-  out_ = std::ostringstream();
-  impl_ = std::make_unique<GeneratorImpl>(&module_);
-}
+Generator::~Generator() = default;
 
 bool Generator::Generate() {
   auto ret = impl_->Generate(out_);

src/writer/hlsl/generator.h

@@ -19,6 +19,7 @@
 #include <sstream>
 #include <string>
 
+#include "src/program.h"
 #include "src/writer/hlsl/generator_impl.h"
 #include "src/writer/text.h"
 
@@ -32,10 +33,13 @@ class Generator : public Text {
   /// Constructor
   /// @param module the module to convert
   explicit Generator(ast::Module module);
-  ~Generator() override;
 
-  /// Resets the generator
-  void Reset() override;
+  /// Constructor
+  /// @param program the program to convert
+  explicit Generator(Program* program);
+
+  /// Destructor
+  ~Generator() override;
 
   /// Generates the result data
   /// @returns true on successful generation; false otherwise
@@ -55,6 +59,7 @@ class Generator : public Text {
   std::string error() const;
 
  private:
+  ast::Module module_;
   std::ostringstream out_;
   std::unique_ptr<GeneratorImpl> impl_;
 };

src/writer/hlsl/generator_impl.h

@@ -74,9 +74,6 @@ class GeneratorImpl {
   /// @returns the error
   std::string error() const { return error_; }
 
-  /// Resets the generator
-  void Reset();
-
   /// @param out the output stream
   /// @returns true on successful generation; false otherwise
   bool Generate(std::ostream& out);

src/writer/msl/generator.cc

@@ -21,15 +21,13 @@ namespace writer {
 namespace msl {
 
 Generator::Generator(ast::Module module)
-    : Text(std::move(module)),
+    : module_(std::move(module)),
       impl_(std::make_unique<GeneratorImpl>(&module_)) {}
 
-Generator::~Generator() = default;
+Generator::Generator(Program* program)
+    : impl_(std::make_unique<GeneratorImpl>(&program->module)) {}
 
-void Generator::Reset() {
-  set_error("");
-  impl_ = std::make_unique<GeneratorImpl>(&module_);
-}
+Generator::~Generator() = default;
 
 bool Generator::Generate() {
   auto ret = impl_->Generate();

src/writer/msl/generator.h

@@ -18,6 +18,7 @@
 #include <memory>
 #include <string>
 
+#include "src/program.h"
 #include "src/writer/msl/generator_impl.h"
 #include "src/writer/text.h"
 
@@ -31,10 +32,13 @@ class Generator : public Text {
   /// Constructor
   /// @param module the module to convert
   explicit Generator(ast::Module module);
-  ~Generator() override;
 
-  /// Resets the generator
-  void Reset() override;
+  /// Constructor
+  /// @param program the program to convert
+  explicit Generator(Program* program);
+
+  /// Destructor
+  ~Generator() override;
 
   /// Generates the result data
   /// @returns true on successful generation; false otherwise
@@ -54,6 +58,7 @@ class Generator : public Text {
   std::string error() const;
 
  private:
+  ast::Module module_;
   std::unique_ptr<GeneratorImpl> impl_;
 };
 

src/writer/spirv/generator.cc

@@ -21,16 +21,15 @@ namespace writer {
 namespace spirv {
 
 Generator::Generator(ast::Module module)
-    : writer::Writer(std::move(module)),
+    : module_(std::move(module)),
       builder_(std::make_unique<Builder>(&module_)),
       writer_(std::make_unique<BinaryWriter>()) {}
 
-Generator::~Generator() = default;
+Generator::Generator(Program* program)
+    : builder_(std::make_unique<Builder>(&program->module)),
+      writer_(std::make_unique<BinaryWriter>()) {}
 
-void Generator::Reset() {
-  builder_ = std::make_unique<Builder>(&module_);
-  writer_ = std::make_unique<BinaryWriter>();
-}
+Generator::~Generator() = default;
 
 bool Generator::Generate() {
   if (!builder_->Build()) {

src/writer/spirv/generator.h

@@ -20,6 +20,7 @@
 #include <vector>
 
 #include "src/ast/module.h"
+#include "src/program.h"
 #include "src/writer/spirv/binary_writer.h"
 #include "src/writer/spirv/builder.h"
 #include "src/writer/writer.h"
@@ -34,10 +35,13 @@ class Generator : public writer::Writer {
   /// Constructor
   /// @param module the module to convert
   explicit Generator(ast::Module module);
-  ~Generator() override;
 
-  /// Resets the generator
-  void Reset() override;
+  /// Constructor
+  /// @param program the program to convert
+  explicit Generator(Program* program);
+
+  /// Destructor
+  ~Generator() override;
 
   /// Generates the result data
   /// @returns true on successful generation; false otherwise
@@ -54,6 +58,7 @@ class Generator : public writer::Writer {
   const std::vector<uint32_t>& result() const { return writer_->result(); }
 
  private:
+  ast::Module module_;
   std::unique_ptr<Builder> builder_;
   std::unique_ptr<BinaryWriter> writer_;
 };

src/writer/text.cc

@@ -19,8 +19,6 @@
 namespace tint {
 namespace writer {
 
-Text::Text(ast::Module module) : Writer(std::move(module)) {}
-
 Text::~Text() = default;
 
 }  // namespace writer

src/writer/text.h

@@ -25,9 +25,6 @@ namespace writer {
 /// Class to generate text source
 class Text : public Writer {
  public:
-  /// Constructor
-  /// @param module the module to convert
-  explicit Text(ast::Module module);
   ~Text() override;
 
   /// @returns the result data

src/writer/wgsl/generator.cc

@@ -21,15 +21,13 @@ namespace writer {
 namespace wgsl {
 
 Generator::Generator(ast::Module module)
-    : Text(std::move(module)),
+    : module_(std::move(module)),
       impl_(std::make_unique<GeneratorImpl>(&module_)) {}
 
-Generator::~Generator() = default;
+Generator::Generator(Program* program)
+    : impl_(std::make_unique<GeneratorImpl>(&program->module)) {}
 
-void Generator::Reset() {
-  set_error("");
-  impl_ = std::make_unique<GeneratorImpl>(&module_);
-}
+Generator::~Generator() = default;
 
 bool Generator::Generate() {
   auto ret = impl_->Generate();

src/writer/wgsl/generator.h

@@ -18,6 +18,7 @@
 #include <memory>
 #include <string>
 
+#include "src/program.h"
 #include "src/writer/text.h"
 #include "src/writer/wgsl/generator_impl.h"
 
@@ -31,10 +32,13 @@ class Generator : public Text {
   /// Constructor
   /// @param module the module to convert
   explicit Generator(ast::Module module);
-  ~Generator() override;
 
-  /// Resets the generator
-  void Reset() override;
+  /// Constructor
+  /// @param program the program to convert
+  explicit Generator(Program* program);
+
+  /// Destructor
+  ~Generator() override;
 
   /// Generates the result data
   /// @returns true on successful generation; false otherwise
@@ -54,6 +58,7 @@ class Generator : public Text {
   std::string error() const;
 
  private:
+  ast::Module module_;
   std::unique_ptr<GeneratorImpl> impl_;
 };
 

src/writer/writer.cc

@@ -19,8 +19,6 @@
 namespace tint {
 namespace writer {
 
-Writer::Writer(ast::Module module) : module_(std::move(module)) {}
-
 Writer::~Writer() = default;
 
 }  // namespace writer

src/writer/writer.h

@@ -31,11 +31,6 @@ class Writer {
   /// @returns the writer error string
   const std::string& error() const { return error_; }
 
-  /// Resets the generator
-  //! @cond Doxygen_Suppress
-  virtual void Reset() = 0;
-  //! @endcond
-
   /// Converts the module into the desired format
   /// @returns true on success; false on failure
   virtual bool Generate() = 0;
@@ -48,18 +43,12 @@ class Writer {
                                   const std::string& name) = 0;
 
  protected:
-  /// Constructor
-  /// @param module the tint module to convert
-  explicit Writer(ast::Module module);
-
   /// Sets the error string
   /// @param msg the error message
   void set_error(const std::string& msg) { error_ = msg; }
 
   /// An error message, if an error was encountered
   std::string error_;
-  /// The module being converted
-  ast::Module module_;
 };
 
 }  // namespace writer