From 72bdcc17165016d5fc242b649224897dd84a459d Mon Sep 17 00:00:00 2001
From: 4t145 <u4t145@163.com>
Date: Wed, 18 Oct 2023 10:35:40 +0800
Subject: [PATCH] add more comments

---
 tardis/src/config/config_processor.rs |  1 -
 tardis/src/lib.rs                     | 20 +++++++++++++-------
 tardis/src/utils/tardis_component.rs  |  4 ++++
 tardis/src/utils/tardis_static.rs     |  1 -
 tardis/src/web/web_client.rs          | 10 +++++++---
 5 files changed, 24 insertions(+), 12 deletions(-)

diff --git a/tardis/src/config/config_processor.rs b/tardis/src/config/config_processor.rs
index 859efc20..fe7e82fb 100644
--- a/tardis/src/config/config_processor.rs
+++ b/tardis/src/config/config_processor.rs
@@ -36,7 +36,6 @@ impl TardisConfig {
     pub(crate) async fn init(relative_path: Option<&str>) -> TardisResult<TardisConfig> {
         let profile = fetch_profile();
         let parent_path = env::current_dir().expect("[Tardis.Config] Current path get error");
-
         info!(
             "[Tardis.Config] Initializing, base path:{:?}, relative path:{:?}, profile:{}",
             parent_path, relative_path, profile
diff --git a/tardis/src/lib.rs b/tardis/src/lib.rs
index 7b8de5d7..57bf707b 100644
--- a/tardis/src/lib.rs
+++ b/tardis/src/lib.rs
@@ -498,6 +498,10 @@ impl TardisFuns {
     }
 
     /// Get the custom configuration object / 获取自定义配置对象
+    /// 
+    /// # Panic
+    /// If the configuration object does not exist, this will fallback to the default config. 
+    /// Though, if the default config cannot be deserialized as `T`, this will panic.
     pub fn cs_config<T: 'static + for<'a> Deserialize<'a> + Any + Send + Sync>(code: &str) -> Arc<T> {
         let code = code.to_lowercase();
         let code = code.as_str();
@@ -1009,15 +1013,16 @@ impl TardisFuns {
         Self::shutdown_internal(true).await
     }
 
-    /// shutdown with inherit mode
+    /// hot reload tardis instance by a new [`TardisConfig`].
     ///
-    /// this shutdown function will retain some user setted configs like webserver moudules for next init
-    pub async fn shutdown_inherit() -> TardisResult<()> {
-        Self::shutdown_internal(false).await
-    }
-
-    /// hot reload tardis instance
+    /// there should have only one hot reload task at the same time. If it's called when other reload task is running,
+    /// it will wait until the other task finished.
     pub async fn hot_reload(conf: TardisConfig) -> TardisResult<()> {
+        use tokio::sync::Semaphore;
+        tardis_static! {
+            tardis_load_semaphore: Semaphore = Semaphore::new(1);
+        }
+        let _sync = tardis_load_semaphore().acquire().await.expect("reload_semaphore is static so it shouldn't be closed.");
         let new_custom_config = conf.cs.iter().map(|(k, v)| (k.clone(), CachedJsonValue::new(v.clone()))).collect::<HashMap<_, _>>();
         let new_framework_config = conf.fw;
         #[allow(unused_variables)]
@@ -1154,6 +1159,7 @@ impl TardisFunsInst {
         &self.module_code
     }
 
+    /// Get current module's config from custom configs. 
     pub fn conf<T: 'static + for<'a> Deserialize<'a> + Any + Send + Sync>(&self) -> Arc<T> {
         TardisFuns::cs_config(&self.module_code)
     }
diff --git a/tardis/src/utils/tardis_component.rs b/tardis/src/utils/tardis_component.rs
index ac71f5a0..38cd0216 100644
--- a/tardis/src/utils/tardis_component.rs
+++ b/tardis/src/utils/tardis_component.rs
@@ -118,10 +118,14 @@ impl<T> TardisComponentMapInner<T> {
         self.replace_inner(std::iter::empty())
     }
 
+    /// Initialize by an [`ArcMap`] initializer.
+    /// 
+    /// this method will clear the current map and replace it with the new one witch is created from the initializer.
     pub async fn init_by<I>(&self, initializer: &I) -> TardisResult<ArcMap<T>>
     where
         ArcMap<T>: InitBy<I>,
     {
+        self.clear();
         let new_inner = HashMap::<ModuleCode, Arc<T>>::init_by(initializer).await?;
         let wg = &mut *self.inner.write().expect(Self::LOCK_EXPECT);
         Ok(std::mem::replace(wg, new_inner))
diff --git a/tardis/src/utils/tardis_static.rs b/tardis/src/utils/tardis_static.rs
index d40d254a..210a468e 100644
--- a/tardis/src/utils/tardis_static.rs
+++ b/tardis/src/utils/tardis_static.rs
@@ -77,7 +77,6 @@ fn test_tardis_static_macro() {
             retrive_config().await
         };
     }
-
     tardis_static! {
         config_defualt: Config;
     }
diff --git a/tardis/src/web/web_client.rs b/tardis/src/web/web_client.rs
index 26bdca94..c4fcac51 100644
--- a/tardis/src/web/web_client.rs
+++ b/tardis/src/web/web_client.rs
@@ -32,8 +32,12 @@ impl TardisRequestBody for () {
         builder
     }
 }
-struct PlainText<T>(T);
-struct Json<'a, T>(&'a T);
+
+/// Plain text body for [`TardisWebClient`], 
+pub struct PlainText<T>(T);
+
+/// Json body for [`TardisWebClient`], 
+pub struct Json<'a, T>(&'a T);
 
 impl<T: Into<String>> TardisRequestBody for PlainText<T> {
     fn apply_on(self, builder: RequestBuilder) -> RequestBuilder {
@@ -47,7 +51,7 @@ impl<T: Serialize> TardisRequestBody for Json<'_, T> {
     }
 }
 
-/// convert a str pair into a string pair
+/// convert a str pair into a string pair, it may be helpful when you want to use a string literal as a header for [`TardisWebClient`]
 pub fn str_pair_to_string_pair(p: (&str, &str)) -> (String, String) {
     (p.0.to_owned(), p.1.to_owned())
 }