feat!: [BREAKING CHANGE] add on_configure

.vscode/launch.json

@@ -129,7 +129,7 @@
       "request": "launch",
       "program": "${workspaceFolder}/out/linux/x64/tests/standalone/ten_runtime_smoke_test",
       "args": [
-        "--gtest_filter=DataTest.Basic"
+        "--gtest_filter=ExtensionTest.BasicMultiAppCloseThroughEngine"
       ],
       "cwd": "${workspaceFolder}/out/linux/x64/tests/standalone/",
       "env": {
@@ -645,12 +645,12 @@
       "name": "app (golang) (lldb, launch)",
       "type": "lldb",
       "request": "launch",
-      "program": "${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/python/go_app_python/go_app_python_app/bin/main",
-      "cwd": "${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/python/go_app_python/go_app_python_app/",
+      "program": "${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/go/access_property_go/access_property_go_app/bin/main",
+      "cwd": "${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/go/access_property_go/access_property_go_app/",
       "env": {
-        "LD_LIBRARY_PATH": "${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/python/go_app_python/go_app_python_app/ten_packages/system/ten_runtime/lib:${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/python/go_app_python/go_app_python_app/ten_packages/system/ten_runtime_go/lib:${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/python/go_app_python/go_app_python_app/ten_packages/system/ten_runtime_python/lib",
+        "LD_LIBRARY_PATH": "${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/go/access_property_go/access_property_go_app/ten_packages/system/ten_runtime/lib:${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/go/access_property_go/access_property_go_app/ten_packages/system/ten_runtime_go/lib:${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/go/access_property_go/access_property_go_app/ten_packages/system/ten_runtime_go/lib",
         "DYLD_LIBRARY_PATH": "${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/go/access_property_go/access_property_goo_app/lib",
-        "CGO_LDFLAGS": "-L${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/python/go_app_python/go_app_python_app/ten_packages/system/ten_runtime_go/lib -lten_runtime_go -Wl,-rpath,@loader_path/lib -Wl,-rpath,@loader_path/../lib",
+        "CGO_LDFLAGS": "-L${workspaceFolder}/out/linux/x64/tests/ten_runtime/integration/go/access_property_go/access_property_go_app/ten_packages/system/ten_runtime_go/lib -lten_runtime_go -Wl,-rpath,@loader_path/lib -Wl,-rpath,@loader_path/../lib",
         "TEN_ENABLE_PYTHON_DEBUG": "true",
       },
       "initCommands": [

core/include/ten_runtime/app/app.h

@@ -16,13 +16,15 @@ typedef struct ten_app_t ten_app_t;
 typedef struct ten_metadata_info_t ten_metadata_info_t;
 typedef struct ten_env_t ten_env_t;
 
+typedef void (*ten_app_on_configure_func_t)(ten_app_t *app, ten_env_t *ten_env);
+
 typedef void (*ten_app_on_init_func_t)(ten_app_t *app, ten_env_t *ten_env);
 
 typedef void (*ten_app_on_deinit_func_t)(ten_app_t *app, ten_env_t *ten_env);
 
-TEN_RUNTIME_API ten_app_t *ten_app_create(ten_app_on_init_func_t on_init,
-                                          ten_app_on_deinit_func_t on_deinit,
-                                          ten_error_t *err);
+TEN_RUNTIME_API ten_app_t *ten_app_create(
+    ten_app_on_configure_func_t on_configure, ten_app_on_init_func_t on_init,
+    ten_app_on_deinit_func_t on_deinit, ten_error_t *err);
 
 TEN_RUNTIME_API void ten_app_destroy(ten_app_t *self);
 

core/include/ten_runtime/binding/cpp/internal/app.h

@@ -9,12 +9,12 @@
 #include <cstddef>
 #include <string>
 
-#include "ten_utils/macro/check.h"
 #include "ten_runtime/app/app.h"
 #include "ten_runtime/binding/common.h"
 #include "ten_runtime/binding/cpp/internal/common.h"
 #include "ten_runtime/binding/cpp/internal/extension_group.h"
 #include "ten_runtime/ten.h"
+#include "ten_utils/macro/check.h"
 
 using ten_app_t = struct ten_app_t;
 
@@ -23,7 +23,8 @@ namespace ten {
 class app_t {
  public:
   app_t()
-      : app_(ten_app_create(cpp_app_on_init_cb_wrapper, nullptr, nullptr)),
+      : app_(ten_app_create(cpp_app_on_configure_cb_wrapper,
+                            cpp_app_on_init_cb_wrapper, nullptr, nullptr)),
         ten_(new ten_env_t(ten_app_get_ten_env(app_))) {
     TEN_ASSERT(ten_, "Should not happen.");
     ten_binding_handle_set_me_in_target_lang(
@@ -68,11 +69,48 @@ class app_t {
   }
 
  protected:
+  virtual void on_configure(ten_env_t &ten_env) { ten_env.on_configure_done(); }
+
   virtual void on_init(ten_env_t &ten_env) { ten_env.on_init_done(); }
 
   virtual void on_deinit(ten_env_t &ten_env) { ten_env.on_deinit_done(); }
 
  private:
+  static void cpp_app_on_configure_cb_wrapper(ten_app_t *app,
+                                              ::ten_env_t *ten_env) {
+    TEN_ASSERT(app && ten_app_check_integrity(app, true), "Should not happen.");
+    TEN_ASSERT(ten_env && ten_env_check_integrity(ten_env, true),
+               "Should not happen.");
+    TEN_ASSERT(ten_app_get_ten_env(app) == ten_env, "Should not happen.");
+
+    auto *cpp_app =
+        static_cast<app_t *>(ten_binding_handle_get_me_in_target_lang(
+            reinterpret_cast<ten_binding_handle_t *>(app)));
+    auto *cpp_ten_env =
+        static_cast<ten_env_t *>(ten_binding_handle_get_me_in_target_lang(
+            reinterpret_cast<ten_binding_handle_t *>(ten_env)));
+
+    cpp_app->on_configure_helper_for_cpp(*cpp_ten_env);
+  }
+
+  void on_configure_helper_for_cpp(ten_env_t &ten_env) {
+    // The TEN runtime does not use C++ exceptions. The use of try/catch here is
+    // merely to intercept any exceptions that might be thrown by the user's app
+    // code. If exceptions are disabled during the compilation of the TEN
+    // runtime (i.e., with -fno-exceptions), it implies that the extensions used
+    // will also not employ exceptions (otherwise it would be unreasonable). In
+    // this case, the try/catch blocks become no-ops. Conversely, if exceptions
+    // are enabled during compilation, then the try/catch here can intercept all
+    // exceptions thrown by user code that are not already caught, serving as a
+    // kind of fallback.
+    try {
+      on_configure(ten_env);
+    } catch (...) {
+      TEN_LOGW("Caught a exception of type '%s' in App on_configure().",
+               curr_exception_type_name().c_str());
+    }
+  }
+
   static void cpp_app_on_init_cb_wrapper(ten_app_t *app, ::ten_env_t *ten_env) {
     TEN_ASSERT(app && ten_app_check_integrity(app, true), "Should not happen.");
     TEN_ASSERT(ten_env && ten_env_check_integrity(ten_env, true),

core/include/ten_runtime/binding/cpp/internal/extension.h

@@ -13,7 +13,6 @@
 #include <string>
 #include <utility>
 
-#include "ten_utils/macro/check.h"
 #include "ten_runtime/binding/common.h"
 #include "ten_runtime/binding/cpp/internal/common.h"
 #include "ten_runtime/binding/cpp/internal/msg/audio_frame.h"
@@ -28,6 +27,7 @@
 #include "ten_runtime/ten_env/ten_env.h"
 #include "ten_utils/lib/json.h"
 #include "ten_utils/lib/smart_ptr.h"
+#include "ten_utils/macro/check.h"
 
 using ten_json_t = ::ten_json_t;
 using ten_env_t = struct ten_env_t;
@@ -71,6 +71,8 @@ class extension_t {
          // *' to 'void *'
         c_extension(::ten_extension_create(
             name.c_str(),
+            reinterpret_cast<ten_extension_on_configure_func_t>(
+                &proxy_on_configure),
             reinterpret_cast<ten_extension_on_init_func_t>(&proxy_on_init),
             reinterpret_cast<ten_extension_on_start_func_t>(&proxy_on_start),
             reinterpret_cast<ten_extension_on_stop_func_t>(&proxy_on_stop),
@@ -92,6 +94,8 @@ class extension_t {
     TEN_ASSERT(cpp_ten_env, "Should not happen.");
   }
 
+  virtual void on_configure(ten_env_t &ten_env) { ten_env.on_configure_done(); }
+
   virtual void on_init(ten_env_t &ten_env) { ten_env.on_init_done(); }
 
   virtual void on_start(ten_env_t &ten_env) { ten_env.on_start_done(); }
@@ -138,6 +142,20 @@ class extension_t {
     ten_shared_ptr_destroy(stop_graph_cmd);
   }
 
+  static void proxy_on_configure(ten_extension_t *extension,
+                                 ::ten_env_t *ten_env) {
+    TEN_ASSERT(extension && ten_env, "Should not happen.");
+
+    auto *cpp_extension =
+        static_cast<extension_t *>(ten_binding_handle_get_me_in_target_lang(
+            reinterpret_cast<ten_binding_handle_t *>(extension)));
+    auto *cpp_ten_env =
+        static_cast<ten_env_t *>(ten_binding_handle_get_me_in_target_lang(
+            reinterpret_cast<ten_binding_handle_t *>(ten_env)));
+
+    cpp_extension->invoke_cpp_extension_on_configure(*cpp_ten_env);
+  }
+
   static void proxy_on_init(ten_extension_t *extension, ::ten_env_t *ten_env) {
     TEN_ASSERT(extension && ten_env, "Should not happen.");
 
@@ -261,6 +279,30 @@ class extension_t {
         *cpp_ten_env, std::move(cpp_frame_ptr));
   }
 
+  void invoke_cpp_extension_on_configure(ten_env_t &ten_env) {
+    // The TEN runtime does not use C++ exceptions. The use of try/catch here is
+    // merely to intercept any exceptions that might be thrown by the user's app
+    // code. If exceptions are disabled during the compilation of the TEN
+    // runtime (i.e., with -fno-exceptions), it implies that the extensions used
+    // will also not employ exceptions (otherwise it would be unreasonable). In
+    // this case, the try/catch blocks become no-ops. Conversely, if exceptions
+    // are enabled during compilation, then the try/catch here can intercept all
+    // exceptions thrown by user code that are not already caught, serving as a
+    // kind of fallback.
+    try {
+      on_configure(ten_env);
+    } catch (std::exception &e) {
+      TEN_LOGW("Caught a exception in extension on_configure(), %s", e.what());
+
+      issue_stop_graph_cmd(ten_env);
+    } catch (...) {
+      TEN_LOGW("Caught a exception of type '%s' in extension on_configure().",
+               curr_exception_type_name().c_str());
+
+      issue_stop_graph_cmd(ten_env);
+    }
+  }
+
   void invoke_cpp_extension_on_init(ten_env_t &ten_env) {
     // The TEN runtime does not use C++ exceptions. The use of try/catch here is
     // merely to intercept any exceptions that might be thrown by the user's app

core/include/ten_runtime/binding/cpp/internal/extension_group.h

@@ -8,11 +8,11 @@
 
 #include <cstddef>
 
-#include "ten_utils/macro/check.h"
 #include "ten_runtime/binding/common.h"
 #include "ten_runtime/binding/cpp/internal/ten_env.h"
 #include "ten_runtime/extension_group/extension_group.h"
 #include "ten_utils/container/list.h"
+#include "ten_utils/macro/check.h"
 
 // NOLINTNEXTLINE(bugprone-forward-declaration-namespace)
 using ten_extension_group_t = struct ten_extension_group_t;
@@ -50,7 +50,7 @@ class extension_group_t {
  protected:
   explicit extension_group_t(const std::string &name)
       : c_extension_group_(ten_extension_group_create(
-            name.c_str(), proxy_on_init, proxy_on_deinit,
+            name.c_str(), proxy_on_configure, proxy_on_init, proxy_on_deinit,
             proxy_on_create_extensions, proxy_on_destroy_extensions)),
         cpp_ten_env(new ten_env_t(
             ten_extension_group_get_ten_env(c_extension_group_))) {
@@ -60,6 +60,8 @@ class extension_group_t {
     TEN_ASSERT(cpp_ten_env, "Should not happen.");
   }
 
+  virtual void on_configure(ten_env_t &ten_env) { ten_env.on_configure_done(); }
+
   virtual void on_init(ten_env_t &ten_env) { ten_env.on_init_done(); }
 
   virtual void on_deinit(ten_env_t &ten_env) { ten_env.on_deinit_done(); }
@@ -80,6 +82,27 @@ class extension_group_t {
   friend class ten_env_t;
   friend class app_t;
 
+  static void proxy_on_configure(ten_extension_group_t *extension_group,
+                                 ::ten_env_t *ten_env) {
+    TEN_ASSERT(extension_group &&
+                   ten_extension_group_check_integrity(extension_group, true),
+               "Invalid argument.");
+    TEN_ASSERT(ten_extension_group_get_ten_env(extension_group) &&
+                   ten_env_check_integrity(
+                       ten_extension_group_get_ten_env(extension_group), true),
+               "Should not happen.");
+
+    auto *cpp_extension_group = static_cast<extension_group_t *>(
+        ten_binding_handle_get_me_in_target_lang(
+            reinterpret_cast<ten_binding_handle_t *>(extension_group)));
+
+    auto *cpp_ten_env =
+        static_cast<ten_env_t *>(ten_binding_handle_get_me_in_target_lang(
+            reinterpret_cast<ten_binding_handle_t *>(ten_env)));
+
+    cpp_extension_group->on_configure(*cpp_ten_env);
+  }
+
   static void proxy_on_init(ten_extension_group_t *extension_group,
                             ::ten_env_t *ten_env) {
     TEN_ASSERT(extension_group &&

core/include/ten_runtime/binding/cpp/internal/ten_env.h

@@ -949,6 +949,18 @@ class ten_env_t {
     return addon_destroy_extension_async(extension, nullptr, err);
   }
 
+  bool on_configure_done() { return on_configure_done(nullptr); }
+
+  virtual bool on_configure_done(error_t *err) {
+    TEN_ASSERT(c_ten_env, "Should not happen.");
+
+    bool rc = ten_env_on_configure_done(
+        c_ten_env,
+        err != nullptr ? err->get_internal_representation() : nullptr);
+
+    return rc;
+  }
+
   virtual bool on_init_done(error_t *err) {
     TEN_ASSERT(c_ten_env, "Should not happen.");
 

core/include/ten_runtime/extension/extension.h

@@ -16,6 +16,9 @@ typedef struct ten_extension_t ten_extension_t;
 typedef struct ten_env_t ten_env_t;
 typedef struct ten_metadata_info_t ten_metadata_info_t;
 
+typedef void (*ten_extension_on_configure_func_t)(ten_extension_t *self,
+                                                  ten_env_t *ten_env);
+
 typedef void (*ten_extension_on_init_func_t)(ten_extension_t *self,
                                              ten_env_t *ten_env);
 
@@ -48,7 +51,8 @@ TEN_RUNTIME_API bool ten_extension_check_integrity(ten_extension_t *self,
                                                    bool check_thread);
 
 TEN_RUNTIME_API ten_extension_t *ten_extension_create(
-    const char *name, ten_extension_on_init_func_t on_init,
+    const char *name, ten_extension_on_configure_func_t on_configure,
+    ten_extension_on_init_func_t on_init,
     ten_extension_on_start_func_t on_start,
     ten_extension_on_stop_func_t on_stop,
     ten_extension_on_deinit_func_t on_deinit,

core/include/ten_runtime/extension_group/extension_group.h

@@ -16,6 +16,9 @@ typedef struct ten_extension_group_t ten_extension_group_t;
 typedef struct ten_metadata_info_t ten_metadata_info_t;
 typedef struct ten_env_t ten_env_t;
 
+typedef void (*ten_extension_group_on_configure_func_t)(
+    ten_extension_group_t *self, ten_env_t *ten_env);
+
 typedef void (*ten_extension_group_on_init_func_t)(ten_extension_group_t *self,
                                                    ten_env_t *ten_env);
 
@@ -32,7 +35,8 @@ TEN_RUNTIME_API bool ten_extension_group_check_integrity(
     ten_extension_group_t *self, bool check_thread);
 
 TEN_RUNTIME_API ten_extension_group_t *ten_extension_group_create(
-    const char *name, ten_extension_group_on_init_func_t on_init,
+    const char *name, ten_extension_group_on_configure_func_t on_configure,
+    ten_extension_group_on_init_func_t on_init,
     ten_extension_group_on_deinit_func_t on_deinit,
     ten_extension_group_on_create_extensions_func_t on_create_extensions,
     ten_extension_group_on_destroy_extensions_func_t on_destroy_extensions);

core/include/ten_runtime/ten_env/internal/on_xxx_done.h

@@ -13,6 +13,9 @@
 typedef struct ten_env_t ten_env_t;
 typedef struct ten_metadata_info_t ten_metadata_info_t;
 
+TEN_RUNTIME_API bool ten_env_on_configure_done(ten_env_t *self,
+                                               ten_error_t *err);
+
 TEN_RUNTIME_API bool ten_env_on_init_done(ten_env_t *self, ten_error_t *err);
 
 TEN_RUNTIME_API bool ten_env_on_deinit_done(ten_env_t *self, ten_error_t *err);

core/include_internal/ten_runtime/app/app.h

@@ -81,6 +81,7 @@ typedef struct ten_app_t {
 
   ten_list_t predefined_graph_infos;
 
+  ten_app_on_configure_func_t on_configure;
   ten_app_on_init_func_t on_init;
   ten_app_on_deinit_func_t on_deinit;
 
@@ -128,10 +129,14 @@ TEN_RUNTIME_PRIVATE_API ten_string_t *ten_app_get_uri(ten_app_t *self);
 TEN_RUNTIME_PRIVATE_API ten_protocol_context_store_t *
 ten_app_get_protocol_context_store(ten_app_t *self);
 
+TEN_RUNTIME_PRIVATE_API void ten_app_on_configure(ten_env_t *ten_env);
+
 TEN_RUNTIME_PRIVATE_API void ten_app_on_init(ten_env_t *ten_env);
 
 TEN_RUNTIME_PRIVATE_API void ten_app_on_init_done(ten_env_t *ten_env);
 
 TEN_RUNTIME_PRIVATE_API void ten_app_on_deinit(ten_app_t *self);
 
 TEN_RUNTIME_PRIVATE_API void ten_app_on_deinit_done(ten_env_t *ten_env);
+
+TEN_RUNTIME_PRIVATE_API void ten_app_on_configure_done(ten_env_t *ten_env);

core/include_internal/ten_runtime/binding/python/ten_env/ten_env.h

@@ -40,6 +40,9 @@ TEN_RUNTIME_PRIVATE_API void ten_py_ten_env_invalidate(
 
 TEN_RUNTIME_PRIVATE_API bool ten_py_ten_env_init_for_module(PyObject *module);
 
+TEN_RUNTIME_PRIVATE_API PyObject *ten_py_ten_env_on_configure_done(
+    PyObject *self, PyObject *args);
+
 TEN_RUNTIME_PRIVATE_API PyObject *ten_py_ten_env_on_init_done(PyObject *self,
                                                               PyObject *args);
 

core/include_internal/ten_runtime/engine/on_xxx.h

@@ -11,13 +11,13 @@
 typedef struct ten_env_t ten_env_t;
 
 TEN_RUNTIME_PRIVATE_API void ten_engine_on_all_extensions_added(void *self_,
-                                                              void *arg);
+                                                                void *arg);
 
 TEN_RUNTIME_PRIVATE_API void ten_engine_on_extension_thread_closed(void *self_,
-                                                                 void *arg);
+                                                                   void *arg);
 
-TEN_RUNTIME_PRIVATE_API void ten_engine_on_extension_thread_inited(void *self_,
-                                                                 void *arg);
+TEN_RUNTIME_PRIVATE_API void ten_engine_on_extension_thread_initted(void *self_,
+                                                                    void *arg);
 
 TEN_RUNTIME_PRIVATE_API void ten_engine_on_addon_create_extension_group_done(
     void *self_, void *arg);