RSDK-9298: Instance class

CMakeLists.txt

@@ -324,7 +324,11 @@ set(VIAMCPPSDK_XTL_VERSION_MINIMUM 0.7.2)
 set(VIAMCPPSDK_XTENSOR_VERSION_MINIMUM 0.24.3)
 
 # Time to find `BOOST`.
-find_package(Boost ${VIAMCPPSDK_BOOST_VERSION_MINIMUM} REQUIRED COMPONENTS headers log program_options)
+if (VIAMCPPSDK_BUILD_TESTS)
+  set(VIAMCPPSDK_BOOST_TEST "unit_test_framework")
+endif()
+
+find_package(Boost ${VIAMCPPSDK_BOOST_VERSION_MINIMUM} REQUIRED COMPONENTS headers log program_options ${VIAMCPPSDK_BOOST_TEST})
 
 # Time to find `protobuf` and `gRPC[++]`. Normally this would just be
 # something like `find_package(gRPC <version> CONFIG REQUIRED)`, and

src/viam/examples/camera/example_camera.cpp

@@ -3,6 +3,7 @@
 #include <unistd.h>
 #include <vector>
 
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/components/camera.hpp>
 #include <viam/sdk/robot/client.hpp>
 #include <viam/sdk/rpc/dial.hpp>
