refactor!: refine extension startup flow (#52)

With the introduction of the on_configure() initialization phase, the startup process of the
extension has been better planned.

- on_configure ~ on_configure_done + on_init ~ on_init_done: Handles its own initialization; cannot
  send or receive messages. The reason for this is that, before `on_init_done`, the extension may
  not be ready to handle external requests, so the received messages need to be temporarily stored.

- ~ on_start: The messages received before on_start() will be temporarily stored, and only after
  on_start() is called will they be sent to the extension. The reason for this is developers
  generally expect `on_start` to occur before any `on_cmd` events.

- on_start ~ on_stop_done: Normal sending and receiving of all messages and results.

BREAKING CHANGE: The initialization actions that were originally performed in on_start() need to be
moved to on_init(). This is because once on_start() is called, on_cmd() will start being received.

.vscode/launch.json

@@ -129,7 +129,7 @@
       "request": "launch",
       "program": "${workspaceFolder}/out/linux/x64/tests/standalone/ten_runtime_smoke_test",
       "args": [
-        "--gtest_filter=DataTest.MultiDestData"
+        "--gtest_filter=StandaloneTest.New"
       ],
       "cwd": "${workspaceFolder}/out/linux/x64/tests/standalone/",
       "env": {

core/include_internal/ten_runtime/extension/extension.h

@@ -43,36 +43,48 @@ typedef struct ten_timer_t ten_timer_t;
 // The relationship between several lifecycle stages and their connection to
 // sending messages:
 //
-// - on_init ~ on_init_done: Handles its own initialization; cannot send or
-//   receive messages.
+// - on_configure ~ on_configure_done + on_init ~ on_init_done: Handles its own
+//   initialization; cannot send or receive messages. The reason for this is
+//   that, before `on_init_done`, the extension may not be ready to handle
+//   external requests, so the received messages need to be temporarily stored.
 //
-// [ After everyone has completed on_init_done, they will collectively move
-//   into on_start ]
+// - ~ on_start: The messages received before on_start() will be temporarily
+//   stored, and only after on_start() is called will they be sent to the
+//   extension. The reason for this is developers generally expect `on_start` to
+//   occur before any `on_cmd` events.
 //
-// - on_start ~ on_start_done: Can send messages and receive the results
-//   of sent messages, but cannot receive other messages. Since properties are
-//   initialized within on_start, you can perform initialization actions that
-//   depend on these properties being set up. However, as it's still in the
-//   initializing phase, it won't receive messages initiated by others, avoiding
-//   the need for various checks. You can actively send messages out, though.
-//
-// - After on_start_done ~ on_stop_done: Normal sending and receiving of all
+// - on_start ~ on_stop_done: Normal sending and receiving of all
 //   messages and results.
 //
+// TODO(WEi): Does it still needs to be considered?
 // [ After everyone has completed on_stop_done, they will collectively move into
 //   on_deinit. ]
 //
 // - on_deinit ~ on_deinit_done: Handles its own de-initialization; cannot send
 //   or receive messages.
 typedef enum TEN_EXTENSION_STATE {
   TEN_EXTENSION_STATE_INIT,
-  TEN_EXTENSION_STATE_CONFIGURED,  // on_configure_done is completed.
-  TEN_EXTENSION_STATE_INITTED,     // on_init_done() is completed.
-  TEN_EXTENSION_STATE_STARTED,     // on_start_done() is completed.
-  TEN_EXTENSION_STATE_CLOSING,  // on_stop_done() is completed and could proceed
-                                // to be closed.
-  TEN_EXTENSION_STATE_DEINITING,  // on_deinit() is started.
-  TEN_EXTENSION_STATE_DEINITTED,  // on_deinit_done() is called.
+
+  // on_configure_done() is completed.
+  TEN_EXTENSION_STATE_ON_CONFIGURE_DONE,
+
+  // on_init_done() is completed.
+  TEN_EXTENSION_STATE_ON_INIT_DONE,
+
+  // on_start() is called.
+  TEN_EXTENSION_STATE_ON_START,
+
+  // on_start_done() is completed.
+  TEN_EXTENSION_STATE_ON_START_DONE,
+
+  // on_stop_done() is completed and could proceed to be closed.
+  TEN_EXTENSION_STATE_CLOSING,
+
+  // on_deinit() is called.
+  TEN_EXTENSION_STATE_ON_DEINIT,
+
+  // on_deinit_done() is called.
+  TEN_EXTENSION_STATE_ON_DEINIT_DONE,
 } TEN_EXTENSION_STATE;
 
 struct ten_extension_t {
@@ -214,9 +226,6 @@ struct ten_extension_t {
   // @}
 };
 
-TEN_RUNTIME_PRIVATE_API void ten_extension_set_state(ten_extension_t *self,
-                                                     TEN_EXTENSION_STATE state);
-
 TEN_RUNTIME_PRIVATE_API void ten_extension_determine_all_dest_extension(
     ten_extension_t *self, ten_extension_context_t *extension_context);
 

core/include_internal/ten_runtime/extension/on_xxx.h

@@ -10,22 +10,6 @@
 
 #include "ten_runtime/ten_env/ten_env.h"
 
-/**
- * @brief Indicate that extension on_configure is completed.
- */
-typedef struct ten_extension_on_configure_done_t {
-  // Indicates which extension's on_configure ends.
-  ten_extension_t *extension;
-} ten_extension_on_configure_done_t;
-
-/**
- * @brief Indicate that extension on_init is completed.
- */
-typedef struct ten_extension_on_init_done_t {
-  // Indicates which extension's on_init ends.
-  ten_extension_t *extension;
-} ten_extension_on_init_done_t;
-
 /**
  * @brief Indicate that extension on_start/on_stop/on_deinit is completed.
  */
@@ -49,9 +33,3 @@ TEN_RUNTIME_PRIVATE_API void ten_extension_on_start_done(ten_env_t *self);
 TEN_RUNTIME_PRIVATE_API void ten_extension_on_stop_done(ten_env_t *self);
 
 TEN_RUNTIME_PRIVATE_API void ten_extension_on_deinit_done(ten_env_t *self);
-
-TEN_RUNTIME_PRIVATE_API void ten_extension_on_configure_done_destroy(
-    ten_extension_on_configure_done_t *self);
-
-TEN_RUNTIME_PRIVATE_API void ten_extension_on_init_done_destroy(
-    ten_extension_on_init_done_t *self);

core/include_internal/ten_runtime/extension_context/extension_context.h

@@ -49,7 +49,6 @@ struct ten_extension_context_t {
   size_t extension_threads_cnt_of_initted;
   size_t extension_threads_cnt_of_all_extensions_added_to_engine;
   size_t extension_threads_cnt_of_all_extensions_stopped;
-  size_t extension_threads_cnt_of_all_extensions_initted;
   size_t extension_threads_cnt_of_closing_flag_is_set;
   size_t extension_threads_cnt_of_closed;
 

core/include_internal/ten_runtime/extension_thread/extension_thread.h

@@ -26,22 +26,15 @@ typedef struct ten_extension_context_t ten_extension_context_t;
 typedef struct ten_extension_t ten_extension_t;
 
 typedef enum TEN_EXTENSION_THREAD_STATE {
-  // All received messages will be kept in a temporary buffer, and wait until
-  // the state switched to NORMAL.
   TEN_EXTENSION_THREAD_STATE_INIT,
-
-  // All received messages will be fed into the extensions directly.
+  TEN_EXTENSION_THREAD_STATE_CREATING_EXTENSIONS,
   TEN_EXTENSION_THREAD_STATE_NORMAL,
-
-  // All the extensions have been started completely. The extension thread could
-  // be 'suspended' only in this state.
-  TEN_EXTENSION_THREAD_STATE_ALL_STARTED,
-
-  // Give extension a chance to do something before the whole engine shuting
-  // down.
   TEN_EXTENSION_THREAD_STATE_PREPARE_TO_CLOSE,
 
-  // All received messages will be dropped.
+  // All the extensions of the extension thread have been closed, so the
+  // extension thread can now proceed with its own closing flow. Additionally,
+  // since the extensions have been closed, any messages received by the
+  // extension thread from this point on will be directly dropped.
   TEN_EXTENSION_THREAD_STATE_CLOSING,
 
   // The closing procedure is completed, so the extension thread can be
@@ -59,6 +52,7 @@ typedef struct ten_extension_thread_t {
   ten_sanitizer_thread_check_t thread_check;
 
   TEN_EXTENSION_THREAD_STATE state;
+  bool is_close_triggered;
 
   ten_mutex_t *lock_mode_lock;
   bool in_lock_mode;
@@ -68,8 +62,6 @@ typedef struct ten_extension_thread_t {
   ten_list_t extensions;  // ten_extension_t*
   size_t extensions_cnt_of_added_to_engine;
   size_t extensions_cnt_of_deleted_from_engine;
-  size_t extensions_cnt_of_on_init_done;
-  size_t extensions_cnt_of_on_start_done;
   size_t extensions_cnt_of_on_stop_done;
   size_t extensions_cnt_of_set_closing_flag;
 
@@ -81,6 +73,7 @@ typedef struct ten_extension_thread_t {
   ten_extension_context_t *extension_context;
 
   ten_runloop_t *runloop;
+  ten_event_t *runloop_is_ready_to_use;
 } ten_extension_thread_t;
 
 TEN_RUNTIME_API bool ten_extension_thread_not_call_by_me(
@@ -103,9 +96,6 @@ TEN_RUNTIME_PRIVATE_API void ten_extension_thread_attach_to_context_and_group(
     ten_extension_thread_t *self, ten_extension_context_t *extension_context,
     ten_extension_group_t *extension_group);
 
-TEN_RUNTIME_PRIVATE_API void ten_extension_thread_attach_to_group(
-    ten_extension_thread_t *self, ten_extension_group_t *extension_group);
-
 TEN_RUNTIME_PRIVATE_API void ten_extension_thread_destroy(
     ten_extension_thread_t *self);
 

core/include_internal/ten_runtime/extension_thread/msg_interface/common.h

@@ -14,7 +14,7 @@
 
 typedef struct ten_extension_thread_t ten_extension_thread_t;
 
-TEN_RUNTIME_PRIVATE_API void ten_extension_thread_handle_msg_async(
+TEN_RUNTIME_PRIVATE_API void ten_extension_thread_handle_in_msg_async(
     ten_extension_thread_t *self, ten_shared_ptr_t *msg);
 
 TEN_RUNTIME_PRIVATE_API void ten_extension_thread_dispatch_msg(

core/include_internal/ten_runtime/extension_thread/on_xxx.h

@@ -35,21 +35,9 @@ ten_extension_thread_on_extension_deleted_from_engine(void *self_, void *arg);
 TEN_RUNTIME_PRIVATE_API void
 ten_extension_thread_on_extension_group_on_init_done(void *self_, void *arg);
 
-TEN_RUNTIME_PRIVATE_API void
-ten_extension_thread_on_extension_on_configure_done(void *self_, void *arg);
-
-TEN_RUNTIME_PRIVATE_API void ten_extension_thread_on_extension_on_init_done(
-    void *self_, void *arg);
-
-TEN_RUNTIME_PRIVATE_API void ten_extension_thread_on_extension_on_start_done(
-    void *self_, void *arg);
-
 TEN_RUNTIME_PRIVATE_API void ten_extension_thread_on_extension_on_stop_done(
     void *self_, void *arg);
 
-TEN_RUNTIME_PRIVATE_API void ten_extension_thread_call_all_extensions_on_start(
-    void *self_, void *arg);
-
 TEN_RUNTIME_PRIVATE_API void ten_extension_thread_call_all_extensions_on_deinit(
     void *self_, void *arg);
 
@@ -72,9 +60,6 @@ ten_extension_thread_on_extension_group_on_deinit_done(void *self_, void *arg);
 TEN_RUNTIME_PRIVATE_API void ten_extension_thread_on_all_extensions_deleted(
     void *self_, void *arg);
 
-TEN_RUNTIME_PRIVATE_API void ten_extension_thread_on_all_extensions_created(
-    void *self_, void *arg);
-
 TEN_RUNTIME_PRIVATE_API void
 ten_extension_thread_on_addon_create_extension_done(void *self_, void *arg);
 

core/include_internal/ten_runtime/ten_env_proxy/ten_env_proxy.h

@@ -39,7 +39,12 @@ typedef struct ten_notify_data_t {
 TEN_RUNTIME_API bool ten_env_proxy_check_integrity(ten_env_proxy_t *self);
 
 TEN_RUNTIME_API size_t ten_env_proxy_get_thread_cnt(ten_env_proxy_t *self,
-                                                  ten_error_t *err);
+                                                    ten_error_t *err);
 
 TEN_RUNTIME_PRIVATE_API bool ten_env_proxy_acquire(ten_env_proxy_t *self,
-                                                 ten_error_t *err);
+                                                   ten_error_t *err);
+
+TEN_RUNTIME_API bool ten_env_proxy_notify_async(ten_env_proxy_t *self,
+                                                ten_notify_func_t notify_func,
+                                                void *user_data,
+                                                ten_error_t *err);

core/include_internal/ten_runtime/test/extension_test.h

@@ -27,6 +27,7 @@ TEN_RUNTIME_API void ten_extension_test_destroy(ten_extension_test_t *self);
 
 typedef struct ten_extension_test_new_t {
   ten_thread_t *test_app_thread;
+  ten_string_t test_extension_addon_name;
   ten_env_proxy_t *test_app_ten_env_proxy;
   ten_event_t *test_app_ten_env_proxy_create_completed;
 } ten_extension_test_new_t;
@@ -35,3 +36,9 @@ TEN_RUNTIME_API ten_extension_test_new_t *ten_extension_test_create_new(void);
 
 TEN_RUNTIME_API void ten_extension_test_destroy_new(
     ten_extension_test_new_t *self);
+
+TEN_RUNTIME_API void ten_extension_test_start_new(
+    ten_extension_test_new_t *self);
+
+TEN_RUNTIME_API void ten_extension_test_add_addon(
+    ten_extension_test_new_t *self, const char *addon_name);

core/src/ten_runtime/binding/python/native/common/common.c

@@ -8,10 +8,10 @@
 
 #include "include_internal/ten_runtime/binding/python/common/common.h"
 #include "include_internal/ten_runtime/binding/python/common/python_stuff.h"
-#include "ten_utils/macro/check.h"
 #include "ten_utils/container/list.h"
 #include "ten_utils/container/list_node_str.h"
 #include "ten_utils/lib/string.h"
+#include "ten_utils/macro/check.h"
 
 int ten_py_is_initialized(void) { return Py_IsInitialized(); }
 

core/src/ten_runtime/binding/python/native/ten_env/ten_env_on_configure_done.c

@@ -46,9 +46,9 @@ PyObject *ten_py_ten_env_on_configure_done(PyObject *self, PyObject *args) {
   if (py_ten->c_ten_env->attach_to == TEN_ENV_ATTACH_TO_ADDON) {
     rc = ten_env_on_configure_done(py_ten->c_ten_env, &err);
   } else {
-    rc = ten_env_proxy_notify(py_ten->c_ten_env_proxy,
-                              ten_env_proxy_notify_on_configure_done, NULL,
-                              false, &err);
+    rc = ten_env_proxy_notify_async(py_ten->c_ten_env_proxy,
+                                    ten_env_proxy_notify_on_configure_done,
+                                    NULL, &err);
   }
 
   if (!rc) {

core/src/ten_runtime/binding/python/native/ten_env/ten_env_on_init_done.c

@@ -46,9 +46,8 @@ PyObject *ten_py_ten_env_on_init_done(PyObject *self, PyObject *args) {
   if (py_ten->c_ten_env->attach_to == TEN_ENV_ATTACH_TO_ADDON) {
     rc = ten_env_on_init_done(py_ten->c_ten_env, &err);
   } else {
-    rc = ten_env_proxy_notify(py_ten->c_ten_env_proxy,
-                              ten_env_proxy_notify_on_init_done, NULL, false,
-                              &err);
+    rc = ten_env_proxy_notify_async(
+        py_ten->c_ten_env_proxy, ten_env_proxy_notify_on_init_done, NULL, &err);
   }
 
   if (!rc) {

core/src/ten_runtime/binding/python/native/ten_env/ten_env_on_start_done.c

@@ -39,9 +39,8 @@ PyObject *ten_py_ten_env_on_start_done(PyObject *self,
   ten_error_t err;
   ten_error_init(&err);
 
-  TEN_UNUSED bool rc = ten_env_proxy_notify(py_ten->c_ten_env_proxy,
-                                            ten_env_proxy_notify_on_start_done,
-                                            NULL, false, &err);
+  TEN_UNUSED bool rc = ten_env_proxy_notify_async(
+      py_ten->c_ten_env_proxy, ten_env_proxy_notify_on_start_done, NULL, &err);
   TEN_ASSERT(rc, "Should not happen.");
 
   ten_error_deinit(&err);

core/src/ten_runtime/binding/python/native/ten_env/ten_env_on_stop_done.c

@@ -39,9 +39,8 @@ PyObject *ten_py_ten_env_on_stop_done(PyObject *self,
   ten_error_t err;
   ten_error_init(&err);
 
-  TEN_UNUSED bool rc = ten_env_proxy_notify(py_ten->c_ten_env_proxy,
-                                            ten_env_proxy_notify_on_stop_done,
-                                            NULL, false, &err);
+  TEN_UNUSED bool rc = ten_env_proxy_notify_async(
+      py_ten->c_ten_env_proxy, ten_env_proxy_notify_on_stop_done, NULL, &err);
 
   ten_error_deinit(&err);