Add comments for public functions and classes

ghstack-source-id: a0191f931e5aa7268f93c1fd8a69d0b6c98b5bc3
Pull Request resolved: #222

Author: PaliC

multipy/runtime/deploy.h

@@ -57,6 +57,8 @@ struct TORCH_API InterpreterSession {
   // InterpreterSession* I)' instead. We will have no backwards compatibility
   // guarentees for this function.
   ReplicatedObj createMovable(Obj obj);
+
+  // Converts a `ReplicatedObj` to an `Obj` on this InterpreterSession.
   Obj fromMovable(const ReplicatedObj& obj);
 
  protected:
@@ -73,6 +75,9 @@ struct TORCH_API InterpreterSession {
   std::function<void()> deconstruction_callback_ = nullptr;
 };
 
+// An `Interpreter` represents an invidual subinterpreter created by `torch::deploy`.
+// It allows for the creation of `InterpreterSession` objects which allow users to interact with
+// python objects.
 class TORCH_API Interpreter {
  private:
   void* handle_;
@@ -84,17 +89,22 @@ class TORCH_API Interpreter {
   multipy::optional<EmbeddedFile> torchPluginFile_;
 
  public:
+  // Create an Interpreter which is managed by `manager` and using the enviroment `env`
   Interpreter(InterpreterManager* manager, std::shared_ptr<Environment> env);
+
+  // Create an Interpreter manager using enviroment `env` which is not tied to an Interpreter Manager.
   explicit Interpreter(std::shared_ptr<Environment> env)
       : Interpreter(nullptr, env) {}
 
+  // Get a new `InterpreterSession` from this Interpreter.
   InterpreterSession acquireSession() const {
     if (manager_) {
       return InterpreterSession(pImpl_->acquireSession(), manager_);
     } else {
       return InterpreterSession(pImpl_->acquireSession());
     }
   }
+
   ~Interpreter();
   Interpreter(Interpreter&& rhs) noexcept
       : handle_(rhs.handle_),
@@ -113,17 +123,26 @@ class TORCH_API Interpreter {
 
 struct Package;
 
+// The default LoadBalancer for torch::deploy which handles allocating and freeing subinterpreters.
 struct TORCH_API LoadBalancer {
+
+  // create a Loadbalancer which handles `n` interpreters.
   explicit LoadBalancer(size_t n)
       : uses_(new uint64_t[8 * n]), allocated_(n), n_(n) {
     // 8*... to avoid false sharing of atomics on the same cache line
     memset(uses_.get(), 0, 8 * n_ * sizeof(uint64_t));
   }
+
+  // change the amount of subinterpreters which is handled by the load balancer.
   void setResourceLimit(size_t n) {
     MULTIPY_INTERNAL_ASSERT(n <= allocated_);
     n_ = n;
   }
+
+  // allocate an subinterpreter, and return its ID which is used to free it.
   int acquire();
+
+  // free the subinterpreter with ID `where`. This ID is returned by `LoadBalancer::acquire()`
   void free(int where);
 
  private:
@@ -134,13 +153,18 @@ struct TORCH_API LoadBalancer {
   size_t n_;
 };
 
+// An `InterpreterManager` handles the interaction of multiple subinterpreters such as allocating
+// subinterpreters, or load balancing the subinterpreters.
 struct TORCH_API InterpreterManager {
+
+  // constructor for `InterpreterManager` which takes the number of interpreters
+  // (usually correlates to number of cores on your cpu), and a pointer to an `Enviroment`.
   explicit InterpreterManager(
       size_t nInterp = 2,
       std::shared_ptr<Environment> env = std::make_shared<NoopEnvironment>());
 
-  // get a free model, guarenteed that no other user of acquireOne has the same
-  // model. It _is_ possible that other users will be using the interpreter.
+  // get a free InterpreterSession, guarenteed that no other user of acquireOne has the same
+  // InterpreterSession. It _is_ possible that other users will be using the interpreter.
   InterpreterSession acquireOne() {
     int where = resources_.acquire();
     InterpreterSession I = instances_[where].acquireSession();
@@ -154,11 +178,18 @@ struct TORCH_API InterpreterManager {
   at::ArrayRef<Interpreter> allInstances() {
     return instances_;
   }
+
+  // debugging tool to control the size of the loadBalancer
+  // and change the number of interpreters on the fly
   void debugLimitInterpreters(size_t N) {
     AT_ASSERT(N <= instances_.size());
     resources_.setResourceLimit(N);
   }
+
+  // loads a package from a file with name `uri`
   Package loadPackage(const std::string& uri);
+
+  // loads a package from a `PyTorchStreamReader` or any class other which uses `ReadAdapterInterface`
   Package loadPackage(
       std::shared_ptr<caffe2::serialize::ReadAdapterInterface> reader);
 
@@ -171,10 +202,12 @@ struct TORCH_API InterpreterManager {
     registeredModuleSource_[std::move(name)] = std::move(src);
   }
 
-  // Util function for debugging.
+  // Util function for debugging which outputs the number of registered modules.
   size_t countRegisteredModuleSources() {
     return registeredModuleSource_.size();
   }
+
+  // Converts `obj` from on `InterpreterSession` I into a  `ReplicatedObj`.
   ReplicatedObj createMovable(Obj obj, InterpreterSession* I);
   InterpreterManager(const InterpreterManager&) = delete;
   InterpreterManager& operator=(const InterpreterManager&) = delete;
@@ -189,6 +222,7 @@ struct TORCH_API InterpreterManager {
   std::unordered_map<std::string, std::string> registeredModuleSource_;
 };
 
+// Underlying implementation for ReplicatedObj.
 struct TORCH_API ReplicatedObjImpl {
   ReplicatedObjImpl(
       size_t object_id,
@@ -204,32 +238,44 @@ struct TORCH_API ReplicatedObjImpl {
   InterpreterManager* manager_;
 };
 
+// A python object which is Replicated from an `Obj` such that it is able to move around to different `InterpreterSessions`
+// by using `InterpreterSession::fromMovable(ReplicatedObj)`
 struct TORCH_API ReplicatedObj {
+
+  // default constructor for `ReplicatedObj`
   ReplicatedObj() : pImpl_(nullptr) {}
+
+  // Create an `InterpreterSession` using `onThisInterpreter`. If `onThisInterpreter` is
+  // a `nullptr', then the associated `InterpreterManager` allocates it.
   InterpreterSession acquireSession(
       const Interpreter* onThisInterpreter = nullptr) const;
   at::IValue operator()(at::ArrayRef<at::IValue> args) const {
     auto I = acquireSession();
     return I.self(args).toIValue();
   }
 
+  // invokes `callKwargs` using the underlying python object, and returns the output as an `IValue`.
   [[nodiscard]] at::IValue callKwargs(
       std::vector<at::IValue> args,
       std::unordered_map<std::string, c10::IValue> kwargs) const {
     auto I = acquireSession();
     return I.self.callKwargs(std::move(args), std::move(kwargs)).toIValue();
   }
 
+ // invokes `callKwargs` using the underlying python object, and returns the output as an `IValue`.
   [[nodiscard]] at::IValue callKwargs(
       std::unordered_map<std::string, c10::IValue> kwargs) const {
     auto I = acquireSession();
     return I.self.callKwargs(std::move(kwargs)).toIValue();
   }
 
+ // invokes `hasattr` using the underlying python object, and returns the output as an `IValue`.
   [[nodiscard]] bool hasattr(const char* name) const {
     auto I = acquireSession();
     return I.self.hasattr(name);
   }
+
+
   void unload(const Interpreter* onThisInterpreter = nullptr);
   Obj toObj(InterpreterSession* I);
 
@@ -242,21 +288,24 @@ struct TORCH_API ReplicatedObj {
   friend struct InterpreterManager;
 };
 
+// PythonMethodWrapper is a more specific instance of a
+// ReplicatedObj which represents a python method, and
+// is therefore callable and has argument names accessible.
 class PythonMethodWrapper : public torch::IMethod {
-  // PythonMethodWrapper is a more specific instance of a
-  // ReplicatedObj which represents a python method, and
-  // is therefore callable and has argument names accessible.
  public:
   // TODO(whc) make bound method pickleable, then directly construct from that
+
   PythonMethodWrapper(
       torch::deploy::ReplicatedObj model,
       std::string methodName)
       : model_(std::move(model)), methodName_(std::move(methodName)) {}
 
+  // return the name of the python method.
   const std::string& name() const override {
     return methodName_;
   }
 
+  // overrides the `()` operater to call the underlying python method.
   c10::IValue operator()(
       std::vector<c10::IValue> args,
       const IValueMap& kwargs = IValueMap()) const override {
@@ -274,6 +323,7 @@ class PythonMethodWrapper : public torch::IMethod {
   std::string methodName_;
 };
 
+// An object to encapsulate a `torch::package` which can act as part (or entire) enviroment for subinterpreters.
 struct TORCH_API Package {
   // shorthand for getting the object as a pickle resource in the package
   ReplicatedObj loadPickle(const std::string& module, const std::string& file) {
@@ -308,12 +358,15 @@ struct TORCH_API Package {
   }
 #endif
 
+  // allocate an `InterpreterSession` and load the appropriate torch.package with it.
   InterpreterSession acquireSession() {
     auto I = manager_->acquireOne();
     I.self =
         I.impl_->createOrGetPackageImporterFromContainerFile(containerFile_);
     return I;
   }
+
+  // Converts an `Obj` from `InterpreterSession` `I` into a `ReplicatedObj`.
   ReplicatedObj createMovable(Obj obj, InterpreterSession* I) {
     return manager_->createMovable(obj, I);
   }

multipy/runtime/elf_file.h

@@ -35,10 +35,11 @@ struct Section {
   }
 };
 
+// TODO: consolidate other ELF file related functions in loader.cpp to this file
+
 /*
  * This class provie utilities to handle ELF file. Only support 64bit ELF file.
  */
-// TODO: consolidate other ELF file related functions in loader.cpp to this file
 class ElfFile {
  public:
   explicit ElfFile(const char* filename);

multipy/runtime/interpreter/interpreter_impl.h

@@ -19,6 +19,7 @@ namespace deploy {
 struct InterpreterSessionImpl;
 struct Obj;
 
+// Representation a Pickled Object
 struct PickledObject {
   std::string data_;
   std::vector<at::Storage> storages_;
@@ -28,6 +29,7 @@ struct PickledObject {
   std::shared_ptr<caffe2::serialize::PyTorchStreamReader> containerFile_;
 };
 
+// The underlying implementation of `Obj` which holds the underlying `py::object`.
 struct InterpreterObj {
   friend struct Obj;
   friend struct ReplicatedObjImpl;
@@ -72,21 +74,34 @@ struct Obj {
       : isDefault_(false), baseObj_(baseObj) {}
   Obj() : isDefault_(true), baseObj_(nullptr) {}
 
+  // convert underlying `py::object` into an `IValue`.
   at::IValue toIValue() const;
+
+  // overwrite `()` to use `call` of the underlying `py::object` with `Obj`s as args.
+  // The output is represented as an `Obj`.
   Obj operator()(at::ArrayRef<Obj> args);
+
+  // overwrite `()` to use `call` of the underlying `py::object` with `IValue`s as args.
+  // The output is represented as an `Obj`.
   Obj operator()(at::ArrayRef<at::IValue> args);
+
+  // calls callKwargs from the underlying `py::object`
   Obj callKwargs(
       std::vector<at::IValue> args,
       std::unordered_map<std::string, c10::IValue> kwargs);
+  // calls callKwargs from the underlying `py::object`. The output is represented as an `Obj`.
   Obj callKwargs(std::unordered_map<std::string, c10::IValue> kwargs);
+  // calls hasattr from the underlying `py::object`. The output is represented as an `Obj`.
   bool hasattr(const char* attr);
+  // calls attr from the underlying `py::object`. The output is represented as an `Obj`.
   Obj attr(const char* attr);
 
  private:
   bool isDefault_;
   std::shared_ptr<InterpreterObj> baseObj_;
 };
 
+// The underlying implementation of `InterpreterSession`
 struct InterpreterSessionImpl {
   friend struct Package;
   friend struct ReplicatedObj;
@@ -132,6 +147,7 @@ struct InterpreterSessionImpl {
   }
 };
 
+// The underlying implementation of `Interpreter`
 struct InterpreterImpl {
   virtual InterpreterSessionImpl* acquireSession() = 0;
   virtual void setFindModule(

multipy/runtime/interpreter/plugin_registry.h

@@ -11,21 +11,36 @@ namespace py = pybind11;
 
 namespace multipy {
 
+// A `Converter` is used in order to convert `PyObject`s/`py::object` into
+// an `IValue` or some other representation usch as storage.
 class Converter {
  public:
   virtual ~Converter() = default;
 
+  // convert a `py::handle` to an `IValue`
   virtual multipy::optional<at::IValue> toTypeInferredIValue(
       py::handle input) = 0;
+
+  // convert an `IValue` into a `py::object`
   virtual multipy::optional<py::object> toPyObject(at::IValue ivalue) = 0;
+
+  // convert an `PyObject` into a `Storage`
   virtual multipy::optional<at::Storage> createStorage(PyObject* obj) = 0;
+
+  // create a `PyObject` from `storage`
   virtual multipy::optional<PyObject*> createPyObject(
       const at::Storage& storage) = 0;
+
+  // return the `THPDtype` of `scalarType`
   virtual multipy::optional<THPDtype*> getTHPDtype(
       at::ScalarType scalarType) = 0;
 };
 
+// register a converter to be used by torch::deploy / multipy.
+// The order of the registration of the converters is dictated by the order of compilation.
 void registerConverter(Converter*);
+// deregister a converter from torch::deploy / multipy
+// The order of the deregistration of the converters is dictated by the order of compilation.
 void deregisterConverter(Converter*);
 
 at::IValue toTypeInferredIValue(py::handle input);

multipy/runtime/mem_file.h

@@ -51,6 +51,8 @@ struct MemFile {
   [[nodiscard]] const char* data() const {
     return (const char*)mem_;
   }
+
+  // return the file descriptor of the underlying file.
   int valid() {
     return fcntl(fd_, F_GETFD) != -1 || errno != EBADF;
   }
@@ -62,6 +64,8 @@ struct MemFile {
       close(fd_);
     }
   }
+
+  // return the size of the underlying file defined by the `MemFile`
   size_t size() {
     return n_bytes_;
   }

multipy/runtime/noop_environment.h

@@ -11,6 +11,7 @@
 namespace torch {
 namespace deploy {
 
+// An empty Enviroment
 class NoopEnvironment : public Environment {
  public:
   void configureInterpreter(Interpreter* /* interp */) override {}

multipy/runtime/path_environment.h

@@ -12,6 +12,7 @@
 namespace torch {
 namespace deploy {
 
+// An Enviroment which is defined by a specific path to python code (ie. condas sitepackages)
 class PathEnvironment : public Environment {
  public:
   explicit PathEnvironment(std::string path) : path_(std::move(path)) {}