@@ -13,6 +14,11 @@ int main() {
     using std::endl;
     namespace vs = ::viam::sdk;
     try {
+        // Every Viam C++ SDK program must have one and only one Instance object which is created
+        // before
+        // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+        vs::Instance inst;
+
         // If you want to connect to a remote robot, this should be the url of the robot
         // Ex: xxx.xxx.viam.cloud
         std::string robot_address("localhost:8080");

src/viam/examples/dial/example_dial.cpp

@@ -9,13 +9,18 @@
 
 #include <boost/optional.hpp>
 
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/components/generic.hpp>
 #include <viam/sdk/robot/client.hpp>
 #include <viam/sdk/rpc/dial.hpp>
 
 using namespace viam::sdk;
 
 int main() {
+    // Every Viam C++ SDK program must have one and only one Instance object which is created before
+    // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+    Instance inst;
+
     const char* uri = "<your robot URI here>";
     DialOptions dial_options;
     std::string type = "<your authentication type>";

src/viam/examples/dial_api_key/example_dial_api_key.cpp

@@ -10,6 +10,7 @@
 #include <boost/optional.hpp>
 #include <boost/program_options.hpp>
 
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/robot/client.hpp>
 #include <viam/sdk/rpc/dial.hpp>
 
@@ -18,6 +19,10 @@ using namespace viam::sdk;
 namespace po = boost::program_options;
 
 int main(int argc, char* argv[]) {
+    // Every Viam C++ SDK program must have one and only one Instance object which is created before
+    // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+    Instance inst;
+
     po::options_description desc("Allowed options");
     desc.add_options()("help", "List options and exit")(
         "uri", po::value<std::string>(), "URI of robot")(

src/viam/examples/mlmodel/example_audio_classification_client.cpp

@@ -29,6 +29,7 @@
 #include <boost/program_options.hpp>
 #include <boost/variant/get.hpp>
 
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/robot/client.hpp>
 #include <viam/sdk/services/mlmodel.hpp>
 
@@ -78,6 +79,10 @@ constexpr char kRobotConfigTemplate[] = R"(
 }  // namespace
 
 int main(int argc, char* argv[]) try {
+    // Every Viam C++ SDK program must have one and only one Instance object which is created before
+    // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+    viam::sdk::Instance inst;
+
     // Build up our command line options. The example operates in two
     // modes. In the "--generate" mode, it takes command line
     // parameters needed to satisfy the interpolation points in the

src/viam/examples/modules/complex/client.cpp

@@ -11,6 +11,7 @@
 #include <grpcpp/grpcpp.h>
 #include <grpcpp/support/status.h>
 
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/components/motor.hpp>
 #include <viam/sdk/robot/client.hpp>
 #include <viam/sdk/rpc/dial.hpp>
@@ -21,6 +22,10 @@
 using namespace viam::sdk;
 
 int main() {
+    // Every Viam C++ SDK program must have one and only one Instance object which is created before
+    // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+    Instance inst;
+
     const char* uri = "http://localhost:8080/";  // replace with your URI if connecting securely
     DialOptions dial_options;
     dial_options.set_allow_insecure_downgrade(true);  // set to false if connecting securely
@@ -37,8 +42,8 @@ int main() {
 
     // Register custom gizmo and summation clients so robot client can access resources
     // of that type from the server.
-    Registry::register_resource_client<GizmoClient>();
-    Registry::register_resource_client<SummationClient>();
+    Registry::get().register_resource_client<GizmoClient>();
+    Registry::get().register_resource_client<SummationClient>();
 
     // Connect to robot.
     std::shared_ptr<RobotClient> robot = RobotClient::at_address(address, options);

src/viam/examples/modules/complex/main.cpp

@@ -5,6 +5,7 @@
 #include <grpcpp/grpcpp.h>
 #include <grpcpp/server_context.h>
 
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/components/base.hpp>
 #include <viam/sdk/components/component.hpp>
 #include <viam/sdk/config/resource.hpp>
@@ -24,11 +25,15 @@
 using namespace viam::sdk;
 
 int main(int argc, char** argv) {
+    // Every Viam C++ SDK program must have one and only one Instance object which is created before
+    // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+    Instance inst;
+
     Model mybase_model("viam", "base", "mybase");
 
     // Make sure to explicity register resources with custom APIs.
-    Registry::register_resource_server<GizmoServer>();
-    Registry::register_resource_server<SummationServer>();
+    Registry::get().register_resource_server<GizmoServer>();
+    Registry::get().register_resource_server<SummationServer>();
 
     std::shared_ptr<ModelRegistration> mybase_mr = std::make_shared<ModelRegistration>(
         API::get<Base>(),

src/viam/examples/modules/complex/test_complex_module.cpp

@@ -24,8 +24,9 @@ using namespace viam::sdktests;
 
 struct RegisterGizmoAndSummationFixture {
     RegisterGizmoAndSummationFixture() {
-        Registry::register_resource<GizmoClient, GizmoServer>();
-        Registry::register_resource<SummationClient, SummationServer>();
+        auto& registry = Registry::get();
+        registry.register_resource<GizmoClient, GizmoServer>();
+        registry.register_resource<SummationClient, SummationServer>();
     }
 
     // Test teardown is a noop;

src/viam/examples/modules/simple/client.cpp

@@ -2,6 +2,7 @@
 #include <memory>
 #include <string>
 
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/common/proto_value.hpp>
 #include <viam/sdk/components/sensor.hpp>
 #include <viam/sdk/robot/client.hpp>
@@ -10,6 +11,10 @@
 using namespace viam::sdk;
 
 int main() {
+    // Every Viam C++ SDK program must have one and only one Instance object which is created before
+    // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+    Instance inst;
+
     const char* uri = "http://localhost:8080/";  // replace with your URI if connecting securely
     DialOptions dial_options;
     dial_options.set_allow_insecure_downgrade(true);  // set to false if connecting securely

src/viam/examples/modules/simple/main.cpp

@@ -3,6 +3,7 @@
 #include <sstream>
 
 #include <viam/sdk/common/exception.hpp>
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/common/proto_value.hpp>
 #include <viam/sdk/components/sensor.hpp>
 #include <viam/sdk/config/resource.hpp>
@@ -75,6 +76,10 @@ ProtoStruct MySensor::get_readings(const ProtoStruct&) {
 }
 
 int main(int argc, char** argv) try {
+    // Every Viam C++ SDK program must have one and only one Instance object which is created before
+    // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+    Instance inst;
+
     Model mysensor_model("viam", "sensor", "mysensor");
 
     std::shared_ptr<ModelRegistration> mr = std::make_shared<ModelRegistration>(

src/viam/examples/modules/tflite/main.cpp

@@ -23,6 +23,7 @@
 
 #include <tensorflow/lite/c/c_api.h>
 
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/common/proto_value.hpp>
 #include <viam/sdk/components/component.hpp>
 #include <viam/sdk/config/resource.hpp>
@@ -723,6 +724,10 @@ class MLModelServiceTFLite : public vsdk::MLModelService,
 };
 
 int serve(const std::string& socket_path) try {
+    // Every Viam C++ SDK program must have one and only one Instance object which is created before
+    // any other C++ SDK objects and stays alive until all Viam C++ SDK objects are destroyed.
+    vsdk::Instance inst;
+
     // Create a new model registration for the service.
     auto module_registration = std::make_shared<vsdk::ModelRegistration>(
         // Identify that this resource offers the MLModelService API
@@ -737,7 +742,7 @@ int serve(const std::string& socket_path) try {
         });
 
     // Register the newly created registration with the Registry.
-    vsdk::Registry::register_model(module_registration);
+    Registry::get().register_model(module_registration);
 
     // Construct the module service and tell it where to place the socket path.
     auto module_service = std::make_shared<vsdk::ModuleService>(socket_path);

src/viam/examples/motor/example_motor.cpp

@@ -6,6 +6,7 @@
 #include <string>
 #include <vector>
 
+#include <viam/sdk/common/instance.hpp>
 #include <viam/sdk/components/motor.hpp>
 #include <viam/sdk/robot/client.hpp>
 #include <viam/sdk/rpc/dial.hpp>
@@ -27,6 +28,11 @@ int main() {
     namespace vs = ::viam::sdk;
 
     try {
+        // Every Viam C++ SDK program must have one and only one Instance object which is created
+        // before any other C++ SDK objects and stays alive until all Viam C++ SDK objects are
+        // destroyed.
+        vs::Instance inst;
+
         // If you want to connect to a remote robot, this should be the url of the robot
         // Ex: xxx.xxx.viam.cloud
         std::string robot_address("localhost:8080");

src/viam/sdk/CMakeLists.txt

@@ -50,6 +50,7 @@ target_sources(viamsdk
   PRIVATE
     common/client_helper.cpp
     common/exception.cpp
+    common/instance.cpp
     common/linear_algebra.cpp
     common/pose.cpp
     common/proto_value.cpp
@@ -145,6 +146,7 @@ target_sources(viamsdk
     FILES
       ../../viam/sdk/common/client_helper.hpp
       ../../viam/sdk/common/exception.hpp
+      ../../viam/sdk/common/instance.hpp
       ../../viam/sdk/common/linear_algebra.hpp
       ../../viam/sdk/common/pose.hpp
       ../../viam/sdk/common/proto_convert.hpp

src/viam/sdk/common/instance.cpp

@@ -0,0 +1,57 @@
+#include <viam/sdk/common/instance.hpp>
+
+#include <viam/sdk/common/exception.hpp>
+#include <viam/sdk/common/private/instance.hpp>
+#include <viam/sdk/registry/registry.hpp>
+
+#include <atomic>
+
+namespace viam {
+namespace sdk {
+
+namespace {
+
+// Memory region sentinel to check if object is being destroyed.
+std::aligned_storage_t<sizeof(Instance), alignof(Instance)> sentinel;
+
+std::atomic<Instance*> current_instance{nullptr};
+
+}  // namespace
+
+Instance::Instance() {
+    Instance* expected = nullptr;
+
+    if (!current_instance.compare_exchange_strong(expected, this)) {
+        throw Exception("tried to create duplicate instance");
+    }
+
+    impl_ = std::make_unique<Instance::Impl>();
+    impl_->registry.initialize();
+}
+
+Instance::~Instance() {
+    current_instance.store(reinterpret_cast<Instance*>(&sentinel));
+    impl_.reset();
+}
+
+Instance& Instance::current(Instance::Creation creation) {
+    if (!current_instance.load()) {
+        if (creation == Creation::if_needed) {
+            // This variable declaration calls the default ctor, storing a current instance.
+            static Instance inst;  // NOLINT (misc-const-correctness)
+        } else {
+            throw Exception("Instance has not yet been created");
+        }
+    }
+
+    Instance* current = current_instance.load();
+
+    if (current == reinterpret_cast<Instance*>(&sentinel)) {
+        throw Exception("instance was destroyed");
+    }
+
+    return *current;
+}
+
+}  // namespace sdk
+}  // namespace viam

src/viam/sdk/common/instance.hpp

@@ -0,0 +1,37 @@
+#pragma once
+
+#include <memory>
+
+namespace viam {
+namespace sdk {
+
+/// @brief Instance management for Viam C++ SDK applications.
+/// This is a single instance class which is responsible for global setup and teardown related to
+/// the SDK. An Instance must be constructed before doing anything else in a program, and it must
+/// remain alive in a valid state for the duration of the program. Creating multiple Instance
+/// objects in the same program is an error.
+class Instance {
+   public:
+    /// @brief Enumeration for creation behavior of @ref current
+    enum class Creation {
+        open_existing,  ///< Instance must already exist
+        if_needed       ///< Use existing instance if present, else create one.
+    };
+
+    Instance();
+    ~Instance();
+
+    /// @brief Get the current Instance according to the Creation behavior.
+    /// Calling current(Creation::open_existing) when an instance has not yet been constructed is an
+    /// error.
+    static Instance& current(Creation);
+
+   private:
+    friend class Registry;
+
+    struct Impl;
+    std::unique_ptr<Impl> impl_;
+};
+
+}  // namespace sdk
+}  // namespace viam

src/viam/sdk/common/private/instance.hpp

@@ -0,0 +1,14 @@
+#pragma once
+
+#include <viam/sdk/common/instance.hpp>
+#include <viam/sdk/registry/registry.hpp>
+
+namespace viam {
+namespace sdk {
+
+struct Instance::Impl {
+    Registry registry;
+};
+
+}  // namespace sdk
+}  // namespace viam