docs: 增加doxygen.conf，便于生成本地文档

Author: CodingHanYa

README.md

@@ -24,6 +24,7 @@
 - 稳定的：利用`std::function`的小任务优化减少内存碎片、拥有良好的异步线程异常处理机制。
 - 兼容性：纯C++11实现，跨平台，且兼容C++11以上版本。
 
+
 ## 主要模块
 
 ### **workbranch**
@@ -311,6 +312,15 @@ threads: 12 |  tasks: 100000000  |  time-cost: 5.17316 (s)
 
 ## 如何使用
 
+#### 生成doxygen文档
+请提前安装doxygen
+``` shell
+# 与workspace同级目录中（Linux）
+doxygen ./doxygen.conf
+```
+生成的文档在`workspace/docs/`中，可以在浏览器中打开`workspace/docs/html/index.html`并查看接口。
+
+
 #### 简单使用
 
 ```shell

doxygen.conf

@@ -0,0 +1,57 @@
+# 项目名称
+PROJECT_NAME = workspace
+
+# 项目版本号
+PROJECT_NUMBER = 1.0
+
+# 输入目录
+INPUT = include README.md
+
+# 输出目录
+OUTPUT_DIRECTORY = docs
+
+# 递归处理子目录
+RECURSIVE = YES
+
+# 匹配的文件模式
+FILE_PATTERNS = *.cpp *.h
+
+# 使用Markdown格式处理注释
+MARKDOWN_SUPPORT = YES
+
+# 生成的文档类型
+GENERATE_HTML = YES
+GENERATE_XML = YES
+
+# 排除某些文件
+EXCLUDE_PATTERNS = */tests/*
+
+# 自动生成函数的调用图
+CALL_GRAPH = YES
+
+# 自动生成函数的调用关系图
+CALLER_GRAPH = YES
+
+# 自动生成类的继承关系图
+COLLABORATION_GRAPH = YES
+
+# 自动生成文件的依赖关系图
+INCLUDE_GRAPH = YES
+
+# 自动生成文件的包含关系图
+INCLUDED_BY_GRAPH = YES
+
+# 是否生成源代码文件的副本
+SOURCE_BROWSER = YES
+
+# 是否生成内部类的文档
+INLINE_INHERITED_MEMB = YES
+
+# 是否生成私有类成员的文档
+EXTRACT_PRIVATE = YES
+
+# 是否生成静态成员的文档
+EXTRACT_STATIC = YES
+
+# 强制提取所有文档内的所有元素
+EXTRACT_ALL = YES

include/workspace/workbranch.h

@@ -17,7 +17,7 @@ class workbranch {
     using worker = autothread<detach>;
     using worker_map = std::map<worker::id, worker>;
 
-    sz_t decline = 0;
+    sz_t decline = 0; 
     sz_t task_done_workers = 0;
     bool is_waiting = false;
     bool destructing = false;
@@ -74,17 +74,17 @@ class workbranch {
 
     /**
      * @brief Wait for all tasks done.
-     * @brief This interface will pause all threads(workers) in workbranch to relieve system's stress.
-     * @param timeout timeout for waiting
+     * @brief This interface will pause all threads(workers) in workbranch to relieve system's stress. 
+     * @param timeout timeout for waiting (ms)
      * @return return true if all tasks done 
      */
     bool wait_tasks(unsigned timeout = -1) {
         bool res;
         {
             std::unique_lock<std::mutex> locker(lok);
-            is_waiting = true;
+            is_waiting = true; // task_done_workers == 0
             res = task_done_cv.wait_for(locker, std::chrono::milliseconds(timeout), [this]{
-                return task_done_workers >= workers.size();  // use ">=" to avoid supervisor delete workers
+                return task_done_workers >= workers.size();  // use ">=" to avoid supervisor delete workers  
             }); 
             task_done_workers = 0;
             is_waiting = false;
@@ -117,7 +117,7 @@ class workbranch {
      * @return void
      */
     template <typename T = normal, typename F, 
-        typename R = details::result_of_t<F>, 
+        typename R = details::result_of_t<F>,  
         typename DR = typename std::enable_if<std::is_void<R>::value>::type>
     auto submit(F&& task) -> typename std::enable_if<std::is_same<T, normal>::value>::type {
         tq.push_back([task]{
@@ -128,7 +128,7 @@ class workbranch {
             } catch (...) {
                 std::cerr<<"workspace: worker["<< std::this_thread::get_id()<<"] caught unknown exception\n"<<std::flush;
             }
-        });
+        }); // function
     }
 
     /**
@@ -154,6 +154,7 @@ class workbranch {
     /**
      * @brief async execute tasks 
      * @param task runnable object (sequence)
+     * @param tasks other parameters
      * @return void
      */
     template <typename T, typename F, typename... Fs>
@@ -172,7 +173,6 @@ class workbranch {
     /**
      * @brief async execute the task
      * @param task runnable object (normal)
-     * @param dummy dummy
      * @return std::future<R>
      */
     template <typename T = normal, typename F, 
@@ -200,7 +200,6 @@ class workbranch {
     /**
      * @brief async execute the task
      * @param task runnable object (urgent)
-     * @param dummy dummy
      * @return std::future<R>
      */
     template <typename T,  typename F,  
@@ -226,16 +225,16 @@ class workbranch {
     }
 
 private:
-    // loop
+    // thread's default loop
     void mission() {
         std::function<void()> task;
         while (true) {
             if (decline <= 0 && tq.try_pop(task)) {
                 task(); 
             } else if (decline > 0) {
                 std::lock_guard<std::mutex> lock(lok);
-                if (decline > 0 && decline--) {
-                    workers.erase(std::this_thread::get_id());
+                if (decline > 0 && decline--) { // double check
+                    workers.erase(std::this_thread::get_id()); 
                     if (is_waiting)  
                         task_done_cv.notify_one();
                     if (destructing) 
@@ -247,9 +246,9 @@ class workbranch {
                     std::unique_lock<std::mutex> locker(lok);
                     task_done_workers++;
                     task_done_cv.notify_one();
-                    thread_cv.wait(locker);
+                    thread_cv.wait(locker);  
                 } else {
-                    std::this_thread::yield();
+                    std::this_thread::yield(); 
                 }
             }
         }

test/test_workbranch.cc

@@ -2,7 +2,7 @@
 
 int main() {
 
-    wsp::workbranch br(2);
+    wsp::workbranch br(2); // 2 threads
 
     // add a worker
     br.add_worker();
@@ -11,21 +11,23 @@ int main() {
     // delete a worker
     br.del_worker();
     br.del_worker();
-    std::cout<<"workers: "<<br.num_workers()<<std::endl;
+    std::cout<<"workers: "<<br.num_workers()<<std::endl; // 1 worker
 
     // normal task
-    br.submit([]{std::cout<<"<normal>"<<std::endl;}); 
+    br.submit([]{std::cout<<"<normal>"<<std::endl;});  // FIFO
 
     // normal task
     br.submit<wsp::task::nor>([]{std::cout<<"<normal>"<<std::endl;}); 
 
     // urgent task, executed as soon as possible
-    br.submit<wsp::task::urg>([]{std::cout<<"<urgent>"<<std::endl;});   // 
+    br.submit<wsp::task::urg>([]{std::cout<<"<urgent>"<<std::endl;});    
 
     // sequence task
     br.submit<wsp::task::seq>([]{std::cout<<"<sequence1>"<<std::endl;},
                               []{std::cout<<"<sequence2>"<<std::endl;},
-                              []{std::cout<<"<sequence3>"<<std::endl;});
+                              []{std::cout<<"<sequence3>"<<std::endl;}); 
     // wait for tasks done
     br.wait_tasks(); 
+
+    // distruct -> close the threadpool
 }