coostdocs
diff --git a/‎config.toml‎
Lines changed: 1 addition & 1 deletion b/‎config.toml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎content/cn/about/co.md‎
Lines changed: 63 additions & 29 deletions b/‎content/cn/about/co.md‎
Lines changed: 63 additions & 29 deletions
diff --git a/‎content/cn/co/_index.md‎
Lines changed: 1 addition & 1 deletion b/‎content/cn/co/_index.md‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎content/cn/co/benchmark.md‎
Lines changed: 105 additions & 0 deletions b/‎content/cn/co/benchmark.md‎
Lines changed: 105 additions & 0 deletions
@@ -80,7 +80,7 @@ enableGitInfo = true
 
   # Set source repository location.
   # Used for 'Last Modified' and 'Edit this page' links.
-  BookRepo = 'https://github.com/cocoyaxi/codoc'
+  BookRepo = 'https://github.com/coostdocs/codoc'
 
   # (Optional, default 'commit') Specifies commit portion of the link to the page's last modified
   # commit hash for 'doc' page type.
 
@@ -12,17 +12,17 @@ title: "简介"
 
 **[coost](https://github.com/idealvin/coost)** 是一个**兼具性能与易用性**的跨平台 C++ 基础库，其目标是打造一把 C++ 开发神器，让 C++ 编程变得简单、轻松、愉快。
 
-coost 原名为 co，后改为 cocoyaxi，前者过短，后者过长，取中庸之道，又改为 coost。它曾被称为小型 [boost](https://www.boost.org/) 库，与 boost 相比，coost 小而精美，在 **linux 与 mac 上编译出来的静态库仅 1M 左右大小**，却包含了不少强大的功能：
+coost 简称为 co，曾被称为小型 [boost](https://www.boost.org/) 库，与 boost 相比，coost 小而精美，在 **linux 与 mac 上编译出来的静态库仅 1M 左右大小**，却包含了不少强大的功能：
 
 
 {{< columns >}}
 
 - 命令行与配置文件解析(flag)
 - **高性能日志库(log)**
-- 单元测试框架(unitest)
+- 单元测试框架
+- 基准测试框架
 - **go-style 协程**
 - 基于协程的网络编程框架
-- 高效 JSON 库
 - **基于 JSON 的 RPC 框架**
 
 <--->
@@ -38,7 +38,7 @@ coost 原名为 co，后改为 cocoyaxi，前者过短，后者过长，取中
 <--->
 
 - **面向玄学编程**
-- LruMap
+- 高效 JSON 库
 - hash 库
 - path 库
 - 文件系统操作(fs)
@@ -93,21 +93,21 @@ xmake r co
 
 ### 使用 coost 开发 C++ 项目
 
-最简单的，可以直接包含 [co/all.h](https://github.com/idealvin/coost/blob/master/include/co/all.h)，使用 coost 中的所有特性。如果担心影响编译速度，也可以只包含需要用到的头文件，如包含 [co/co.h](https://github.com/idealvin/coost/blob/master/include/co/co.h)，可以使用 co/flag, co/log 以及协程相关的所有特性。
+最简单的，可以直接包含 [co/all.h](https://github.com/idealvin/coost/blob/master/include/co/all.h)，使用 coost 中的所有特性。如果担心影响编译速度，也可以只包含需要用到的头文件，如包含 [co/co.h](https://github.com/idealvin/coost/blob/master/include/co/co.h)，可以使用 flag, log 以及协程相关的所有特性。
 
 ```cpp
 #include "co/all.h"
 
 DEF_string(s, "nice", "");
 
 int main(int argc, char** argv) {
-    flag::init(argc, argv);
+    flag::parse(argc, argv);
     LOG << FLG_s;
     return 0;
 }
 ```
 
-上面是一个简单的例子，main 函数第一行用于解析命令行参数及配置文件。coost 中的部分组件用 flag 定义配置项，因此需要在 main 函数开头调用 `flag::init()` 进行初始化。
+上面是一个简单的例子，main 函数第一行用于解析命令行参数及配置文件。coost 中的部分组件用 flag 定义配置项，因此需要在 main 函数开头调用 `flag::parse()` 进行初始化。
 
 用户也可以用宏 `DEF_main` 定义 main 函数：
 
@@ -122,7 +122,7 @@ DEF_main(argc, argv) {
 }
 ```
 
-`DEF_main` 将 main 函数中的代码放到协程中运行，内部已经调用了 `flag::init()`，用户无需手动调用。
+`DEF_main` 将 main 函数中的代码放到协程中运行，内部已经调用了 `flag::parse()`，用户无需手动调用。
 
 
 
@@ -131,7 +131,7 @@ DEF_main(argc, argv) {
 
 ### 内存分配器
 
-ptmalloc、jemalloc、tcmalloc 以及 mimalloc 等内存分配器，小内存释放后大概率不会归还给操作系统，这可能**造成释放大量小内存后内存占用量却始终不降的疑似内存泄漏的现象**。为解决此问题，coost 设计了一个专用的内存分配器(co/malloc)，在兼顾性能的同时，会尽可能多的将释放的内存归还给系统，有利于降低程序的内存占用量，在实测中也取得了良好的效果。
+ptmalloc、jemalloc、tcmalloc 以及 mimalloc 等内存分配器，小内存释放后大概率不会归还给操作系统，这可能**造成释放大量小内存后内存占用量却始终不降的疑似内存泄漏的现象**。为解决此问题，coost 设计了一个专用的内存分配器，在兼顾性能的同时，会尽可能多的将释放的内存归还给系统，有利于降低程序的内存占用量，在实测中也取得了良好的效果。
 
 [co/test](https://github.com/idealvin/coost/blob/master/test/mem.cc) 中提供了简单的测试代码，可以执行如下命令编译及运行：
 
@@ -150,7 +150,7 @@ xmake r mem -t 4 -s
 
 表中数据为平均耗时，单位为纳秒(ns)，linux 是在 Windows WSL 中运行的 ubuntu 系统，speedup 是 coost 内存分配器相对于系统内存分配器的性能提升倍数。
 
-可以看到，**co::alloc 在 Linux 上比 ::malloc 提升了近 99 倍**，这其中的一个重要原因是 ptmalloc 在多线程环境中锁竞争开销较大，而 co/malloc 在设计上尽可能避免锁的使用，小块内存的分配、释放不需要锁，跨线程释放时连自旋锁也不用。
+可以看到，**co::alloc 在 Linux 上比 ::malloc 提升了近 99 倍**，这其中的一个重要原因是 ptmalloc 在多线程环境中锁竞争开销较大，而 coost 内存分配器在设计上尽可能避免锁的使用，小块内存的分配、释放不需要锁，跨线程释放时连自旋锁也不用。
 
 
 
@@ -172,7 +172,7 @@ xmake r mem -t 4 -s
 | 4 | 0.206712 | 4.764238 | 0.316607 | 0.743227 | 23.0/2.3 |
 | 8 | 0.302088 | 3.963644 | 0.406025 | 1.417387 | 13.1/3.5 |
 
-上表是分别[用 1、2、4、8 个线程打印 100 万条日志](https://github.com/idealvin/coost/tree/benchmark)的耗时，单位为秒，speedup 是 co/log 在 linux、windows 平台相对于 spdlog 的性能提升倍数。
+上表是分别[用 1、2、4、8 个线程打印 100 万条日志](https://github.com/idealvin/coost/tree/benchmark)的耗时，单位为秒，speedup 是 co.log 在 linux、windows 平台相对于 spdlog 的性能提升倍数。
 
 
 
@@ -184,7 +184,7 @@ xmake r mem -t 4 -s
 | mac | 783 | 1097 | 1289 | 1658 | 1.6/1.5 |
 | linux | 468 | 764 | 1359 | 1070 | 2.9/1.4 |
 
-上表是将 [twitter.json](https://raw.githubusercontent.com/simdjson/simdjson/master/jsonexamples/twitter.json) 最小化后测得的 stringify 及 parse 的平均耗时，单位为微秒(us)，speedup 是 co/json 在 stringify、parse 方面相对于 rapidjson 的性能提升倍数。
+上表是将 [twitter.json](https://raw.githubusercontent.com/simdjson/simdjson/master/jsonexamples/twitter.json) 最小化后测得的 stringify 及 parse 的平均耗时，单位为微秒(us)，speedup 是 co.json 在 stringify、parse 方面相对于 rapidjson 的性能提升倍数。
 
 
 
@@ -193,7 +193,7 @@ xmake r mem -t 4 -s
 
 ### 面向玄学编程
 
-[co/god.h](https://github.com/idealvin/coost/blob/master/include/co/god.h) 提供模板相关的一些功能。模板用到深处，代码深奥难懂，有些 C++ 程序员称之为面向玄学编程。
+[co/god.h](https://github.com/idealvin/coost/blob/master/include/co/god.h) 提供模板相关的一些功能。模板用到深处有点玄，有些 C++ 程序员称之为面向玄学编程。
 
 ```cpp
 #include "co/god.h"
@@ -223,7 +223,7 @@ DEF_uint32(u, 0, "xxx");
 DEF_string(s, "", "xx");
 
 int main(int argc, char** argv) {
-    flag::init(argc, argv);
+    flag::parse(argc, argv);
     COUT << "x: " << FLG_x;
     COUT << "y: " << FLG_y;
     COUT << "debug: " << FLG_debug;
@@ -259,7 +259,7 @@ log 支持两种类型的日志：一种是 level log，分为 debug, info, warn
 #include "co/log.h"
 
 int main(int argc, char** argv) {
-    flag::init(argc, argv);
+    flag::parse(argc, argv);
 
     TLOG("xx") << "s" << 23; // topic log
     DLOG << "hello " << 23;  // debug
@@ -305,14 +305,14 @@ DEF_test(os) {
 } // namespace test
 ```
 
-上面是一个简单的例子，`DEF_test` 宏定义了一个测试单元，实际上就是一个函数(类中的方法)。`DEF_case` 宏定义了测试用例，每个测试用例实际上就是一个代码块。main 函数一般只需要下面几行：
+上面是一个简单的例子，`DEF_test` 宏定义了一个测试单元，实际上就是一个函数。`DEF_case` 宏定义了测试用例，每个测试用例实际上就是一个代码块。main 函数一般只需要下面几行：
 
 ```cpp
 #include "co/unitest.h"
 
 int main(int argc, char** argv) {
-    flag::init(argc, argv);
-    unitest::run_all_tests();
+    flag::parse(argc, argv);
+    unitest::run_tests();
     return 0;
 }
 ```
@@ -325,6 +325,41 @@ xmake r unitest -os  # 仅运行 os 单元中的测试用例
 ```
 
 
+### 基准测试
+
+[benchmark](../../co/benchmark/) 是一个简单易用的基准测试框架。
+
+```cpp
+#include "co/benchmark.h"
+#include "co/mem.h"
+
+BM_group(malloc) {
+    void* p;
+
+    BM_add(::malloc)(
+        p = ::malloc(32);
+    );
+    BM_use(p);
+
+    BM_add(co::alloc)(
+        p = co::alloc(32);
+    );
+    BM_use(p);
+}
+
+int main(int argc, char** argv) {
+    flag::parse(argc, argv);
+    bm::run_benchmarks();
+    return 0;
+}
+```
+
+上例中，`BM_group` 定义了一个测试组，`BM_add` 添加了两个需要进行比较的测试用例，`BM_use` 防止编译器将测试代码优化掉。
+
+基准测试结果以 markdown table 格式输出，如下所示：
+![bm.png](/images/bm.png)
+
+
 
 ### JSON
 
@@ -371,15 +406,15 @@ coost 实现了类似 golang 中 goroutine 的协程机制，它有如下特性
 - 支持多线程调度，默认线程数为系统 CPU 核数。
 - 共享栈，同一线程中的协程共用若干个栈(大小默认为 1MB)，内存占用低。
 - 各协程之间为平级关系，可以在任何地方(包括在协程中)创建新的协程。
-- 支持[协程同步事件](../../co/coroutine/#协程同步事件coevent)、[协程锁](../../co/coroutine/#协程锁comutex)、[channel](../../co/coroutine/#channelcochan)、[waitgroup](../../co/coroutine/#waitgroupcowaitgroup) 等协程同步机制。
+- 支持[协程同步事件](../../co/concurrency/coroutine/event/)、[协程锁](../../co/concurrency/coroutine/mutex/)、[channel](../../co/concurrency/coroutine/chan/)、[waitgroup](../../co/concurrency/coroutine/wg/) 等协程同步机制。
 
 ```cpp
 #include "co/co.h"
 
 int main(int argc, char** argv) {
-    flag::init(argc, argv);
+    flag::parse(argc, argv);
 
-    co::WaitGroup wg;
+    co::wait_group wg;
     wg.add(2);
 
     go([wg](){
@@ -397,16 +432,16 @@ int main(int argc, char** argv) {
 }
 ```
 
-上面的代码中，`go()` 创建的协程会均匀的分配到不同的调度线程中。用户也可以自行控制协程的调度：
+上面的代码中，`go()` 创建的协程会根据默认策略分配到不同的调度线程中。用户也可以自行控制协程的调度：
 
 ```cpp
 // run f1 and f2 in the same scheduler
-auto s = co::next_scheduler();
+auto s = co::next_sched();
 s->go(f1);
 s->go(f2);
 
 // run f in all schedulers
-for (auto& s : co::schedulers()) {
+for (auto& s : co::scheds()) {
     s->go(f);
 }
 ```
@@ -415,11 +450,10 @@ for (auto& s : co::schedulers()) {
 
 ### 网络编程
 
-coost 提供了一套基于协程的网络编程框架，大致可以分为三个部分：
+coost 提供了一套基于协程的网络编程框架：
 
-- **[协程化的 socket API](../../co/coroutine/#协程化的-socket-api)**，形式上与系统 socket API 类似，熟悉 socket 编程的用户，可以轻松的用同步的方式写出高性能的网络程序。
+- **[协程化的 socket API](../../co/net/sock/)**，形式上与系统 socket API 类似，熟悉 socket 编程的用户，可以轻松的用同步的方式写出高性能的网络程序。
 - [TCP](../../co/net/tcp/)、[HTTP](../../co/net/http/)、[RPC](../../co/net/rpc/) 等高层网络编程组件，兼容 IPv6，同时支持 SSL，用起来比 socket API 更方便。
-- **[系统 API hook](../../co/coroutine/#%E7%B3%BB%E7%BB%9F-api-hook)**，支持在协程中使用一般的三方网络库。
 
 
 **RPC server**
@@ -430,7 +464,7 @@ coost 提供了一套基于协程的网络编程框架，大致可以分为三
 #include "co/time.h"
 
 int main(int argc, char** argv) {
-    flag::init(argc, argv);
+    flag::parse(argc, argv);
 
     rpc::Server()
         .add_service(new xx::HelloWorldImpl)
@@ -457,7 +491,7 @@ curl http://127.0.0.1:7788/xx --request POST --data '{"api":"ping"}'
 DEF_string(d, ".", "root dir"); // docroot for the web server
 
 int main(int argc, char** argv) {
-    flag::init(argc, argv);
+    flag::parse(argc, argv);
     so::easy(FLG_d.c_str()); // mum never have to worry again
     return 0;
 }
 
@@ -1,4 +1,4 @@
 ---
 weight: 3
-title: "CO 参考文档"
+title: "参考文档"
 ---
@@ -0,0 +1,105 @@
+---
+weight: 7
+title: "基准测试"
+---
+
+include: [co/benchmark.h](https://github.com/idealvin/coost/blob/master/include/co/benchmark.h).
+
+
+## 基本概念
+
+**co.benchmark** 是 v3.0.1 新增的基准测试框架，可用于性能基准测试。
+
+
+### BM_group
+
+```cpp
+#define BM_group(_name_) \
+    ...... \
+    void _co_bm_group_##_name_(bm::xx::Group& _g_)
+```
+
+- `BM_group` 宏用于定义基准测试组，实际上定义了一个函数。
+- 每个 group 内可以用 [BM_add](#bm_add) 定义多条基准测试。
+
+{{< hint warning >}}
+参数 `_name_` 是组名，也是所定义函数名的一部分，如 `BM_group(atomic)` 是合理的，而 `BM_group(co.atomic)` 则是不允许的。
+{{< /hint >}}
+
+
+
+
+### BM_add
+
+```cpp
+#define BM_add(_name_) \
+    _g_.bm = #_name_; \
+    _BM_add
+```
+
+- `BM_add` 宏用于定义基准测试，它必须在 [BM_group](#bm_group) 定义的函数内使用。
+
+{{< hint warning >}}
+参数 `_name_` 是基准测试名，与 `BM_group` 不同，`BM_add(co.atomic)` 也是允许的。
+{{< /hint >}}
+
+
+
+### BM_use
+
+```cpp
+#define BM_use(v) bm::xx::use(&v, sizeof(v))
+```
+
+- `BM_use` 宏告诉编译器变量 `v` 会被使用，防止编译器将一些测试代码优化掉。
+
+
+
+
+## 编写基准测试代码
+
+
+### 测试代码示例
+
+```cpp
+#include "co/benchmark.h"
+#include "co/mem.h"
+
+BM_group(malloc) {
+    void* p;
+
+    BM_add(::malloc)(
+        p = ::malloc(32);
+    );
+    BM_use(p);
+
+    BM_add(co::alloc)(
+        p = co::alloc(32);
+    );
+    BM_use(p);
+}
+
+int main(int argc, char** argv) {
+    flag::parse(argc, argv);
+    bm::run_benchmarks();
+    return 0;
+}
+```
+
+- 上面的代码定义了一个名为 `malloc` 的基准测试组，组内用 `BM_add` 添加了 2 个基准测试。
+- 调用 `bm::run_benchmarks()`，会执行所有的基准测试代码。
+
+{{< hint warning >}}
+上例中，若无 `BM_use(p)`，编译器可能认为 `p` 是未使用的变量，将相关的测试代码优化掉，导致无法测出准确的结果。
+{{< /hint >}}
+
+
+
+
+### 测试结果示例
+
+![bm.png](/images/bm.png)
+
+- 基准测试结果输出为 markdown 表格，可以轻松将测试结果复制到 markdown 文档中。
+- 多个 `BM_group` 会生成多个 markdown 表格。
+- 表格第 1 列是 group 内的所有基准测试，第 2 列是单次迭代用时(单位为纳秒)，第 3 列是每秒迭代次数，第 4 列是性能提升倍数，以第一个基准测试为基准。