update docs and readme

wxing2008666 · Dec 11, 2019 · 246d2a0 · 246d2a0
1 parent d87dcc2
commit 246d2a0
Show file tree

Hide file tree

Showing 8 changed files with 38 additions and 14 deletions.
diff --git a/docs/cn/11.高效流式日志库(log).md b/docs/cn/11.高效流式日志库(log).md
@@ -184,7 +184,7 @@ LOG 库的测试代码见 [test/log_test.cc](https://github.com/idealvin/co/blob
 
 ```sh
 # 生成 log.exe
-cd co/test && ./_build.sh log_test.cc && cd ../build
+cd co/test && xmake -b log && cd ../build
 
 # 打印不同类型的日志
 ./log.exe

diff --git a/docs/cn/12.单元测试框架(unitest).md b/docs/cn/12.单元测试框架(unitest).md
@@ -50,7 +50,7 @@ DEF_test(os) {
 
 ```sh
 # 生成 unitest 可执行文件
-cd co/unitest/base && scons -j4 && cd ../../build
+cd co/unitest/base && xmake && cd ../../build
 
 # 运行所有测试用例
 ./unitest -a

diff --git a/docs/cn/16.高效json库(json).md b/docs/cn/16.高效json库(json).md
@@ -24,7 +24,7 @@ include: [base/json.h](https://github.com/idealvin/co/blob/master/base/json.h).
     - 支持 array、object 两种复合类型.
     - 所有类型统一用一个 `Json` 类表示.
     - Json 类内部仅一个指针数据成员，`sizeof(Json) == sizeof(void*)`.
-    - Json 内置引用计数，复制操作仅增加引用计数，不进行内存拷贝.
+    - Json 内置引用计数，复制操作仅增加引用计数(**非原子操作，非线程安全**)，不进行内存拷贝.
 
 ### 16.1 基本类型
 
@@ -181,11 +181,10 @@ if (v.is_int()) {
 
 json 字符串内部以 '\0' 结尾，应该避免在字符串中包含二进制字符。
 
-json 字符串支持包含 `"` 与 `\`，也支持转义字符 `\r, \n, \t`。但包含这些特殊字符，会降低 `json::parse()` 的性能，实际应用中应该尽量少用。
+json 字符串支持包含 `"` 与 `\`，也支持 `\r, \n, \t` 等转义字符。但包含这些特殊字符，会降低 `json::parse()` 的性能，实际应用中应该尽量少用。
 
 ```cpp
 Json x = "hello\r\n\t";      // ok, 字符串中包含转义字符
 Json x = "hello\"world";     // ok, 字符串中包含 "
 Json x = "hello\\world";     // ok, 字符串中包含 \
 ```
-
diff --git a/docs/cn/17.高性能json-rpc框架(rpc).md b/docs/cn/17.高性能json-rpc框架(rpc).md
@@ -44,7 +44,7 @@ class Server {
 };
 
 // 创建一个 rpc server，passwd 非空时，客户端连接后需要进行密码认证
-Server* new_server(const char* ip, int port, const char* passwd);
+Server* new_server(const char* ip, int port, const char* passwd="");
 } // rpc
 ```
 
@@ -165,6 +165,8 @@ class HelloWorld : public rpc::Service {
 
 可以看到 HelloWrold 的构造函数已经将 hello, world 方法注册到内部的 map 中，process() 方法根据 req 中的 `method` 字段，找到并调用对应的 rpc 方法。用户只需继承 `HelloWorld` 类，实现具体进行业务处理的 hello, world 方法即可。
 
+业务处理方法可能在不同的线程中调用，实现时需要注意线程安全性。业务处理方法内部需要连接到其他网络服务时，可以用协程安全的 `co::Pool` 管理这些网络连接。
+
 生成的头文件可以直接放到 server 代码所在目录，客户端不需要用到。客户端只需参考 proto 文件中的 req/res 定义，就知道怎么构造 req 发起 rpc 调用了。
 
 #### 17.2.3 具体的业务实现
@@ -220,7 +222,7 @@ class Client {
     virtual void call(const Json& req, Json& res) = 0;
 };
 
-Client* new_client(const char* ip, int port, const char* passwd);
+Client* new_client(const char* ip, int port, const char* passwd="");
 } // rpc
 ```
 
@@ -254,6 +256,28 @@ int main(int argc, char** argv) {
 }
 ```
 
+需要注意，一个 `rpc::Client` 对应一个连接，不要在多个线程中使用同一个 rpc::Client。多线程环境中，可以使用 `co::Pool` 管理客户端连接，下面是一个例子:
+
+```cpp
+co::Pool cli_pool;
+
+void client_fun() {
+    co::Kakalot<rpc::Client> c(cli_pool);
+    if (c == NULL) c = rpc::new_client("127.0.0.1", 7788, "passwd");
+
+    for (int i = 0; i < 10; ++i) {
+        Json req, res;
+        req.add_member("method", "hello");
+        c->call(req, res);  // 调用 hello 方法
+    }
+}
+
+// 创建 8 个协程
+for (int i = 0; i < 8; ++i) {
+    go(client_fun);
+}
+```
+
 ### 17.4 配置项
 
 rpc 库支持的配置项如下:

diff --git a/docs/cn/22.编译.md b/docs/cn/22.编译.md
@@ -15,8 +15,7 @@ [email protected]
 
 ## 22. 编译
 
-`CO` 使用 [xmake](https://github.com/xmake-io/xmake) 进行编译，后续可能不再支持 <s>[scons](https://scons.org/)</s>, <s>[vs project](https://visualstudio.microsoft.com/)</s>。
-
+`CO` 使用 [xmake](https://github.com/xmake-io/xmake) 进行编译，后续可能不再支持 ~~[scons](https://scons.org/)~~, ~~[vs project](https://visualstudio.microsoft.com/)~~。
 
 - 编译器
     - Linux: [gcc 4.8+](https://gcc.gnu.org/projects/cxx-status.html#cxx11)
@@ -84,7 +83,8 @@ cd ../build
 cd co/rpcgen
 xmake
 
-# 可以将 rpcgen 放到系统目录下
+# 建议将 rpcgen 放到系统目录下(/usr/local/bin/).
+# 有些 linux 系统自带了一个 rpcgen，为避免冲突，可能需要重命名 rpcgen.
 rpcgen hello_world.proto
 ```
 

diff --git a/docs/cn/8.高效字符串(fastring).md b/docs/cn/8.高效字符串(fastring).md
@@ -21,7 +21,7 @@ include: [base/fastring.h](https://github.com/idealvin/co/blob/master/base/fastr
 
 - fastring 的特性：
     - 类中仅有一个指针成员，`sizeof(fastring) == sizeof(void*)`.
-    - 内置引用计数，复制操作仅增加引用计数，不会进行内存拷贝.
+    - 内置引用计数，复制操作仅增加引用计数(原子操作，线程安全)，不会进行内存拷贝.
     - 空字符串不分配内存，内部指针为 0，不存在引用计数，复制空字符串不会增加引用计数.
 
 - 代码示例

diff --git a/docs/en/8.efficient strings (fastring).md b/docs/en/8.efficient strings (fastring).md
@@ -21,7 +21,7 @@ include: [base/fastring.h](https://github.com/idealvin/co/blob/master/base/fastr
 
 - Features:
     - There is only one pointer member, `sizeof(fastring) == sizeof(void*)`.
-    - It uses reference counter, so copying only increases the counter without copying.
+    - It uses reference counter, so copying only increases the counter without memory copying(atomic and thread-safe).
     - No memory is allocated for empty strings, and the internal pointer is `0`. No reference counter is provided, so copying empty strings will not increment it.
 
 - Examples

diff --git a/readme.md b/readme.md
@@ -93,7 +93,7 @@ go(f);
 
 ## 编译执行
 
-`CO` 已将构建工具切换为 [ruki](https://github.com/waruqi) 的 [xmake](https://github.com/xmake-io/xmake)，后续可能放弃 <s>[scons](https://scons.org/)</s>, <s>[vs project](https://visualstudio.microsoft.com/)</s>。
+`CO` 已将构建工具切换为 [ruki](https://github.com/waruqi) 的 [xmake](https://github.com/xmake-io/xmake)，后续可能放弃 ~~[scons](https://scons.org/)~~, ~~[vs project](https://visualstudio.microsoft.com/)~~。
 
 - 安装 xmake
 
@@ -156,7 +156,8 @@ cd ../build
 cd co/rpcgen
 xmake
 
-# 可以将 rpcgen 放到系统目录下
+# 建议将 rpcgen 放到系统目录下(/usr/local/bin/).
+# 有些 linux 系统自带了一个 rpcgen，为避免冲突，可能需要重命名 rpcgen.
 rpcgen hello_world.proto
 ```