Doxygen for torchbind (#35007)
Summary: Pull Request resolved: https://github.com/pytorch/pytorch/pull/35007
Test Plan: Imported from OSS
Reviewed By: driazati
Differential Revision: D20525680
Pulled By: jamesr66a
fbshipit-source-id: aaa768f395e30dcec8007d50e17f21837c306719
diff --git a/docs/cpp/source/Doxyfile b/docs/cpp/source/Doxyfile
index e0ba567..1c58d68 100644
--- a/docs/cpp/source/Doxyfile
+++ b/docs/cpp/source/Doxyfile
@@ -59,7 +59,8 @@
../../../torch/csrc/autograd/generated/variable_factories.h \
../../../torch/csrc/jit/runtime/custom_operator.h \
../../../torch/csrc/jit/serialization/import.h \
- ../../../torch/csrc/jit/api/module.h
+ ../../../torch/csrc/jit/api/module.h \
+ ../../../torch/custom_class.h
# Don't include .cpp files!
FILE_PATTERNS = *.h
# If you need this to be YES, exhale will probably break.
diff --git a/torch/custom_class.h b/torch/custom_class.h
index da1fb75..9072ad8 100644
--- a/torch/custom_class.h
+++ b/torch/custom_class.h
@@ -17,53 +17,45 @@
namespace torch {
-// Given a qualified name (e.g. __torch__.torch.classes.Foo), return
-// the ClassType pointer to the Type that describes that custom class,
-// or nullptr if no class by that name was found.
-TORCH_API at::ClassTypePtr getCustomClass(const std::string& name);
-
-// Given an IValue, return true if the object contained in that IValue
-// is a custom C++ class, otherwise return false.
-TORCH_API bool isCustomClass(const c10::IValue& v);
-
-// This function is used in conjunction with `class_::def()` to register
-// a constructor for a given C++ class type. For example,
-// torch::init<int, std::string>() would register a two-argument constructor
-// taking an int and a std::string as argument.
+/// This function is used in conjunction with `class_::def()` to register
+/// a constructor for a given C++ class type. For example,
+/// `torch::init<int, std::string>()` would register a two-argument constructor
+/// taking an `int` and a `std::string` as argument.
template <class... Types>
detail::types<void, Types...> init() {
return detail::types<void, Types...>{};
}
-// Entry point for custom C++ class registration. To register a C++ class
-// in PyTorch, instantiate `torch::class_` with the desired class as the
-// template parameter. Typically, this instantiation should be done in
-// the initialization of a global variable, so that the class will be
-// made available on dynamic library loading without any additional API
-// calls needed. For example, to register a class named Foo, you might
-// create a global variable like so:
-//
-// static auto register_foo = torch::class_<Foo>("Foo")
-// .def("myMethod", &Foo::myMethod)
-// .def("lambdaMethod", [](const c10::intrusive_ptr<Foo>& self) {
-// // Do something with `self`
-// });
-//
-// In addition to registering the class, this registration also chains
-// `def()` calls to register methods. `myMethod()` is registered with
-// a pointer to the Foo class's `myMethod()` method. `lambdaMethod()`
-// is registered with a C++ lambda expression.
+/// Entry point for custom C++ class registration. To register a C++ class
+/// in PyTorch, instantiate `torch::class_` with the desired class as the
+/// template parameter. Typically, this instantiation should be done in
+/// the initialization of a global variable, so that the class will be
+/// made available on dynamic library loading without any additional API
+/// calls needed. For example, to register a class named Foo, you might
+/// create a global variable like so:
+///
+/// static auto register_foo = torch::class_<Foo>("Foo")
+/// .def("myMethod", &Foo::myMethod)
+/// .def("lambdaMethod", [](const c10::intrusive_ptr<Foo>& self) {
+/// // Do something with `self`
+/// });
+///
+/// In addition to registering the class, this registration also chains
+/// `def()` calls to register methods. `myMethod()` is registered with
+/// a pointer to the Foo class's `myMethod()` method. `lambdaMethod()`
+/// is registered with a C++ lambda expression.
template <class CurClass>
class class_ {
static_assert(std::is_base_of<CustomClassHolder, CurClass>::value,
"torch::class_<T> requires T to inherit from CustomClassHolder");
public:
- // Constructor. String argument className_ is the name you would like to
- // see this class exposed as in Python and TorchScript. For example, if
- // you pass in "MyStack" here, the class will appear as
- // `torch.classes.MyStack` in both Python and TorchScript.
- class_(std::string className_) : className(std::move(className_)) {
+ /// This constructor actually registers the class type.
+ /// String argument `className_` is the name you would like to
+ /// see this class exposed as in Python and TorchScript. For example, if
+ /// you pass in "MyStack" here, the class will appear as
+ /// `torch.classes.MyStack` in both Python and TorchScript.
+ explicit class_(const std::string& className) : className(std::move(className)) {
qualClassName = topModule + "." + parentModule + "." + className;
classTypePtr = at::ClassType::create(
@@ -79,10 +71,10 @@
registerCustomClass(classTypePtr);
}
- // def() can be used in conjunction with `torch::init()` to register
- // a constructor for a given C++ class type. For example, passing
- // torch::init<int, std::string>() would register a two-argument constructor
- // taking an int and a std::string as argument.
+ /// def() can be used in conjunction with `torch::init()` to register
+ /// a constructor for a given C++ class type. For example, passing
+ /// `torch::init<int, std::string>()` would register a two-argument constructor
+ /// taking an `int` and a `std::string` as argument.
template <typename... Types>
class_& def(detail::types<void, Types...>) { // Used in combination with
// torch::init<...>()
@@ -96,23 +88,24 @@
return *this;
}
- // This is the normal method registration API. `name` is the name that
- // the method will be made accessible by in Python and TorchScript.
- // `f` is a callable object that defines the method. Typically `f`
- // will either be a pointer to a method on `CurClass`, or a lambda
- // expression that takes a c10::intrusive_ptr<CurClass> as the first
- // argument (emulating a `this` argument in a C++ method.)
- //
- // Examples:
- // // Exposes method `foo` on C++ class `Foo` as `call_foo()` in
- // // Python and TorchScript
- // .def("call_foo", &Foo::foo)
- //
- // // Exposes the given lambda expression as method `call_lambda()`
- // // in Python and TorchScript.
- // .def("call_lambda", [](const c10::intrusive_ptr<Foo>& self) {
- // // do something
- // })
+ /// This is the normal method registration API. `name` is the name that
+ /// the method will be made accessible by in Python and TorchScript.
+ /// `f` is a callable object that defines the method. Typically `f`
+ /// will either be a pointer to a method on `CurClass`, or a lambda
+ /// expression that takes a `c10::intrusive_ptr<CurClass>` as the first
+ /// argument (emulating a `this` argument in a C++ method.)
+ ///
+ /// Examples:
+ ///
+ /// // Exposes method `foo` on C++ class `Foo` as `call_foo()` in
+ /// // Python and TorchScript
+ /// .def("call_foo", &Foo::foo)
+ ///
+ /// // Exposes the given lambda expression as method `call_lambda()`
+ /// // in Python and TorchScript.
+ /// .def("call_lambda", [](const c10::intrusive_ptr<Foo>& self) {
+ /// // do something
+ /// })
template <typename Func>
class_& def(std::string name, Func f) {
auto wrapped_f = detail::wrap_func<CurClass, Func>(std::move(f));
@@ -120,22 +113,34 @@
return *this;
}
- // def_pickle() is used to define exactly what state gets serialized
- // or deserialized for a given instance of a custom C++ class in
- // Python or TorchScript. This protocol is equivalent to the Pickle
- // concept of __getstate__ and __setstate__ from Python
- // (https://docs.python.org/2/library/pickle.html#object.__getstate__)
- //
- // Currently, both the `get_state` and `set_state` callables must be
- // C++ lambda expressions. They should have the following signatures,
- // where CurClass is the class you're registering and T is some object
- // that encapsulates the state of the object.
- //
- // __getstate__(intrusive_ptr<CurClass>) -> T
- // __setstate__(T) -> intrusive_ptr<CurClass>
- //
- // T must be an object that is convertable to IValue by the same rules
- // for custom op/method registration.
+ /// def_pickle() is used to define exactly what state gets serialized
+ /// or deserialized for a given instance of a custom C++ class in
+ /// Python or TorchScript. This protocol is equivalent to the Pickle
+ /// concept of `__getstate__` and `__setstate__` from Python
+ /// (https://docs.python.org/2/library/pickle.html#object.__getstate__)
+ ///
+ /// Currently, both the `get_state` and `set_state` callables must be
+ /// C++ lambda expressions. They should have the following signatures,
+ /// where `CurClass` is the class you're registering and `T` is some object
+ /// that encapsulates the state of the object.
+ ///
+ /// __getstate__(intrusive_ptr<CurClass>) -> T
+ /// __setstate__(T) -> intrusive_ptr<CurClass>
+ ///
+ /// `T` must be an object that is convertable to IValue by the same rules
+ /// for custom op/method registration.
+ ///
+ /// Example:
+ ///
+ /// .def_pickle(
+ /// // __getstate__
+ /// [](const c10::intrusive_ptr<MyStackClass<std::string>>& self) {
+ /// return self->stack_;
+ /// },
+ /// [](std::vector<std::string> state) { // __setstate__
+ /// return c10::make_intrusive<MyStackClass<std::string>>(
+ /// std::vector<std::string>{"i", "was", "deserialized"});
+ /// })
template <typename GetStateFn, typename SetStateFn>
class_& def_pickle(GetStateFn&& get_state, SetStateFn&& set_state) {
static_assert(
@@ -233,15 +238,15 @@
const std::string topModule = "__torch__.torch";
};
-// make_custom_class() is a convenient way to create an instance of a registered
-// custom class and wrap it in an IValue, for example when you want to pass the
-// object to TorchScript. Its syntax is equivalent to APIs like std::make_shared<>
-// or c10::make_intrusive<>.
-//
-// For example, if you have a custom C++ class that can be constructed from an int
-// and std::string, you might use this API like so:
-//
-// IValue custom_class_iv = torch::make_custom_class<MyClass>(3, "foobarbaz");
+/// make_custom_class() is a convenient way to create an instance of a registered
+/// custom class and wrap it in an IValue, for example when you want to pass the
+/// object to TorchScript. Its syntax is equivalent to APIs like `std::make_shared<>`
+/// or `c10::make_intrusive<>`.
+///
+/// For example, if you have a custom C++ class that can be constructed from an `int`
+/// and `std::string`, you might use this API like so:
+///
+/// IValue custom_class_iv = torch::make_custom_class<MyClass>(3, "foobarbaz");
template <typename CurClass, typename... CtorArgs>
c10::IValue make_custom_class(CtorArgs&&... args) {
if (!c10::isCustomClassRegistered<c10::intrusive_ptr<CurClass>>()) {
diff --git a/torch/custom_class_detail.h b/torch/custom_class_detail.h
index 3b3c7c2..373f980 100644
--- a/torch/custom_class_detail.h
+++ b/torch/custom_class_detail.h
@@ -124,6 +124,15 @@
TORCH_API void registerCustomClass(at::ClassTypePtr class_type);
TORCH_API void registerCustomClassMethod(std::shared_ptr<jit::Function> method);
+// Given a qualified name (e.g. __torch__.torch.classes.Foo), return
+// the ClassType pointer to the Type that describes that custom class,
+// or nullptr if no class by that name was found.
+TORCH_API at::ClassTypePtr getCustomClass(const std::string& name);
+
+// Given an IValue, return true if the object contained in that IValue
+// is a custom C++ class, otherwise return false.
+TORCH_API bool isCustomClass(const c10::IValue& v);
+
namespace jit {
using ::torch::registerCustomClass;
using ::torch::registerCustomClassMethod;
