Fixes on docs and comments

yanghxstone · Sep 14, 2017 · c3ae57a · c3ae57a
1 parent ee9e268
commit c3ae57a
Show file tree

Hide file tree

Showing 39 changed files with 62 additions and 74 deletions.
diff --git a/docs/cn/benchmark.md b/docs/cn/benchmark.md
@@ -23,28 +23,28 @@ com组（INF前身）在08年开发的RPC框架，在百度产品线广泛使用
 - nova_pbrpc：网盟在12年基于UB开发的RPC框架，用protobuf代替mcpack作为序列化方法，协议是nshead + user's protobuf。
 - public_pbrpc：INF在13年初基于UB开发的RPC框架，用protobuf代替mcpack作为序列化方法，但协议与nova_pbrpc不同，大致是nshead + meta protobuf。meta protobuf中有个string字段包含user's protobuf。由于用户数据要序列化两次，这个RPC的性能很差，没有被推广开来。
 
-我们以在网盟广泛使用的nova_pbrpc为UB的代表。测试时其代码为[r10500](https://svn.baidu.com/app/ecom/cm/trunk/pb-rpc)。早期的UB支持CPOOL和XPOOL，分别使用[select](http://linux.die.net/man/2/select)和[leader-follower模型](http://kircher-schwanninger.de/michael/publications/lf.pdf)，后来提供了EPOOL，使用[epoll](http://man7.org/linux/man-pages/man7/epoll.7.html)处理多路连接。鉴于产品线大都是用EPOOL模型，我们的UB配置也使用EPOOL。UB只支持[连接池](client.md#连接方式)，结果用“**ubrpc_mc**"指代（mc代表"multiple
+我们以在网盟广泛使用的nova_pbrpc为UB的代表。测试时其代码为r10500。早期的UB支持CPOOL和XPOOL，分别使用[select](http://linux.die.net/man/2/select)和[leader-follower模型](http://kircher-schwanninger.de/michael/publications/lf.pdf)，后来提供了EPOOL，使用[epoll](http://man7.org/linux/man-pages/man7/epoll.7.html)处理多路连接。鉴于产品线大都是用EPOOL模型，我们的UB配置也使用EPOOL。UB只支持[连接池](client.md#连接方式)，结果用“**ubrpc_mc**"指代（mc代表"multiple
 connection"）。虽然这个名称不太准确（见上文对ubrpc的介绍），但在本文的语境下，请默认ubrpc = UB。
 
 ## hulu-pbrpc
 
-INF在13年基于saber(kylin变种)和protobuf实现的RPC框架，hulu在实现上有较多问题：未封装的引用计数，混乱的生命周期，充斥的race conditions和ABA problems，运行质量不可靠，比如短链接从来没有能正常运行过。之后迅速被brpc代替，测试时其代码为：<https://svn.baidu.com/public/tags/hulu/pbrpc/pbrpc_2-0-15-27959_PD_BL>。hulu-pbrpc只支持单连接，结果用“**hulu-pbrpc**"指代。
+INF在13年基于saber(kylin变种)和protobuf实现的RPC框架，hulu在实现上有较多问题：未封装的引用计数，混乱的生命周期，充斥的race conditions和ABA problems，运行质量不可靠，比如短链接从来没有能正常运行过。之后迅速被brpc代替，测试时其代码为`pbrpc_2-0-15-27959_PD_BL`。hulu-pbrpc只支持单连接，结果用“**hulu-pbrpc**"指代。
 
 ## brpc
 
-INF在2014年底开发至今的rpc产品，支持百度内所有协议（不限于protobuf），并第一次统一了百度内主要分布式系统的RPC框架。测试时其代码为[r31906](https://svn.baidu.com/public/tags/baidu-rpc/baidu-rpc_1-0-199-31906_PD_BL)（开发请使用@ci-base保持更新）。brpc既支持单连接也支持连接池，前者的结果用"**baidu-rpc**"指代，后者用“**baidu-rpc_mc**"指代。
+INF在2014年底开发至今的rpc产品，支持百度内所有协议（不限于protobuf），并第一次统一了百度内主要分布式系统的RPC框架。测试时代码为r31906（开发请使用@ci-base保持更新）。brpc既支持单连接也支持连接池，前者的结果用"**baidu-rpc**"指代，后者用“**baidu-rpc_mc**"指代。
 
 ## sofa-pbrpc
 
-大搜在13年基于boost::asio和protobuf实现的RPC框架，有多个版本，咨询相关同学后，确认ps/opensource下的和github上的较新，且会定期同步。故测试使用使用ps/opensource下的版本。测试时其代码为：<https://svn.baidu.com/ps/opensource/branches/sofa-pbrpc/sofa-pbrpc_1-0-2_BRANCH/>。sofa-pbrpc只支持单连接，结果用“**sofa-pbrpc**”指代。
+大搜在13年基于boost::asio和protobuf实现的RPC框架，有多个版本，咨询相关同学后，确认ps/opensource下的和github上的较新，且会定期同步。故测试使用使用ps/opensource下的版本。测试时其代码为`sofa-pbrpc_1-0-2_BRANCH`。sofa-pbrpc只支持单连接，结果用“**sofa-pbrpc**”指代。
 
 ## apache thrift
 
-thrift是由facebook最早在07年开发的序列化方法和rpc框架，包含独特的序列化格式和IDL，支持很多编程语言。开源后改名[apache thrift](https://thrift.apache.org/)，fb自己有一个[fbthrift分支](https://github.com/facebook/fbthrift)，我们使用的是apache thrift。测试时其代码为[0.9](https://svn.baidu.com/third-64/tags/thrift/thrift_0-9-1-400_PD_BL)。thrift的缺点是：代码看似分层清晰，client和server选择很多，但没有一个足够通用，每个server实现都只能解决很小一块场景，每个client都线程不安全，实际使用很麻烦。由于thrift没有线程安全的client，所以每个线程中都得建立一个client，使用独立的连接。在测试中thrift其实是占了其他实现的便宜：它的client不需要处理多线程问题。thrift的结果用"**thrift_mc**"指代。
+thrift是由facebook最早在07年开发的序列化方法和rpc框架，包含独特的序列化格式和IDL，支持很多编程语言。开源后改名[apache thrift](https://thrift.apache.org/)，fb自己有一个[fbthrift分支](https://github.com/facebook/fbthrift)，我们使用的是apache thrift。测试时其代码为`thrift_0-9-1-400_PD_BL`。thrift的缺点是：代码看似分层清晰，client和server选择很多，但没有一个足够通用，每个server实现都只能解决很小一块场景，每个client都线程不安全，实际使用很麻烦。由于thrift没有线程安全的client，所以每个线程中都得建立一个client，使用独立的连接。在测试中thrift其实是占了其他实现的便宜：它的client不需要处理多线程问题。thrift的结果用"**thrift_mc**"指代。
 
 ## grpc
 
-由google开发的rpc框架，使用http/2和protobuf 3.0，测试时其代码为：<https://github.com/grpc/grpc/tree/release-0_11>。grpc并不是stubby，定位更像是为了推广http/2和protobuf 3.0，但鉴于很多人对它的表现很感兴趣，我们也（很麻烦地）把它加了进来。grpc的结果用"**grpc**"指代。
+由google开发的rpc框架，使用http/2和protobuf 3.0，测试时其代码为<https://github.com/grpc/grpc/tree/release-0_11>。grpc并不是stubby，定位更像是为了推广http/2和protobuf 3.0，但鉴于很多人对它的表现很感兴趣，我们也（很麻烦地）把它加了进来。grpc的结果用"**grpc**"指代。
 
 # 测试方法
 

diff --git a/docs/cn/client.md b/docs/cn/client.md
@@ -510,7 +510,7 @@ Channel的默认协议是标准协议，可通过设置ChannelOptions.protocol
 - PROTOCOL_NOVA_PBRPC 或 ”nova_pbrpc“，网盟的协议，默认为连接池。
 - PROTOCOL_HTTP 或 ”http", http协议，默认为连接池(Keep-Alive)。具体方法见[访问HTTP服务](http_client.md)。
 - PROTOCOL_SOFA_PBRPC 或 "sofa_pbrpc"，sofa-pbrpc的协议，默认为单连接。
-- PROTOCOL_PUBLIC_PBRPC 或 "public_pbrpc"，public/pbrpc的协议，默认为连接池。
+- PROTOCOL_PUBLIC_PBRPC 或 "public_pbrpc"，public_pbrpc的协议，默认为连接池。
 - PROTOCOL_UBRPC_COMPACK 或 "ubrpc_compack"，public/ubrpc的协议，使用compack打包，默认为连接池。具体方法见[ubrpc (by protobuf)](ub_client.md)。相关的还有PROTOCOL_UBRPC_MCPACK2或ubrpc_mcpack2，使用mcpack2打包。
 - PROTOCOL_NSHEAD_CLIENT 或 "nshead_client"，这是发送brpc-ub中所有UBXXXRequest需要的协议，默认为连接池。具体方法见[访问ub](ub_client.md)。
 - PROTOCOL_NSHEAD 或 "nshead"，这是brpc中发送NsheadMessage需要的协议，默认为连接池。注意发送NsheadMessage的效果等同于发送brpc-ub中的UBRawBufferRequest，但更加方便一点。具体方法见[nshead+blob](ub_client.md#nshead-blob) 。
@@ -714,13 +714,13 @@ struct ChannelOptions {
 
 ### Q: Invalid address=`bns://group.user-persona.dumi.nj03'是什么意思
 ```
-FATAL 04-07 20:00:03 7778 public/brpc/src/brpc/channel.cpp:123] Invalid address=`bns://group.user-persona.dumi.nj03'. You should use Init(naming_service_name, load_balancer_name, options) to access multiple servers.
+FATAL 04-07 20:00:03 7778 src/brpc/channel.cpp:123] Invalid address=`bns://group.user-persona.dumi.nj03'. You should use Init(naming_service_name, load_balancer_name, options) to access multiple servers.
 ```
 访问bns要使用三个参数的Init，它第二个参数是load_balancer_name，而你这里用的是两个参数的Init，框架当你是访问单点，就会报这个错。
 
 ### Q: 两个产品线都使用protobuf，为什么不能互相访问
 
-协议 !=protobuf。protobuf负责打包，协议负责定字段。打包格式相同不意味着字段可以互通。协议中可能会包含多个protobuf包，以及额外的长度、校验码、magic number等等。协议的互通是通过在RPC框架内转化为统一的编程接口完成的，而不是在protobuf层面。从广义上来说，protobuf也可以作为打包框架使用，生成其他序列化格式的包，像[idl<=>protobuf](idl_protobuf.md)就是通过protobuf生成了解析idl的代码。
+协议 !=protobuf。protobuf负责打包，协议负责定字段。打包格式相同不意味着字段可以互通。协议中可能会包含多个protobuf包，以及额外的长度、校验码、magic number等等。协议的互通是通过在RPC框架内转化为统一的编程接口完成的，而不是在protobuf层面。从广义上来说，protobuf也可以作为打包框架使用，生成其他序列化格式的包，像[idl<=>protobuf](mcpack2pb.md)就是通过protobuf生成了解析idl的代码。
 
 ### Q: 为什么C++ client/server 能够互相通信， 和其他语言的client/server 通信会报序列化失败的错误
 
@@ -734,7 +734,7 @@ FATAL 04-07 20:00:03 7778 public/brpc/src/brpc/channel.cpp:123] Invalid address=
 
 1. 创建一个[bthread_id](https://github.com/brpc/brpc/blob/master/src/bthread/id.h)作为本次RPC的correlation_id。
 2. 根据Channel的创建方式，从进程级的[SocketMap](https://github.com/brpc/brpc/blob/master/src/brpc/socket_map.h)中或从[LoadBalancer](https://github.com/brpc/brpc/blob/master/src/brpc/load_balancer.h)中选择一台下游server作为本次RPC发送的目的地。
-3. 根据连接方式（单连接、连接池、短连接），选择一个[Socket](https://svn.baidu.com/public/trunk/baidu-rpc/src/baidu/rpc/socket.h)。
+3. 根据连接方式（单连接、连接池、短连接），选择一个[Socket](https://github.com/brpc/brpc/blob/master/src/brpc/socket.h)。
 4. 如果开启验证且当前Socket没有被验证过时，第一个请求进入验证分支，其余请求会阻塞直到第一个包含认证信息的请求写入Socket。这是因为server端只对第一个请求进行验证。
 5. 根据Channel的协议，选择对应的序列化函数把request序列化至[IOBuf](https://github.com/brpc/brpc/blob/master/src/butil/iobuf.h)。
 6. 如果配置了超时，设置定时器。从这个点开始要避免使用Controller对象，因为在设定定时器后->有可能触发超时机制->调用到用户的异步回调->用户在回调中析构Controller。

diff --git a/docs/cn/heap_profiler.md b/docs/cn/heap_profiler.md
@@ -47,14 +47,14 @@ WARNING: 12-26 10:01:25:   * 0 [src/brpc/input_messenger.cpp:132][4294969345] Au
 
 左上角的两个选择框作用分别是：
 
-- View：当前正在看的profile。选择<new profile>表示新建一个。新建完毕后，View选择框中会出现新profile，URL也会被修改为对应的地址。这意味着你可以通过粘贴URL分享结果，点击链接的人将看到和你一模一样的结果，而不是重做profiling的结果。你可以在框中选择之前的profile查看。历史profiie保留最近的32个，可通过[--max_profiles_kept](http://brpc.baidu.com:8765/flags/max_profiles_kept)调整。
+- View：当前正在看的profile。选择\<new profile\>表示新建一个。新建完毕后，View选择框中会出现新profile，URL也会被修改为对应的地址。这意味着你可以通过粘贴URL分享结果，点击链接的人将看到和你一模一样的结果，而不是重做profiling的结果。你可以在框中选择之前的profile查看。历史profiie保留最近的32个，可通过[--max_profiles_kept](http://brpc.baidu.com:8765/flags/max_profiles_kept)调整。
 - Diff：和选择的profile做对比。<none>表示什么都不选。如果你选择了之前的某个profile，那么将看到View框中的profile相比Diff框中profile的变化量。
 
 下图演示了勾选Diff和Text的效果。
 
 ![img](../images/heap_profiler_3.gif)
 
-你也可以使用pprof脚本（public/brpc/tools/pprof）在命令行中查看文本格式结果：
+你也可以使用pprof脚本（tools/pprof）在命令行中查看文本格式结果：
 
 ```
 $ tools/pprof --text db-rpc-dev00.db01:8765/pprof/heap    

diff --git a/docs/cn/nshead_service.md b/docs/cn/nshead_service.md
@@ -1,6 +1,6 @@
 ub是百度内广泛使用的老RPC框架，在迁移ub服务时不可避免地需要[访问ub-server](ub_client.md)或被ub-client访问。ub使用的协议种类很多，但都以nshead作为二进制包的头部，这类服务在brpc中统称为**“nshead service”**。
 
-nshead后大都使用mcpack/compack作为序列化格式，注意这不是“协议”。"协议"除了序列化格式，还涉及到各种特殊字段的定义，一种序列化格式可能会衍生出很多协议。ub没有定义标准协议，所以即使都使用mcpack/compack，产品线的通信协议也是五花八门，无法互通。鉴于此，我们提供了一套接口，让用户能够灵活的处理自己产品线的协议，同时享受brpc提供的builtin services等一系列框架福利。
+nshead后大都使用mcpack/compack作为序列化格式，注意这不是“协议”。"协议"除了序列化格式，还涉及到各种特殊字段的定义，一种序列化格式可能会衍生出很多协议。ub没有定义标准协议，所以即使都使用mcpack或compack，产品线的通信协议也是五花八门，无法互通。鉴于此，我们提供了一套接口，让用户能够灵活的处理自己产品线的协议，同时享受brpc提供的builtin services等一系列框架福利。
 
 # 使用ubrpc的服务
 
@@ -13,7 +13,7 @@ ubrpc协议的基本形式是nshead+compack或mcpack2，但compack或mcpack2中
 使用脚本[idl2proto](https://github.com/brpc/brpc/blob/master/tools/idl2proto)把idl文件自动转化为proto文件，下面是转化后的proto文件。
 
 ```protobuf
-// Converted from echo.idl by public/mcpack2pb/idl2proto
+// Converted from echo.idl by brpc/tools/idl2proto
 import "idl_options.proto";
 option (idl_support) = true;
 option cc_generic_services = true;
@@ -60,15 +60,12 @@ service EchoService {
 };
 ```
 
-## 设置protoc和mcpack2pb的参数
+## 以插件方式运行protoc
 
-注意--mcpack_out要和--cpp_out一致，你可以先设成--mcpack_out=.，执行comake2或bcloud后看错误信息中的--cpp_out的值，再把--mcpack_out设成一样的。
+BRPC_PATH代表brpc产出的路径（包含bin include等目录），PROTOBUF_INCLUDE_PATH代表protobuf的包含路径。注意--mcpack_out要和--cpp_out一致。
 
-```pyton
-PROTOC(ENV.WorkRoot()+"/third-64/protobuf/bin/protoc")
-PROTOFLAGS("--plugin=protoc-gen-mcpack=" + ENV.WorkRoot() + "/public/mcpack2pb/protoc-gen-mcpack --mcpack_out=.")
-PROTOFLAGS('--proto_path=' + ENV.WorkRoot() + '/public/mcpack2pb/')
-PROTOFLAGS('--proto_path=' + ENV.WorkRoot() + '/third-64/protobuf/include/')
+```shell
+protoc --plugin=protoc-gen-mcpack=$BRPC_PATH/bin/protoc-gen-mcpack --cpp_out=. --mcpack_out=. --proto_path=$BRPC_PATH/include --proto_path=PROTOBUF_INCLUDE_PATH
 ```
 
 ## 实现生成的Service基类
@@ -172,7 +169,7 @@ idl是mcpack/compack的前端，用户只要在idl文件中描述schema，就可
 
 > **这个服务在继续使用mcpack/compack作为序列化格式，相比protobuf占用成倍的带宽和打包时间。**
 
-为了解决这个问题，我们提供了[mcpack2pb](idl_protobuf.md)，允许把protobuf作为mcpack/compack的前端。你只要写一份proto文件，就可以同时解析mcpack/compack和protobuf格式的请求。使用这个方法，使用idl描述的服务的可以平滑地改造为使用proto文件描述，而不用修改上游client（仍然使用mcpack/compack）。你产品线的服务可以逐个地从mcpack/compack/idl切换为protobuf，从而享受到性能提升，带宽节省，全新开发体验等好处。你可以自行在NsheadService使用public/mcpack2pb，也可以联系我们，提供更高质量的协议支持。
+为了解决这个问题，我们提供了[mcpack2pb](mcpack2pb.md)，允许把protobuf作为mcpack/compack的前端。你只要写一份proto文件，就可以同时解析mcpack/compack和protobuf格式的请求。使用这个方法，使用idl描述的服务的可以平滑地改造为使用proto文件描述，而不用修改上游client（仍然使用mcpack/compack）。你产品线的服务可以逐个地从mcpack/compack/idl切换为protobuf，从而享受到性能提升，带宽节省，全新开发体验等好处。你可以自行在NsheadService使用src/mcpack2pb，也可以联系我们，提供更高质量的协议支持。
 
 # 使用nshead+protobuf的服务
 
@@ -231,4 +228,3 @@ public:
                                           NsheadMessage* nshead_res) const = 0;
 };
 ```
-
diff --git a/docs/cn/rpc_press.md b/docs/cn/rpc_press.md
@@ -3,7 +3,7 @@ rpc_press无需写代码就压测各种rpc server，目前支持的协议有：
 - 标准协议
 - hulu-pbrpc协议
 - sofa-pbrpc协议
-- public/pbrpc协议（老版pbrpc协议）
+- public_pbrpc协议（老版pbrpc协议）
 - nova-pbrpc协议     
 
 # 获取工具

diff --git a/docs/cn/rpc_replay.md b/docs/cn/rpc_replay.md
@@ -51,7 +51,7 @@ brpc提供了[SampleIterator](https://github.com/brpc/brpc/blob/master/src/brpc/
 brpc::SampleIterator it("./rpc_data/rpc_dump/echo_server");         
 for (SampleRequest* req = it->Next(); req != NULL; req = it->Next()) {
     ...                    
-    // req->meta的类型是brpc::RpcDumpMeta，定义在protocol/brpc/rpc_dump.proto
+    // req->meta的类型是brpc::RpcDumpMeta，定义在src/brpc/rpc_dump.proto
     // req->request的类型是butil::IOBuf，对应格式说明中的"serialized request"
     // 使用结束后必须delete req。
 }

diff --git a/docs/cn/server.md b/docs/cn/server.md
@@ -272,7 +272,7 @@ $ curl -d '{"message":"hello"}' http://brpc.baidu.com:8765/EchoService/Echo
 
 ## json<=>pb
 
-json通过名字与pb字段一一对应，结构层次也应匹配。json中一定要包含pb的required字段，否则转化会失败，对应请求会被拒绝。json中可以包含pb中没有定义的字段，但不会作为pb的unknown字段被继续传递。转化规则详见[json <=> protobuf](idl_protobuf.md)。
+json通过名字与pb字段一一对应，结构层次也应匹配。json中一定要包含pb的required字段，否则转化会失败，对应请求会被拒绝。json中可以包含pb中没有定义的字段，但不会作为pb的unknown字段被继续传递。转化规则详见[json <=> protobuf](json2pb.md)。
 
 r34532后增加选项-pb_enum_as_number，开启后pb中的enum会转化为它的数值而不是名字，比如在`enum MyEnum { Foo = 1; Bar = 2; };`中不开启此选项时MyEnum类型的字段会转化为"Foo"或"Bar"，开启后为1或2。此选项同时影响client发出的请求和server返回的回复。由于转化为名字相比数值有更好的前后兼容性，此选项只应用于兼容无法处理enum为名字的场景。
 
@@ -314,7 +314,7 @@ server端会自动尝试其支持的协议，无需用户指定。`cntl->protoco
   options.nshead_service = new brpc::policy::NovaServiceAdaptor;
   ```
 
-- public/pbrpc协议，显示为"public_pbrpc" (r32206前显示为"nshead_server")，默认不启用，开启方式：
+- public_pbrpc协议，显示为"public_pbrpc" (r32206前显示为"nshead_server")，默认不启用，开启方式：
 
   ```c++
   #include <brpc/policy/public_pbrpc_protocol.h>