add docs for test

LICENSE

+
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/
@@ -174,28 +175,3 @@
       of your accepting any such warranty or additional liability.
 
    END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "{}"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright {yyyy} {name of copyright owner}
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

docs/cn/avalanche_effect.md

+“雪崩”指的是访问服务集群时绝大部分请求都超时，且在流量减少时仍无法恢复的现象。下面解释这个现象的来源。
+
+当流量超出服务的最大qps时，服务将无法正常服务；当流量恢复正常时（小于服务的处理能力），积压的请求会被处理，虽然其中很大一部分可能会因为处理的不及时而超时，但服务本身一般还是会恢复正常的。这就相当于一个水池有一个入水口和一个出水口，如果入水量大于出水量，水池子终将盛满，多出的水会溢出来。但如果入水量降到出水量之下，一段时间后水池总会排空。雪崩并不是单一服务能产生的。
+
+如果一个请求经过两个服务，情况就有所不同了。比如请求访问A服务，A服务又访问了B服务。当B被打满时，A处的client会大量超时，如果A处的client在等待B返回时也阻塞了A的服务线程（常见），且使用了固定个数的线程池（常见），那么A处的最大qps就从**线程数 / 平均延时**，降到了**线程数 / 超时**。由于超时往往是平均延时的3~4倍，A处的最大qps会相应地下降3~4倍，从而产生比B处更激烈的拥塞。如果A还有类似的上游，拥塞会继续传递上去。但这个过程还是可恢复的。B处的流量终究由最前端的流量触发，只要最前端的流量回归正常，B处的流量总会慢慢降下来直到能正常回复大多数请求，从而让A恢复正常。
+
+但有两个例外：
+
+1. A可能对B发起了过于频繁的基于超时的重试。这不仅会让A的最大qps降到**线程数 / 超时**，还会让B处的qps翻**重试次数**倍。这就可能陷入恶性循环了：只要**线程数 / 超时 \* 重试次数**大于B的最大qps**，**B就无法恢复 -> A处的client会继续超时 -> A继续重试 -> B继续无法恢复。
+2. A或B没有限制某个缓冲或队列的长度，或限制过于宽松。拥塞请求会大量地积压在那里，要恢复就得全部处理完，时间可能长得无法接受。由于有限长的缓冲或队列需要在填满时解决等待、唤醒等问题，有时为了简单，代码可能会假定缓冲或队列不会满，这就埋下了种子。即使队列是有限长的，恢复时间也可能很长，因为清空队列的过程是个追赶问题，排空的时间取决于**积压的请求数 / (最大qps - 当前qps)**，如果当前qps和最大qps差的不多，积压的请求又比较多，那排空时间就遥遥无期了。
+
+了解这些因素后可以更好的理解brpc中相关的设计。
+
+1. 拥塞时A服务最大qps的跳变是因为线程个数是**硬限**，单个请求的处理时间很大程度上决定了最大qps。而brpc server端默认在bthread中处理请求，个数是软限，单个请求超时只是阻塞所在的bthread，并不会影响为新请求建立新的bthread。brpc也提供了完整的异步接口，让用户可以进一步提高io-bound服务的并发度，降低服务被打满的可能性。
+2. brpc中[重试](client.md#重试)默认只在连接出错时发起，避免了流量放大，这是比较有效率的重试方式。如果需要基于超时重试，可以设置[backup request](client.md#backuprequest)，这类重试最多只有一次，放大程度降到了最低。brpc中的RPC超时是deadline，超过后RPC一定会结束，这让用户对服务的行为有更好的预判。在之前的一些实现中，RPC超时是单次超时*重试次数，在实践中容易误判。
+3. brpc server端的[max_concurrency选项](server.md#id-创建和设置Server-限制最大并发)控制了server的最大并发：当同时处理的请求数超过max_concurrency时，server会回复client错误，而不是继续积压。这一方面在服务开始的源头控制住了积压的请求数，尽量避免延生到用户缓冲或队列中，另一方面也让client尽快地去重试其他server，对集群来说是个更好的策略。
+
+对于brpc的用户来说，要防止雪崩，主要注意两点：
+
+1. 评估server的最大并发，设置合理的max_concurrency值。这个默认是不设的，也就是不限制。无论程序是同步还是异步，用户都可以通过 **最大qps \* 非拥塞时的延时**（秒）来评估最大并发，原理见[little's law](https://en.wikipedia.org/wiki/Little)，这两个量都可以在brpc中的内置服务中看到。max_concurrency与最大并发相等或大一些就行了。
+2. 注意考察重试发生时的行为，特别是在定制RetryPolicy时。如果你只是用默认的brpc重试，一般是安全的。但用户程序也常会自己做重试，比如通过一个Channel访问失败后，去访问另外一个Channel，这种情况下要想清楚重试发生时最差情况下请求量会放大几倍，服务是否可承受。

docs/cn/backup_request.md

+有时为了保证可用性，需要同时访问两路服务，哪个先返回就取哪个。在brpc中，这有多种做法：
+
+# 当后端server可以挂在一个名字服务内时
+
+Channel开启backup request。这个Channel会先向其中一个server发送请求，如果在ChannelOptions.backup_request_ms后还没回来，再向另一个server发送。之后哪个先回来就取哪个。在设置了合理的backup_request_ms后，大部分时候只会发一个请求，对后端服务只有一倍压力。
+
+示例代码见[example/backup_request_c++](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/example/backup_request_c++)。这个例子中，client设定了在2ms后发送backup request，server在碰到偶数位的请求后会故意睡眠20ms以触发backup request。
+
+运行后，client端和server端的日志分别如下，“index”是请求的编号。可以看到server端在收到第一个请求后会故意sleep 20ms，client端之后发送另一个同样index的请求，最终的延时并没有受到故意sleep的影响。
+
+![img](../images/backup_request_1.png)
+
+![img](../images/backup_request_2.png)
+
+/rpcz也显示client在2ms后触发了backup超时并发出了第二个请求。
+
+![img](../images/backup_request_3.png)
+
+## 选择合理的backup_request_ms
+
+可以观察brpc默认提供的latency_cdf图，或自行添加。cdf图的y轴是延时（默认微秒），x轴是小于y轴延时的请求的比例。在下图中，选择backup_request_ms=2ms可以大约覆盖95.5%的请求，选择backup_request_ms=10ms则可以覆盖99.99%的请求。
+
+![img](../images/backup_request_4.png)
+
+自行添加的方法：
+
+```c++
+#include <bvar/bvar.h>
+#include <butil/time.h>
+...
+bvar::LatencyRecorder my_func_latency("my_func");
+...
+butil::Timer tm;
+tm.start();
+my_func();
+tm.stop();
+my_func_latency << tm.u_elapsed();  // u代表微秒，还有s_elapsed(), m_elapsed(), n_elapsed()分别对应秒，毫秒，纳秒。
+ 
+// 好了，在/vars中会显示my_func_qps, my_func_latency, my_func_latency_cdf等很多计数器。
+```
+
+# 当后端server不能挂在一个名字服务内时
+
+【推荐】建立一个开启backup request的SelectiveChannel，其中包含两个sub channel。访问这个SelectiveChannel和上面的情况类似，会先访问一个sub channel，如果在ChannelOptions.backup_request_ms后没返回，再访问另一个sub channel。如果一个sub channel对应一个集群，这个方法就是在两个集群间做互备。SelectiveChannel的例子见[example/selective_echo_c++](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/tree/example/selective_echo_c++)，具体做法请参考上面的过程。
+
+【不推荐】发起两个异步RPC后Join它们，它们的done内是相互取消的逻辑。示例代码见[example/cancel_c++](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/tree/example/cancel_c++)。这种方法的问题是总会发两个请求，对后端服务有两倍压力，这个方法怎么算都是不经济的，你应该尽量避免用这个方法。

docs/cn/benchmark_http.md

+可代替[ab](https://httpd.apache.org/docs/2.2/programs/ab.html)测试http server极限性能。ab功能较多但年代久远，有时本身可能会成为瓶颈。benchmark_http基本上就是一个brpc http client，性能很高，功能较少，一般压测够用了。
+
+使用方法：
+
+首先你得[下载和编译](getting_started.md)了brpc源码，然后去example/http_c++目录编译，成功后应该能看到benchmark_http。

docs/cn/bthread.md

+bthread([代码](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/tree/src/bthread))是brpc使用的M:N线程库，目的是在提高程序的并发度的同时，降低编码难度，并在核数日益增多的CPU上提供更好的scalability和cache locality。”M:N“是指M个bthread会映射至N个pthread，一般M远大于N。由于linux当下的pthread实现([NPTL](http://en.wikipedia.org/wiki/Native_POSIX_Thread_Library))是1:1的，M个bthread也相当于映射至N个[LWP](http://en.wikipedia.org/wiki/Light-weight_process)。bthread的前身是[DP](http://wiki.babel.baidu.com/twiki/bin/view/Com/Ecom/DistributedProcess)中的fiber，一个N:1的合作式线程库，等价于event-loop库，但写的是同步代码。
+
+# Goals
+
+- 用户可以延续同步的编程模式，能很快地建立bthread，可以用多种原语同步。
+- bthread所有接口可以在pthread中被调用并有合理的行为，使用bthread的代码可以在pthread中正常执行。
+- 能充分利用多核。
+- 更好的cache locality，更低的延时。
+
+# NonGoals
+
+- 提供pthread的兼容接口，只需链接即可使用。拒绝理由：bthread没有优先级，不适用于所有的场景，链接的方式容易使用户在不知情的情况下误用bthread，造成bug。
+- 修改内核让pthread支持同核快速切换。拒绝理由：拥有大量pthread后，每个线程对资源的需求被稀释了，基于thread-local cache的代码效果都会很差，比如tcmalloc。而独立的bthread不会有这个问题，因为它最终还是被映射到了少量的pthread。
+
+# FAQ
+
+##### Q：bthread是协程(coroutine)吗？
+
+不是。我们常说的协程是N:1线程库，即所有的协程都运行于一个系统线程中，计算能力和各种eventloop等价。由于不跨线程，协程之间的切换不需要系统调用，可以非常快(100ns-200ns)，受cache同步的影响也小。但相应的代价是协程无法高效地利用多核，代码必须非阻塞，否则所有的协程都被卡住，对开发者要求苛刻。协程的这个特点使其适合写运行时间确定的IO服务器，典型如http server，在一些精心调试的场景中，可以达到非常高的吞吐。但百度内大部分在线服务的运行时间并不确定，一个缓慢的函数很容易卡住所有的协程。在这点上eventloop是类似的，一个回调卡住整个loop就卡住了，比如ub**a**server（注意那个a，不是ubserver）是公司内对异步框架的尝试，由多个并行的eventloop组成，真实表现糟糕：回调里打日志慢一些，访问下redis，计算重一点，等待中的其他请求就会大量超时。所以这个框架从未流行起来。
+
+bthread是一个M:N线程库，一个bthread被卡住不会影响其他bthread。关键技术两点：work stealing调度和butex，前者让bthread更快地被调度到更多的核心上，后者让bthread和pthread可以相互等待和唤醒。这两点协程都不需要。更多线程的知识查看[这里](threading_overview.md)。
+
+##### Q: 我应该在程序中多使用bthread吗？
+
+不应该。除非你需要在一次RPC过程中[让一些代码并发运行](bthread_or_not.md)，你不应该直接调用bthread函数，把这些留给brpc做更好。
+
+##### Q：bthread和pthread worker如何对应？
+
+pthread worker在任何时间只会运行一个bthread，当前bthread挂起时，pthread worker先尝试从本地(runqueue)弹出一个待运行的bthread，若没有，则随机偷另一个worker的待运行bthread，仍然没有才睡眠并会在有新的待运行bthread时被唤醒。
+
+##### Q：bthread中能调用阻塞的pthread或系统函数吗？
+
+可以，只阻塞当前pthread worker。其他pthread worker不受影响。
+
+##### Q：一个bthread阻塞会影响其他bthread吗？
+
+不影响。若bthread因bthread API而阻塞，它会把当前pthread worker让给其他bthread。若bthread因pthread API或系统函数而阻塞，当前pthread worker上待运行的bthread会被其他空闲的pthread worker偷过去运行。
+
+##### Q：pthread中可以调用bthread API吗？
+
+可以。bthread API在bthread中被调用时影响的是当前bthread，在pthread中被调用时影响的是当前pthread。使用bthread API的代码可以直接运行在pthread中。
+
+##### Q：若有大量的bthread调用了阻塞的pthread或系统函数，会影响RPC运行么？
+
+会。比如有8个pthread worker，当有8个bthread都调用了系统usleep()后，处理网络收发的RPC代码就暂时无法运行了。只要阻塞时间不太长, 这一般没什么影响, 毕竟worker都用完了, 除了排队也没有什么好方法.
+在brpc中用户可以选择调大worker数来缓解问题, 在server端可设置[ServerOptions.num_threads](server.md#id-创建和设置Server-worker线程数)或[-bthread_concurrency](http://brpc.baidu.com:8765/flags/bthread_concurrency), 在client端可设置[-bthread_concurrency](http://brpc.baidu.com:8765/flags/bthread_concurrency).
+
+那有没有完全规避的方法呢?
+
+- 一个容易想到的方法是动态增加worker数. 但实际未必如意, 当大量的worker同时被阻塞时,
+  它们很可能在等待同一个资源(比如同一把锁), 增加worker可能只是增加了更多的等待者. 
+- 大部分RPC框架采取的方法是区分io线程和worker线程, io线程专门处理收发, worker线程调用用户逻辑,
+  即使worker线程全部阻塞也不会影响io线程. 但这个方法使得每个请求都要从io线程跳转至worker线程,
+  增加了一次上下文切换, 在机器繁忙时, 切换都有一定概率无法被及时调度, 会导致更多的延时长尾.
+  另一个问题是增加一层处理环节(io线程)并不能缓解拥塞, 如果worker线程全部卡住, 程序仍然会卡住,
+  只是卡的地方从socket缓冲转移到了io线程和worker线程之间的消息队列. 换句话说, 在worker卡住时,
+  还在运行的io线程做的可能是无用功. 事实上, 这正是上面提到的"没什么影响"真正的含义.
+- 一个实际的解决方法是[限制最大并发](server.md#限制最大并发), 只要同时被处理的请求数低于worker数, 自然可以规避掉"所有worker被阻塞"的情况.
+- 另一个解决方法当被阻塞的worker超过阈值时(比如8个中的6个), 就不在原地调用用户代码了, 而是扔到一个独立的线程池中运行. 这样即使用户代码全部阻塞, 也总能保留几个worker处理rpc的收发. 不过目前bthread模式并没有这个机制, 但类似的机制在[打开pthread模式](server.md#pthread模式)时已经被实现了. 那像上面提到的, 这个机制是不是在用户代码都阻塞时也在做"无用功"呢? 可能是的. 但这个机制更多是为了规避在一些极端情况下的死锁, 比如所有的用户代码都lock在一个pthread mutex上, 并且这个mutex需要在某个RPC回调中unlock, 如果所有的worker都被阻塞, 那么就没有线程来处理RPC回调了, 整个程序就死锁了. 虽然绝大部分的RPC实现都有这个潜在问题, 但实际出现频率似乎很低, 只要养成不在锁内做RPC的好习惯, 这是完全可以规避的. 
+
+##### Q：bthread会有[Channel](https://gobyexample.com/channels)吗？
+
+不会。channel代表的是两点间的关系，而很多现实问题是多点的，这个时候使用channel最自然的解决方案就是：有一个角色负责操作某件事情或某个资源，其他线程都通过channel向这个角色发号施令。如果我们在程序中设置N个角色，让它们各司其职，那么程序就能分类有序地运转下去。所以使用channel的潜台词就是把程序划分为不同的角色。channel固然直观，但是有代价：额外的上下文切换。做成任何事情都得等到被调用处被调度，处理，回复，调用处才能继续。这个再怎么优化，再怎么尊重cache locality，也是有明显开销的。另外一个现实是：用channel的代码也不好写。由于业务一致性的限制，一些资源往往被绑定在一起，所以一个角色很可能身兼数职，但它做一件事情时便无法做另一件事情，而事情又有优先级。各种打断、跳出、继续形成的最终代码异常复杂。
+
+我们需要的往往是buffered channel，扮演的是队列和有序执行的作用，bthread在r31345之后提供[ExecutionQueue](execution_queue.md)，可以完成这个目的。

docs/cn/bthread_id.md

+bthread_id是一个特殊的同步结构，它可以互斥RPC过程中的不同环节，也可以O(1)时间内找到RPC上下文(即Controller)。注意，这里我们谈论的是bthread_id_t，不是bthread_t（bthread的tid），这个名字起的确实不太好，容易混淆。
+
+具体来说，bthread_id解决的问题有：
+
+- 在发送RPC过程中response回来了，处理response的代码和发送代码产生竞争。
+- 设置timer后很快触发了，超时处理代码和发送代码产生竞争。
+- 重试产生的多个response同时回来产生的竞争。
+- 通过correlation_id在O(1)时间内找到对应的RPC上下文，而无需建立从correlation_id到RPC上下文的全局哈希表。
+- 取消RPC。
+
+上文提到的bug在其他rpc框架中广泛存在，下面我们来看下brpc是如何通过bthread_id解决这些问题的。
+
+bthread_id包括两部分，一个是用户可见的64位id，另一个是对应的不可见的bthread::Id结构体。用户接口都是操作id的。从id映射到结构体的方式和brpc中的[其他结构](memory_management.md)类似：32位是内存池的位移，32位是version。前者O(1)时间定位，后者防止ABA问题。
+
+bthread_id的接口不太简洁，有不少API：
+
+- create
+- lock
+- unlock
+- unlock_and_destroy
+- join
+- error
+
+这么多接口是为了满足不同的使用流程。
+
+- 发送request的流程：create -> lock -> ... register timer and send RPC ... -> unlock
+- 接收response的流程：lock -> ..process response -> call done

docs/cn/bthread_or_not.md

+brpc提供了[异步接口](client.md#异步访问)，所以一个常见的问题是：我应该用异步接口还是bthread？
+
+短回答：延时不高时你应该先用简单易懂的同步接口，不行的话用异步接口，只有在需要多核并行计算时才用bthread。
+
+# 同步或异步
+
+异步即用回调代替阻塞，有阻塞的地方就有回调。虽然在javascript这种语言中回调工作的很好，接受度也非常高，但只要用过，就会发现这和我们需要的回调是两码事，这个区别不是[lambda](https://en.wikipedia.org/wiki/Anonymous_function)，也不是[future](https://en.wikipedia.org/wiki/Futures_and_promises)，而是javascript是单线程的。javascript的回调放到多线程下可能没有一个能跑过，竞争太多，单线程的同步方法和多线程的同步方法是完全不同的。那是不是服务能搞成类似的形式呢？多个线程，每个都是独立的eventloop。可以，ub**a**server就是（注意带a)，但实际效果糟糕，因为阻塞改回调可不简单，当阻塞发生在循环，条件分支，深层子函数中时，改造特别困难，况且很多老代码、第三方代码根本不可能去改造。结果是代码中会出现不可避免的阻塞，导致那个线程中其他回调都被延迟，流量超时，server性能不符合预期。如果你说，”我想把现在的同步代码改造为大量的回调，除了我其他人都看不太懂，并且性能可能更差了”，我猜大部分人不会同意。别被那些鼓吹异步的人迷惑了，他们写的是从头到尾从下到上全异步且不考虑多线程的代码，和你要写的完全是两码事。
+
+brpc中的异步和单线程的异步是完全不同的，异步回调会运行在与调用处不同的线程中，你会获得多核扩展性，但代价是你得意识到多线程问题。你可以在回调中阻塞，只要线程够用，对server整体的性能并不会有什么影响。不过异步代码还是很难写的，所以我们提供了[组合访问](combo_channel.md)来简化问题，通过组合不同的channel，你可以声明式地执行复杂的访问，而不用太关心其中的细节。
+
+当然，延时不长，qps不高时，我们更建议使用同步接口，这也是创建bthread的动机：维持同步代码也能提升交互性能。
+
+**判断使用同步或异步**：计算qps * latency(in seconds)，如果和cpu核数是同一数量级，就用同步，否则用异步。
+
+比如：
+
+- qps = 2000，latency = 10ms，计算结果 = 2000 * 0.01s = 20。和常见的32核在同一个数量级，用同步。
+- qps = 100, latency = 5s, 计算结果 = 100 * 5s = 500。和核数不在同一个数量级，用异步。
+- qps = 500, latency = 100ms，计算结果 = 500 * 0.1s = 50。基本在同一个数量级，可用同步。如果未来延时继续增长，考虑异步。
+
+这个公式计算的是同时进行的平均请求数（你可以尝试证明一下），和线程数，cpu核数是可比的。当这个值远大于cpu核数时，说明大部分操作并不耗费cpu，而是让大量线程阻塞着，使用异步可以明显节省线程资源（栈占用的内存）。当这个值小于或和cpu核数差不多时，异步能节省的线程资源就很有限了，这时候简单易懂的同步代码更重要。
+
+# 异步或bthread
+
+有了bthread这个工具，用户甚至可以自己实现异步。以“半同步”为例，在brpc中用户有多种选择：
+
+- 发起多个异步RPC后挨个Join，这个函数会阻塞直到RPC结束。（这儿是为了和bthread对比，实现中我们建议你使用[ParallelChannel](combo_channel.md#parallelchannel)，而不是自己Join）
+- 启动多个bthread各自执行同步RPC后挨个join bthreads。
+
+哪种效率更高呢？显然是前者。后者不仅要付出创建bthread的代价，在RPC过程中bthread还被阻塞着，不能用于其他用途。
+
+**如果仅仅是为了并发RPC，别用bthread。**
+
+不过当你需要并行计算时，问题就不同了。使用bthread可以简单地构建树形的并行计算，充分利用多核资源。比如检索过程中有三个环节可以并行处理，你可以建立两个bthread运行两个环节，在原地运行剩下的环节，最后join那两个bthread。过程大致如下：
+```c++
+bool search() {
+  ...
+  bthread th1, th2;
+  if (bthread_start_background(&th1, NULL, part1, part1_args) != 0) {
+    LOG(ERROR) << "Fail to create bthread for part1";
+    return false;
+  }
+  if (bthread_start_background(&th2, NULL, part2, part2_args) != 0) {
+    LOG(ERROR) << "Fail to create bthread for part2";
+    return false;
+  }
+  part3(part3_args);
+  bthread_join(th1);
+  bthread_join(th2);
+  return true;
+}
+```
+这么实现的point：
+- 你当然可以建立三个bthread分别执行三个部分，最后join它们，但相比这个方法要多耗费一个线程资源。
+- bthread从建立到执行是有延时的（调度延时），在不是很忙的机器上，这个延时的中位数在3微秒左右，90%在10微秒内，99.99%在30微秒内。这说明两点：
+  - 计算时间超过1ms时收益比较明显。如果计算非常简单，几微秒就结束了，用bthread是没有意义的。
+  - 尽量让原地运行的部分最慢，那样bthread中的部分即使被延迟了几微秒，最后可能还是会先结束，而消除掉延迟的影响。并且join一个已结束的bthread时会立刻返回，不会有上下文切换开销。
+
+另外当你有类似线程池的需求时，像执行一类job的线程池时，也可以用bthread代替。如果对job的执行顺序有要求，你可以使用基于bthread的[ExecutionQueue](execution_queue.md)。

docs/cn/builtin_service.md

+# 什么是内置服务？
+
+内置服务以多种形式展现服务器内部状态，提高你开发和调试服务的效率。brpc通过HTTP协议提供内置服务，可通过浏览器或curl访问，服务器会根据User-Agent返回纯文本或html，你也可以添加?console=1要求返回纯文本。我们在自己的开发机上启动了[一个长期运行的例子](http://brpc.baidu.com:8765/)，你可以点击后随便看看。服务端口只有在8000-8999内才能被笔记本访问到，对于范围之外的端口可以使用[rpc_view](rpc_view.md)或在命令行中使用curl <SERVER-URL>。
+
+从浏览器访问： 
+
+![img](../images/builtin_service_more.png)
+
+ 从命令行访问：
+
+ ![img](../images/builtin_service_from_console.png) 
+
+# 安全模式
+
+出于安全考虑，直接对外服务需要关闭内置服务（包括经过nginx或其他http server转发流量的），具体方法请阅读[这里](server.md#安全模式)。
+
+# 主要服务
+
+[status](status.md)
+
+[vars](vars.md)
+
+[connections](connections.md)
+
+[flags](flags.md)
+
+[rpcz](rpcz.md)
+
+[cpu profiler](cpu_profiler.md)
+
+[heap profiler](heap_profiler.md)
+
+[contention profiler](contention_profiler.md)
+
+# 其他服务
+
+[version服务](http://brpc.baidu.com:8765/version)可以查看服务器的版本。用户可通过Server::set_version()设置Server的版本，如果用户没有设置，框架会自动为用户生成，规则：`brpc_server_<service-name1>_<service-name2> ...`
+
+![img](../images/version_service.png)
+
+[health服务](http://brpc.baidu.com:8765/health)可以探测服务的存活情况。
+
+![img](../images/health_service.png)
+
+[protobufs服务](http://brpc.baidu.com:8765/protobufs)可以查看程序中所有的protobuf结构体。
+
+![img](../images/protobufs_service.png)
+
+[vlog服务](http://brpc.baidu.com:8765/vlog)可以查看程序中当前可开启的[VLOG](streaming_log.md#VLOG)。
+
+![img](../images/vlog_service.png)
+
+dir服务可以浏览服务器上的所有文件，这个服务很敏感，默认关闭也不建议打开。
+
+threads服务可以查看进程内所有线程的运行状况，调用时对程序性能影响较大，默认关闭。

docs/cn/case_apicontrol.md

+# 进展
+
+| 时间          | 内容                                    | 说明             |
+| ----------- | ------------------------------------- | -------------- |
+| 8.11 - 8.28 | 调研 + 研发 + 自测                          | 自测性能报告见附件      |
+| 9.8 - 9.22  | QA测试                                  | QA测试报告见附件      |
+| 10.8        | 北京机房1台机器上线                            |                |
+| 10.14       | 北京机房1台机器上线                            | 修复URL编码问题      |
+| 10.19       | 北京机房7/35机器上线杭州和南京各2台机器上线              | 开始小流量上线        |
+| 10.22       | 北京机房10/35机器上线杭州机房5/26机器上线南京机房5/19机器上线 | 修复http响应数据压缩问题 |
+| 11.3        | 北京机房10/35机器上线                         | 修复RPC内存泄露问题    |
+| 11.6        | 杭州机房5/26机器上线南京机房5/19机器上线              | 同北京机房版本        |
+| 11.9        | 北京机房全流量上线                             |                |
+
+截止目前，线上服务表现稳定。
+
+# QA测试结论
+
+1. 【性能测试】单机支持最大QPS：**9000+**。可以有效解决原来hulu_pbrpc中一个慢服务拖垮所有服务的问题。性能很好。
+2. 【稳定性测试】长时间压测没问题。
+
+QA测试结论：通过
+
+# 性能提升实时统计
+
+统计时间2015.11.3 15:00 – 2015.11.9 14:30，共**143.5**小时（近6天）不间断运行。北京机房升级前和升级后同机房各6台机器，共**12**台线上机器的Noah监控数据。
+
+| 指标       | 升级**前**均值hulu_pbrpc | 升级**后**均值brpc | 收益对比         | 说明                       |
+| -------- | ------------------- | ------------- | ------------ | ------------------------ |
+| CPU占用率   | 67.35%              | 29.28%        | 降低**56.53**% |                          |
+| 内存占用     | 327.81MB            | 336.91MB      | 基本持平         |                          |
+| 鉴权平响(ms) | 0.605               | 0.208         | 降低**65.62**% |                          |
+| 转发平响(ms) | 22.49               | 23.18         | 基本持平         | 依赖后端各个服务的性能              |
+| 总线程数     | 193                 | 132           | 降低**31.61**% | Baidu RPC版本线程数使用率较低，还可降低 |
+| 极限QPS    | 3000                | 9000          | 提升**3**倍     | 线下使用Geoconv和Geocoder服务测试 |
+
+**CPU使用率(%)**（红色为升级前，蓝色为升级后）
+![img](../images/apicontrol_compare_1.png)
+
+**内存使用量(KB)**（红色为升级前，蓝色为升级后）
+![img](../images/apicontrol_compare_2.png)
+
+**鉴权平响(ms)**（红色为升级前，蓝色为升级后）
+![img](../images/apicontrol_compare_3.png)
+
+**转发平响(ms)**（红色为升级前，蓝色为升级后）
+![img](../images/apicontrol_compare_4.png)
+
+**总线程数(个)**（红色为升级前，蓝色为升级后）
+![img](../images/apicontrol_compare_5.png)

docs/cn/case_baidu_dsp.md

+# 背景
+
+baidu-dsp是联盟基于Ad Exchange和RTB模式的需求方平台，服务大客户、代理的投放产品体系。我们改造了多个模块，均取得了显著的效果。本文只介绍其中关于super-nova-as的改动。super-nova-as是的baidu-dsp的AS，之前使用ub-aserver编写，为了尽量减少改动，我们没有改造整个as，而只是把super-nova-as连接下游（ctr-server、cvr-server、super-nova-bs）的client从ubrpc升级为brpc。
+
+# 结论
+
+1. as的吞吐量有显著提升（不到1500 -> 2500+）
+2. cpu优化：从1500qps 50%cpu_idle提高到2000qps 50% cpu_idle；
+3. 超时率改善明显。
+
+# 测试过程
+
+1. 环境：1个as，1个bs，1个ctr，1个cvr；部署情况为：bs单机部署，as+ctr+cvr混布；ctr和cvr为brpc版本
+2. 分别采用1000,1500压力对ubrpc版本的as进行压测，发现1500压力下，as对bs有大量的超时，as到达瓶颈；
+3. 分别采用2000,2500压力对brpc版本的as进行压测，发现2500压力下，as机器的cpu_idle低于30%，as到达瓶颈。brpc对资源利用充分。
+
+|          | ubrpc                                    | brpc                                |
+| -------- | ---------------------------------------- | ---------------------------------------- |
+| 流量       | ![img](../images/baidu_dsp_compare_1.png) | ![img](../images/baidu_dsp_compare_2.png) |
+| bs成功率    | ![img](../images/baidu_dsp_compare_3.png) | ![img](../images/baidu_dsp_compare_4.png) |
+| cpu_idle | ![img](../images/baidu_dsp_compare_5.png) | ![img](../images/baidu_dsp_compare_6.png) |
+| ctr成功率   | ![img](../images/baidu_dsp_compare_7.png) | ![img](../images/baidu_dsp_compare_8.png) |
+| cvr成功率   | ![img](../images/baidu_dsp_compare_9.png) | ![img](../images/baidu_dsp_compare_10.png) |

docs/cn/case_elf.md

+# 背景
+
+ELF(Essential/Extreme/Excellent Learning Framework) 框架为公司内外的大数据应用提供学习/挖掘算法开发支持。 平台主要包括数据迭代处理的框架支持，并行计算过程中的通信支持和用于存储大规模参数的分布式、快速、高可用参数服务器。应用于fcr-model，公有云bml，大数据实验室，语音技术部门等等。之前是基于[zeromq](http://zeromq.org/)封装的rpc，这次改用brpc。
+
+# 结论
+
+单个rpc-call以及单次请求所有rpc-call的提升非常显著，延时都缩短了**50%**以上，总训练的耗时除了ftrl-sync-no-shuffle提升不明显外，其余三个算法训练总体性能都有**15%**左右的提升。现在瓶颈在于计算逻辑，所以相对单个的rpc的提升没有那么多。该成果后续会推动凤巢模型训练的上线替换。详细耗时见下节。
+
+# 性能对比报告
+
+## 算法总耗时
+
+ftrl算法: 替换前总耗时2:4:39, 替换后总耗时1:42:48, 提升18%
+
+ftrl-sync-no-shuffle算法: 替换前总耗时3:20:47, 替换后总耗时3:15:28, 提升2.5%
+
+ftrl-sync算法: 替换前总耗时4:28:47, 替换后总耗时3:45:57, 提升16%
+
+fm-sync算法: 替换前总耗时6:16:37, 替换后总耗时5:21:00, 提升14.6%
+
+## 子任务耗时
+
+单个rpc-call(针对ftrl算法)
+
+|      | Average   | Max       | Min        |
+| ---- | --------- | --------- | ---------- |
+| 替换前  | 164.946ms | 7938.76ms | 0.249756ms |
+| 替换后  | 10.4198ms | 2614.38ms | 0.076416ms |
+| 缩短   | 93%       | 67%       | 70%        |
+
+单次请求所有rpc-call(针对ftrl算法)
+
+|      | Average  | Max      | Min       |
+| ---- | -------- | -------- | --------- |
+| 替换前  | 658.08ms | 7123.5ms | 1.88159ms |
+| 替换后  | 304.878  | 2571.34  | 0         |
+| 缩短   | 53.7%    | 63.9%    |           |
+
+##结论
+
+单个rpc-call以及单次请求所有rpc-call的提升非常显著，提升都在50%以上，总任务的耗时除了ftrl-sync-no-shuffle提升不明显外，其余三个算法都有15%左右的提升，现在算法的瓶颈在于对计算逻辑，所以相对单个的rpc的提升没有那么多。
+
+附cpu profiling结果, top 40没有rpc相关函数。
+```
+Total: 8664 samples
+     755   8.7%   8.7%      757   8.7% baidu::elf::Partitioner
+     709   8.2%  16.9%      724   8.4% baidu::elf::GlobalShardWriterClient::local_aggregator::{lambda#1}::operator [clone .part.1341]
+     655   7.6%  24.5%      655   7.6% boost::detail::lcast_ret_unsigned
+     582   6.7%  31.2%      642   7.4% baidu::elf::RobinHoodLinkedHashMap
+     530   6.1%  37.3%     2023  23.4% std::vector
+     529   6.1%  43.4%      529   6.1% std::binary_search
+     406   4.7%  48.1%      458   5.3% tc_delete
+     405   4.7%  52.8%     2454  28.3% baidu::elf::GlobalShardWriterClient
+     297   3.4%  56.2%      297   3.4% __memcpy_sse2_unaligned
+     256   3.0%  59.2%      297   3.4% tc_new
+     198   2.3%  61.5%      853   9.8% std::__introsort_loop
+     157   1.8%  63.3%      157   1.8% baidu::elf::GrowableArray
+     152   1.8%  65.0%      177   2.0% calculate_grad
+     142   1.6%  66.7%      699   8.1% baidu::elf::BlockTableReaderManager
+     137   1.6%  68.2%      656   7.6% baidu::elf::DefaultWriterServer
+     127   1.5%  69.7%      127   1.5% _init
+     122   1.4%  71.1%      582   6.7% __gnu_cxx::__normal_iterator
+     117   1.4%  72.5%      123   1.4% baidu::elf::GrowableArray::emplace_back
+     116   1.3%  73.8%      116   1.3% baidu::elf::RobinHoodHashMap::insert
+     101   1.2%  75.0%      451   5.2% baidu::elf::NoCacheReaderClient
+      99   1.1%  76.1%     3614  41.7% parse_ins
+      97   1.1%  77.2%       97   1.1% std::basic_string::_Rep::_M_dispose [clone .part.12]
+      96   1.1%  78.3%      154   1.8% std::basic_string
+      91   1.1%  79.4%      246   2.8% boost::algorithm::split_iterator
+      87   1.0%  80.4%      321   3.7% boost::function2
+      76   0.9%  81.3%      385   4.4% boost::detail::function::functor_manager
+      69   0.8%  82.1%       69   0.8% std::locale::~locale
+      63   0.7%  82.8%      319   3.7% std::__unguarded_linear_insert
+      58   0.7%  83.5%     2178  25.2% boost::algorithm::split [clone .constprop.2471]
+      54   0.6%  84.1%      100   1.2% std::vector::_M_emplace_back_aux
+      49   0.6%  84.7%       49   0.6% boost::algorithm::detail::is_any_ofF
+      47   0.5%  85.2%       79   0.9% baidu::elf::DefaultReaderServer
+      41   0.5%  85.7%       41   0.5% std::locale::_S_initialize
+      39   0.5%  86.1%      677   7.8% boost::detail::function::function_obj_invoker2
+      39   0.5%  86.6%       39   0.5% memset
+      39   0.5%  87.0%       39   0.5% std::locale::locale
+      38   0.4%  87.5%       50   0.6% FTRLAggregator::serialize
+      36   0.4%  87.9%       67   0.8% tcmalloc::CentralFreeList::ReleaseToSpans
+      34   0.4%  88.3%       34   0.4% madvise
+      34   0.4%  88.7%       38   0.4% tcmalloc::CentralFreeList::FetchFromOneSpans
+      32   0.4%  89.0%       32   0.4% std::__insertion_sort
+```

docs/cn/case_ubrpc.md

+# 背景
+
+云平台部把使用ubrpc的模块改造为使用brpc。由于使用了mcpack2pb的转换功能，这个模块既能被老的ubrpc client访问，也可以通过protobuf类的协议访问（标准协议，sofa-pbrpc协议等等）。
+
+原有使用43台机器（对ubrpc也有富余），brpc使用3台机器即可（此时访问redis的io达到瓶颈）。当前流量4w qps，支持流量增长，考虑跨机房冗余，避免redis和vip瓶颈，brpc实际使用8台机器提供服务。 
+
+brpc改造后的connecter收益明显，可以用较少的机器提供更优质的服务。收益分3个方面：
+
+# 相同配置的机器qps和latency的比较 
+
+通过逐渐缩容，不断增加connecter的压力，获得单机qps和latency的对应数据如下： 
+![img](../images/ubrpc_compare_1.png)
+
+机器配置：cpu: 24 Intel(R) Xeon(R) CPU  E5645  @ 2.40GHz || mem: 64G 
+
+混布情况：同机部署了逻辑层2.0/3.0和C逻辑层，均有流量 
+
+图中可以看到随着压力的增大：
+* brpc的延时，增加微乎其微，提供了较为一致的延时体验
+* ubrpc的延时，快速增大，到了6000~8000qps的时候，出现*queue full*，服务不可用。
+
+# 不同配置机器qps和延时的比较
+qps固定为6500，观察延时。
+| 机器名称  | 略                                        | 略                                        |
+| ----- | ---------------------------------------- | ---------------------------------------- |
+| cpu   | 24 Intel(R) Xeon(R) CPU E5645  @ 2.40GHz | 24 Intel(R) Xeon(R) CPU E5-2620 0 @ 2.00GHz |
+| ubrpc | 8363.46（us）                              | 12649.5（us）                              |
+| brpc  | 3364.66（us）                              | 3382.15（us）                              |
+
+有此可见： 
+
+* ubrpc在不同配置下性能表现差异大，在配置较低的机器下表现较差。
+
+* brpc表现的比ubrpc好，在较低配置的机器上也能有好的表现，因机器不同带来的差异不大。
+
+# 相同配置机器idle分布的比较 
+
+机器配置：cpu： 24 Intel(R) Xeon(R) CPU  E5645  @ 2.40GHz || mem：64G 
+
+![img](../images/ubrpc_compare_2.png)
+
+在线上缩容 不断增大压力过程中：
+
+* ubrpc cpu idle分布在35%~60%，在55%最集中，最低30%； 
+* brpc cpu idle分布在60%~85%，在75%最集中，最低50%； brpc比ubrpc对cpu的消耗低。

docs/cn/connections.md

+[connections服务](http://brpc.baidu.com:8765/connections)可以查看所有的连接。一个典型的页面如下：
+
+server_socket_count: 5
+
+| CreatedTime                | RemoteSide          | SSL  | Protocol  | fd   | BytesIn/s | In/s | BytesOut/s | Out/s | BytesIn/m | In/m | BytesOut/m | Out/m | SocketId |
+| -------------------------- | ------------------- | ---- | --------- | ---- | --------- | ---- | ---------- | ----- | --------- | ---- | ---------- | ----- | -------- |
+| 2015/09/21-21:32:09.630840 | 172.22.38.217:51379 | No   | http      | 19   | 1300      | 1    | 269        | 1     | 68844     | 53   | 115860     | 53    | 257      |
+| 2015/09/21-21:32:09.630857 | 172.22.38.217:51380 | No   | http      | 20   | 1308      | 1    | 5766       | 1     | 68884     | 53   | 129978     | 53    | 258      |
+| 2015/09/21-21:32:09.630880 | 172.22.38.217:51381 | No   | http      | 21   | 1292      | 1    | 1447       | 1     | 67672     | 52   | 143414     | 52    | 259      |
+| 2015/09/21-21:32:01.324587 | 127.0.0.1:55385     | No   | baidu_std | 15   | 1480      | 20   | 880        | 20    | 88020     | 1192 | 52260      | 1192  | 512      |
+| 2015/09/21-21:32:01.325969 | 127.0.0.1:55387     | No   | baidu_std | 17   | 4016      | 40   | 1554       | 40    | 238879    | 2384 | 92660      | 2384  | 1024     |
+
+channel_socket_count: 1
+
+| CreatedTime                | RemoteSide     | SSL  | Protocol  | fd   | BytesIn/s | In/s | BytesOut/s | Out/s | BytesIn/m | In/m | BytesOut/m | Out/m | SocketId |
+| -------------------------- | -------------- | ---- | --------- | ---- | --------- | ---- | ---------- | ----- | --------- | ---- | ---------- | ----- | -------- |
+| 2015/09/21-21:32:01.325870 | 127.0.0.1:8765 | No   | baidu_std | 16   | 1554      | 40   | 4016       | 40    | 92660     | 2384 | 238879     | 2384  | 0        |
+
+channel_short_socket_count: 0
+
+上述信息分为三段：
+
+- 第一段是server接受(accept)的连接。
+- 第二段是server与下游的单连接（使用brpc::Channel建立），fd为-1的是虚拟连接，对应第三段中所有相同RemoteSide的连接。
+- 第三段是server与下游的短连接或连接池(pooled connections)，这些连接从属于第二段中的相同RemoteSide的虚拟连接。
+
+表格标题的含义：
+
+- RemoteSide : 远端的ip和端口。
+- SSL：是否使用SSL加密，若为Yes的话，一般是HTTPS连接。
+- Protocol : 使用的协议，可能为baidu_std hulu_pbrpc sofa_pbrpc memcache http public_pbrpc nova_pbrpc nshead_server等。
+- fd : file descriptor（文件描述符），可能为-1。
+- BytesIn/s : 上一秒读入的字节数
+- In/s : 上一秒读入的消息数（消息是对request和response的统称）
+- BytesOut/s : 上一秒写出的字节数
+- Out/s : 上一秒写出的消息数
+- BytesIn/m: 上一分钟读入的字节数
+- In/m: 上一分钟读入的消息数
+- BytesOut/m: 上一分钟写出的字节数
+- Out/m: 上一分钟写出的消息数
+- SocketId ：内部id，用于debug，用户不用关心。
+
+
+
+典型截图分别如下所示：
+
+单连接：![img](../images/single_conn.png)
+
+连接池：![img](../images/pooled_conn.png)
+
+短连接：![img](../images/short_conn.png)
+

docs/cn/consistent_hashing.md

+# 概述
+
+一些场景希望同样的请求尽量落到一台机器上，比如访问缓存集群时，我们往往希望同一种请求能落到同一个后端上，以充分利用其上已有的缓存，不同的机器承载不同的稳定working set。而不是随机地散落到所有机器上，那样的话会迫使所有机器缓存所有的内容，最终由于存不下形成颠簸而表现糟糕。 我们都知道hash能满足这个要求，比如当有n台服务器时，输入x总是会发送到第hash(x) % n台服务器上。但当服务器变为m台时，hash(x) % n和hash(x) % m很可能都不相等，这会使得几乎所有请求的发送目的地都发生变化，如果目的地是缓存服务，所有缓存将失效，继而对原本被缓存遮挡的数据库或计算服务造成请求风暴，触发雪崩。一致性哈希是一种特殊的哈希算法，在增加服务器时，发向每个老节点的请求中只会有一部分转向新节点，从而实现平滑的迁移。[这篇论文](http://blog.phpdr.net/wp-content/uploads/2012/08/Consistent-Hashing-and-Random-Trees.pdf)中提出了一致性hash的概念。
+
+一致性hash满足以下四个性质：
+
+- 平衡性 (Balance) : 每个节点被选到的概率是O(1/n)。
+- 单调性 (Monotonicity) : 当新节点加入时， 不会有请求在老节点间移动， 只会从老节点移动到新节点。当有节点被删除时，也不会影响落在别的节点上的请求。
+- 分散性 (Spread) : 当上游的机器看到不同的下游列表时(在上线时及不稳定的网络中比较常见),  同一个请求尽量映射到少量的节点中。
+- 负载 (Load) : 当上游的机器看到不同的下游列表的时候， 保证每台下游分到的请求数量尽量一致。
+
+
+
+# 实现方式
+
+所有server的32位hash值在32位整数值域上构成一个环(Hash Ring)，环上的每个区间和一个server唯一对应，如果一个key落在某个区间内， 它就被分流到对应的server上。 
+
+![img](../images/chash.png)
+
+当删除一个server的， 它对应的区间会归属于相邻的server，所有的请求都会跑过去。当增加一个server时，它会分割某个server的区间并承载落在这个区间上的所有请求。单纯使用Hash Ring很难满足我们上节提到的属性，主要两个问题：
+
+- 在机器数量较少的时候， 区间大小会不平衡。
+- 当一台机器故障的时候， 它的压力会完全转移到另外一台机器， 可能无法承载。
+
+为了解决这个问题，我们为每个server计算m个hash值，从而把32位整数值域划分为n*m个区间，当key落到某个区间时，分流到对应的server上。那些额外的hash值使得区间划分更加均匀，被称为Virtual Node。当删除一个server时，它对应的m个区间会分别合入相邻的区间中，那个server上的请求会较为平均地转移到其他server上。当增加server时，它会分割m个现有区间，从对应server上分别转移一些请求过来。
+
+由于节点故障和变化不常发生， 我们选择了修改复杂度为O(n)的有序数组来存储hash ring，每次分流使用二分查找来选择对应的机器， 由于存储是连续的，查找效率比基于平衡二叉树的实现高。 线程安全性请参照[Double Buffered Data](lalb.md#doublybuffereddata)章节.
+
+# 使用方式
+
+我们内置了分别基于murmurhash3和md5两种hash算法的实现， 使用要做两件事：
+
+- 在Channel.Init 时指定*load_balancer_name*为 "c_murmurhash" 或 "c_md5"。
+
+- 发起rpc时通过Controller::set_request_code()填入请求的hash code。
+
+> request的hash算法并不需要和lb的hash算法保持一致，只需要hash的值域是32位无符号整数。由于memcache默认使用md5，访问memcached集群时请选择c_md5保证兼容性， 其他场景可以选择c_murmurhash以获得更高的性能和更均匀的分布。

docs/cn/contention_profiler.md

+brpc可以分析花在等待锁上的时间及发生等待的函数。
+
+# 开启方法
+
+按需开启。无需配置，不依赖tcmalloc，不需要链接frame pointer或libunwind。如果只是brpc client或没有使用brpc，看[这里](dummy_server.md)。 
+
+# 图示
+
+当很多线程争抢同一把锁时，一些线程无法立刻获得锁，而必须睡眠直到某个线程退出临界区。这个争抢过程我们称之为**contention**。在多核机器上，当多个线程需要操作同一个资源却被一把锁挡住时，便无法充分发挥多个核心的并发能力。现代OS通过提供比锁更底层的同步原语，使得无竞争锁完全不需要系统调用，只是一两条wait-free，耗时10-20ns的原子操作，非常快。而锁一旦发生竞争，一些线程就要陷入睡眠，再次醒来触发了OS的调度代码，代价至少为3-5us。所以让锁尽量无竞争，让所有线程“一起飞”是需要高性能的server的永恒话题。
+
+r31906后brpc支持contention profiler，可以分析在等待锁上花费了多少时间。等待过程中线程是睡着的不会占用CPU，所以contention profiler中的时间并不是cpu时间，也不会出现在[cpu profiler](cpu_profiler.md)中。cpu profiler可以抓到特别频繁的锁（以至于花费了很多cpu），但耗时真正巨大的临界区往往不是那么频繁，而无法被cpu profiler发现。**contention profiler和cpu profiler好似互补关系，前者分析等待时间（被动），后者分析忙碌时间。**还有一类由用户基于condition或sleep发起的主动等待时间，无需分析。
+
+目前contention profiler支持pthread_mutex_t（非递归）和bthread_mutex_t，开启后每秒最多采集1000个竞争锁，这个数字由参数-bvar_collector_expected_per_second控制（同时影响rpc_dump）。
+
+| Name                               | Value | Description                              | Defined At         |
+| ---------------------------------- | ----- | ---------------------------------------- | ------------------ |
+| bvar_collector_expected_per_second | 1000  | Expected number of samples to be collected per second | bvar/collector.cpp |
+
+如果一秒内竞争锁的次数Ｎ超过了1000，那么每把锁会有1000/N的概率被采集。在我们的各类测试场景中（qps在10万-60万不等）没有观察到被采集程序的性能有明显变化。
+
+我们通过实际例子来看下如何使用contention profiler，点击“contention”按钮（more左侧）后就会开启默认10秒的分析过程。下图是libraft中的一个示例程序的锁状况，这个程序是3个节点复制组的leader，qps在10-12万左右。左上角的**Total seconds: 2.449**是采集时间内（10秒）在锁上花费的所有等待时间。注意是“等待”，无竞争的锁不会被采集也不会出现在下图中。顺着箭头往下走能看到每份时间来自哪些函数。
+
+![img](../images/raft_contention_1.png)
+
+ 上图有点大，让我们放大一个局部看看。下图红框中的0.768是这个局部中最大的数字，它代表raft::LogManager::get_entry在等待涉及到bvar::detail::UniqueLockBase的函数上共等待了0.768秒（10秒内）。我们如果觉得这个时间不符合预期，就可以去排查代码。
+
+![img](../images/raft_contention_2.png)
+
+点击上方的count选择框，可以查看锁的竞争次数。选择后左上角变为了**Total samples: 439026**，代表采集时间内总共的锁竞争次数（估算）。图中箭头上的数字也相应地变为了次数，而不是时间。对比同一份结果的时间和次数，可以更深入地理解竞争状况。
+
+![img](../images/raft_contention_3.png)

docs/cn/cpu_profiler.md

+brpc可以分析程序中的热点函数。
+
+# 开启方法
+
+1. 链接`libtcmalloc_and_profiler.a`
+   1. 这么写也开启了tcmalloc，不建议单独链接cpu profiler而不链接tcmalloc，可能越界访问导致[crash](https://github.com/gperftools/gperftools/blob/master/README#L226)**。**可能由于tcmalloc不及时归还内存，越界访问不会crash。
+   2. 如果tcmalloc使用frame pointer而不是libunwind回溯栈，请确保在CXXFLAGS或CFLAGS中加上`-fno-omit-frame-pointer`，否则函数间的调用关系会丢失，最后产生的图片中都是彼此独立的函数方框。
+2. 定义宏BRPC_ENABLE_CPU_PROFILER, 一般加入编译参数-DBRPC_ENABLE_CPU_PROFILER。
+3. 如果只是brpc client或没有使用brpc，看[这里](dummy_server.md)。 
+
+ 注意要关闭Server端的认证，否则可能会看到这个：
+
+```
+$ tools/pprof --text localhost:9002/pprof/profile
+Use of uninitialized value in substitution (s///) at tools/pprof line 2703.
+http://localhost:9002/profile/symbol doesn't exist
+```
+
+server端可能会有这样的日志：
+
+```
+FATAL: 12-26 10:01:25:   * 0 [src/brpc/policy/giano_authenticator.cpp:65][4294969345] Giano fails to verify credentical, 70003
+WARNING: 12-26 10:01:25:   * 0 [src/brpc/input_messenger.cpp:132][4294969345] Authentication failed, remote side(127.0.0.1:22989) of sockfd=5, close it
+```
+
+# 图示
+
+下图是一次运行cpu profiler后的结果：
+
+- 左上角是总体信息，包括时间，程序名，总采样数等等。
+- View框中可以选择查看之前运行过的profile结果，Diff框中可选择查看和之前的结果的变化量，重启后清空。
+- 代表函数调用的方框中的字段从上到下依次为：函数名，这个函数本身（除去所有子函数）占的采样数和比例，这个函数及调用的所有子函数累计的采样数和比例。采样数越大框越大。
+- 方框之间连线上的数字表示被采样到的上层函数对下层函数的调用数，数字越大线越粗。
+
+热点分析一般开始于找到最大的框最粗的线考察其来源及去向。
+
+cpu profiler的原理是在定期被调用的SIGPROF handler中采样所在线程的栈，由于handler（在linux 2.6后）会被随机地摆放于活跃线程的栈上运行，cpu profiler在运行一段时间后能以很大的概率采集到所有活跃线程中的活跃函数，最后根据栈代表的函数调用关系汇总为调用图，并把地址转换成符号，这就是我们看到的结果图了。采集频率由环境变量CPUPROFILE_FREQUENCY控制，默认100，即每秒钟100次或每10ms一次。。在实践中cpu profiler对原程序的影响不明显。
+
+![img](../images/echo_cpu_profiling.png)
+
+你也可以使用[pprof](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/tools/pprof)或gperftools中的pprof进行profiling。
+
+比如`pprof --text localhost:9002 --seconds=5`的意思是统计运行在本机9002端口的server的cpu情况，时长5秒。一次运行的例子如下：
+
+```
+$ tools/pprof --text 0.0.0.0:9002 --seconds=5
+Gathering CPU profile from http://0.0.0.0:9002/pprof/profile?seconds=5 for 5 seconds to
+  /home/gejun/pprof/echo_server.1419501210.0.0.0.0
+Be patient...
+Wrote profile to /home/gejun/pprof/echo_server.1419501210.0.0.0.0
+Removing funlockfile from all stack traces.
+Total: 2946 samples
+    1161  39.4%  39.4%     1161  39.4% syscall
+     248   8.4%  47.8%      248   8.4% bthread::TaskControl::steal_task
+     227   7.7%  55.5%      227   7.7% writev
+      87   3.0%  58.5%       88   3.0% ::cpp_alloc
+      74   2.5%  61.0%       74   2.5% __read_nocancel
+      46   1.6%  62.6%       48   1.6% tc_delete
+      42   1.4%  64.0%       42   1.4% brpc::Socket::Address
+      41   1.4%  65.4%       41   1.4% epoll_wait
+      35   1.2%  66.6%       35   1.2% memcpy
+      33   1.1%  67.7%       33   1.1% __pthread_getspecific
+      33   1.1%  68.8%       33   1.1% brpc::Socket::Write
+      33   1.1%  69.9%       33   1.1% epoll_ctl
+      28   1.0%  70.9%       42   1.4% brpc::policy::ProcessRpcRequest
+      27   0.9%  71.8%       27   0.9% butil::IOBuf::_push_back_ref
+      27   0.9%  72.7%       27   0.9% bthread::TaskGroup::ending_sched
+```
+
+省略–text进入交互模式，如下图所示：
+
+```
+$ tools/pprof localhost:9002 --seconds=5       
+Gathering CPU profile from http://0.0.0.0:9002/pprof/profile?seconds=5 for 5 seconds to
+  /home/gejun/pprof/echo_server.1419501236.0.0.0.0
+Be patient...
+Wrote profile to /home/gejun/pprof/echo_server.1419501236.0.0.0.0
+Removing funlockfile from all stack traces.
+Welcome to pprof!  For help, type 'help'.
+(pprof) top
+Total: 2954 samples
+    1099  37.2%  37.2%     1099  37.2% syscall
+     253   8.6%  45.8%      253   8.6% bthread::TaskControl::steal_task
+     240   8.1%  53.9%      240   8.1% writev
+      90   3.0%  56.9%       90   3.0% ::cpp_alloc
+      67   2.3%  59.2%       67   2.3% __read_nocancel
+      47   1.6%  60.8%       47   1.6% butil::IOBuf::_push_back_ref
+      42   1.4%  62.2%       56   1.9% brpc::policy::ProcessRpcRequest
+      41   1.4%  63.6%       41   1.4% epoll_wait
+      38   1.3%  64.9%       38   1.3% epoll_ctl
+      37   1.3%  66.1%       37   1.3% memcpy
+      35   1.2%  67.3%       35   1.2% brpc::Socket::Address
+```

docs/cn/dummy_server.md

+如果你的程序只使用了brpc的client或根本没有使用brpc，但你也想使用brpc的内置服务，只要在程序中启动一个空的server就行了，这种server我们称为**dummy server**。
+
+# 使用了brpc的client
+
+只要在程序运行目录建立dummy_server.port文件，填入一个端口号（比如8888），程序会马上在这个端口上启动一个dummy server。在浏览器中访问它的内置服务，便可看到同进程内的所有bvar。
+![img](../images/dummy_server_1.png) ![img](../images/dummy_server_2.png) 
+
+![img](../images/dummy_server_3.png)
+
+# 没有使用brpc
+
+你必须手动加入dummy server。你得先查看[Getting Started](getting_started.md)如何下载和编译brpc，然后在程序入口处加入如下代码片段：
+
+```c++
+#include <brpc/server.h>
+ 
+...
+ 
+int main() {
+    ...
+    brpc::Server dummy_server;
+    brpc::ServerOptions dummy_server_options;
+    dummy_server_options.num_threads = 0;  // 不要改变寄主程序的线程数。
+    if (dummy_server.Start(8888/*port*/, &dummy_server_options) != 0) {
+        LOG(FATAL) << "Fail to start dummy server";
+        return -1;
+    }
+    ...
+}
+```
+
+r31803之后加入dummy server更容易了，只要一行：
+
+```c++
+#include <brpc/server.h>
+ 
+...
+ 
+int main() {
+    ...
+    brpc::StartDummyServerAt(8888/*port*/);
+    ...
+}
+```

docs/cn/error_code.md

+brpc使用[brpc::Controller](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/controller.h)设置一次RPC的参数和获取一次RPC的结果，ErrorCode()和ErrorText()是Controller的两个方法，分别是该次RPC的错误码和错误描述，只在RPC结束后才能访问，否则结果未定义。ErrorText()由Controller的基类google::protobuf::RpcController定义，ErrorCode()则是brpc::Controller定义的。Controller还有个Failed()方法告知该次RPC是否失败，这三者的关系是：
+
+- 当Failed()为true时，ErrorCode()一定不为0，ErrorText()是非空的错误描述
+- 当Failed()为false时，ErrorCode()一定为0，ErrorText()是未定义的（目前在brpc中会为空，但你最好不要依赖这个事实）
+
+# 标记RPC为错误
+
+brpc的client端和server端都有Controller，都可以通过SetFailed()修改其中的ErrorCode和ErrorText。当多次调用一个Controller的SetFailed时，ErrorCode会被覆盖，ErrorText则是**添加**而不是覆盖，在client端，框架会额外加上第几次重试，在server端，框架会额外加上server的地址信息。
+
+client端Controller的SetFailed()常由框架调用，比如发送request失败，接收到的response不符合要求等等。只有在进行较复杂的访问操作时用户才可能需要设置client端的错误，比如在访问后端前做额外的请求检查，发现有错误时需要把RPC设置为失败。
+
+server端Controller的SetFailed()常由用户在服务回调中调用。当处理过程发生错误时，一般调用SetFailed()并释放资源后就return了。框架会把错误码和错误信息按交互协议填入response，client端的框架收到后会填入它那边的Controller中，从而让用户在RPC结束后取到。需要注意的是，**server端在SetFailed()时一般不需要再打条日志。**打日志是比较慢的，在繁忙的线上磁盘上，很容易出现巨大的lag。一个错误频发的client容易减慢整个server的速度而影响到其他的client，理论上来说这甚至能成为一种攻击手段。对于希望在server端看到错误信息的场景，可以打开**-log_error_text**开关（已上线服务可访问/flags/log_error_text?setvalue=true动态打开），server会在每次失败的RPC后把对应Controller的ErrorText()打印出来。
+
+# brpc的错误码
+
+brpc使用的所有ErrorCode都定义在[errno.proto](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/errno.proto)中，*SYS_*开头的来自linux系统，与/usr/include/errno.h中定义的精确一致，定义在proto中是为了跨语言。其余的是brpc自有的。
+
+[berror(error_code)](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/butil/errno.h)可获得error_code的描述，berror()可获得[system errno](http://www.cplusplus.com/reference/cerrno/errno/)的描述。**ErrorText() != berror(****ErrorCode())**，ErrorText()会包含更具体的错误信息。brpc默认包含berror，你可以直接使用。
+
+brpc中常见错误的打印内容列表如下：
+
+ 
+
+| 错误码            | 数值   | 重试   | 说明                                       | 日志                                       |
+| -------------- | ---- | ---- | ---------------------------------------- | ---------------------------------------- |
+| EAGAIN         | 11   | 是    | 同时异步发送的请求过多。r32803前为硬限（<1024)，出现频率较高；r32803后为软限，很少出现。 | Resource temporarily unavailable         |
+| ETIMEDOUT      | 110  | 是    | 在r31711后代表连接超时。r31711前代表RPC超时，相当于ERPCTIMEDOUT。 | Connection timed out                     |
+| ENOSERVICE     | 1001 | 否    | 找不到服务，不太出现，一般会返回ENOMETHOD。               |                                          |
+| ENOMETHOD      | 1002 | 否    | 找不到方法。                                   | 形式广泛，常见如"Fail to find method=..."        |
+| EREQUEST       | 1003 | 否    | request格式或序列化错误，client端和server端都可能设置     | 形式广泛："Missing required fields in request: ...""Fail to parse request message, ...""Bad request" |
+| EAUTH          | 1004 | 否    | 认证失败                                     | "Authentication failed"                  |
+| ETOOMANYFAILS  | 1005 | 否    | ParallelChannel中太多子channel失败             | "%d/%d channels failed, fail_limit=%d"   |
+| EBACKUPREQUEST | 1007 | 是    | 触发backup request时设置，用户一般在/rpcz里看到        | “reached backup timeout=%dms"            |
+| ERPCTIMEDOUT   | 1008 | 否    | RPC超时                                    | "reached timeout=%dms"                   |
+| EFAILEDSOCKET  | 1009 | 是    | RPC进行过程中TCP连接出现问题                        | "The socket was SetFailed"               |
+| EHTTP          | 1010 | 否    | `r31923后失败的HTTP访问（非2xx状态码）均使用这个错误码。默认不重试，可通过RetryPolicy定制` | Bad http call                            |
+| EOVERCROWDED   | 1011 | 是    | 连接上有过多的未发送数据，一般是由于同时发起了过多的异步访问。可通过参数-socket_max_unwritten_bytes控制，默认8MB。 | The server is overcrowded                |
+| EINTERNAL      | 2001 | 否    | Server端Controller.SetFailed没有指定错误码时使用的默认错误码。 | "Internal Server Error"                  |
+| ERESPONSE      | 2002 | 否    | response解析或格式错误，client端和server端都可能设置     | 形式广泛"Missing required fields in response: ...""Fail to parse response message, ""Bad response" |
+| ELOGOFF        | 2003 | 是    | Server已经被Stop了                           | "Server is going to quit"                |
+| ELIMIT         | 2004 | 是    | 同时处理的请求数超过ServerOptions.max_concurrency了 | "Reached server's limit=%d on concurrent requests", |
+
+# 自定义错误码
+
+在C++/C中你可以通过宏、常量、protobuf enum等方式定义ErrorCode:
+```c++
+#define ESTOP -114                // C/C++
+static const int EMYERROR = 30;   // C/C++
+const int EMYERROR2 = -31;        // C++ only
+```
+如果你需要用berror返回这些新错误码的描述，你可以在.cpp或.c文件的全局域中调用BAIDU_REGISTER_ERRNO(error_code, description)进行注册，比如：
+```c++
+BAIDU_REGISTER_ERRNO(ESTOP, "the thread is stopping")
+BAIDU_REGISTER_ERRNO(EMYERROR, "my error")
+```
+strerror/strerror_r不认识使用BAIDU_REGISTER_ERRNO定义的错误码，自然地，printf类的函数中的%m也不能转化为对应的描述，你必须使用%s并配以berror()。
+```c++
+errno = ESTOP;
+printf("Describe errno: %m\n");                               // [Wrong] Describe errno: Unknown error -114
+printf("Describe errno: %s\n", strerror_r(errno, NULL, 0));   // [Wrong] Describe errno: Unknown error -114
+printf("Describe errno: %s\n", berror());                     // [Correct] Describe errno: the thread is stopping
+printf("Describe errno: %s\n", berror(errno));                // [Correct] Describe errno: the thread is stopping
+```
+当同一个error code被重复注册时，如果都是在C++中定义的，那么会出现链接错误：
+
+```
+redefinition of `class BaiduErrnoHelper<30>'
+```
+否则在程序启动时会abort：
+```
+Fail to define EMYERROR(30) which is already defined as `Read-only file system', abort
+```
+
+总的来说这和RPC框架没什么关系，直到你希望通过RPC框架传递ErrorCode。这个需求很自然，不过你得确保不同的模块对ErrorCode的理解是相同的，否则当两个模块把一个错误码理解为不同的错误时，它们之间的交互将出现无法预计的行为。为了防止这种情况出现，你最好这么做：
+- 优先使用系统错误码，它们的值和含义是固定不变的。
+- 多个交互的模块使用同一份错误码定义，防止后续修改时产生不一致。
+- 使用BAIDU_REGISTER_ERRNO描述新错误码，以确保同一个进程内错误码是互斥的。 

docs/cn/flags.md

+brpc使用gflags管理配置。如果你的程序也使用gflags，那么你应该已经可以修改和brpc相关的flags，你可以浏览[flags服务](http://brpc.baidu.com:8765/flags)了解每个flag的具体功能。如果你的程序还没有使用gflags，我们建议你使用，原因如下：
+
+- 命令行和文件均可传入，前者方便做测试，后者适合线上运维。放在文件中的gflags可以reload。而configure只支持从文件读取配置。
+- 你可以在浏览器中查看brpc服务器中所有gflags，并对其动态修改（如果允许的话）。configure不可能做到这点。
+- gflags分散在和其作用紧密关联的文件中，更好管理。而使用configure需要聚集到一个庞大的读取函数中。
+
+# Usage of gflags
+
+gflags一般定义在需要它的源文件中。#include <gflags/gflags.h>后在全局scope加入DEFINE_*<type>*(*<name>*, *<default-value>*, *<description>*); 比如：
+
+```c++
+#include <gflags/gflags.h>
+...
+DEFINE_bool(hex_log_id, false, "Show log_id in hexadecimal");
+DEFINE_int32(health_check_interval, 3, "seconds between consecutive health-checkings");
+```
+
+一般在main函数开头用ParseCommandLineFlags处理程序参数：
+
+```c++
+#include <gflags/gflags.h>
+...
+int main(int argc, char* argv[]) {
+    google::ParseCommandLineFlags(&argc, &argv, true/*表示把识别的参数从argc/argv中删除*/);
+    ...
+}
+```
+
+如果要从conf/gflags.conf中加载gflags，则可以加上参数-flagfile=conf/gflags.conf。如果希望默认（什么参数都不加）就从文件中读取，则可以在程序中直接给flagfile赋值，一般这么写
+
+```c++
+google::SetCommandLineOption("flagfile", "conf/gflags.conf");
+```
+
+程序启动时会检查conf/gflags.conf是否存在，如果不存在则会报错：
+
+```
+$ ./my_program
+conf/gflags.conf: No such file or directory
+```
+
+更具体的使用指南请阅读[官方文档](http://gflags.github.io/gflags/)。
+
+# flagfile
+
+在命令行中参数和值之间可不加等号，而在flagfile中一定要加。比如`./myapp -param 7`是ok的，但在`./myapp -flagfile=./gflags.conf`对应的gflags.conf中一定要写成**-param=7**或**--param=7**，否则就不正确且不会报错。
+
+在命令行中字符串可用单引号或双引号包围，而在flagfile中不能加。比如`./myapp -name="tom"`或`./myapp -name='tom'`都是ok的，但在`./myapp -flagfile=./gflags.conf`对应的gflags.conf中一定要写成**-name=tom**或**--name=tom**，如果写成-name="tom"的话，引号也会作为值的一部分。配置文件中的值可以有空格，比如gflags.conf中写成-name=value with spaces是ok的，参数name的值就是value with spaces，而在命令行中要用引号括起来。
+
+flagfile中参数可由单横线(如-foo)或双横线(如--foo)打头，但不能以三横线或更多横线打头，否则的话是无效参数且不会报错!
+
+flagfile中以`#开头的行被认为是注释。开头的空格和空白行都会被忽略。`
+
+flagfile中可以使用`--flagfile包含另一个flagfile。`
+
+# Change gflag on-the-fly
+
+[flags服务](http://brpc.baidu.com:8765/flags)可以查看服务器进程中所有的gflags。修改过的flags会以红色高亮。“修改过”指的是修改这一行为，即使再改回默认值，仍然会显示为红色。
+
+/flags：列出所有的gflags
+
+/flags/NAME：查询名字为NAME的gflag
+
+/flags/NAME1,NAME2,NAME3：查询名字为NAME1或NAME2或NAME3的gflag
+
+/flags/foo*,b$r：查询名字与某一统配符匹配的gflag，注意用$代替?匹配单个字符，因为?在url中有特殊含义。
+
+访问/flags/NAME?setvalue=VALUE即可动态修改一个gflag的值，validator会被调用。
+
+为了防止误修改，需要动态修改的gflag必须有validator，显示此类gflag名字时有(R)后缀。
+
+![img](../images/reloadable_flags.png)
+
+*修改成功后会显示如下信息*：
+
+![img](../images/flag_setvalue.png)
+
+*尝试修改不允许修改的gflag会显示如下错误信息*：
+
+![img](../images/set_flag_reject.png)
+
+*设置一个不允许的值会显示如下错误（flag值不会变化）*：
+
+![img](../images/set_flag_invalid_value.png)
+
+ 
+
+r31658之后支持可视化地修改，在浏览器上访问时将看到(R)下多了下划线：
+
+![img](../images/the_r_after_flag.png)
+
+点击后在一个独立页面可视化地修改对应的flag：
+
+![img](../images/set_flag_with_form.png)
+
+填入true后确定：
+
+![img](../images/set_flag_with_form_2.png)
+
+返回/flags可以看到对应的flag已经被修改了：
+
+![img](../images/set_flag_with_form_3.png)
+
+ 
+
+关于重载gflags，重点关注：
+
+- 避免在一段代码中多次调用同一个gflag，应把该gflag的值保存下来并调用该值。因为gflag的值随时可能变化，而产生意想不到的结果。
+- 使用google::GetCommandLineOption()访问string类型的gflag，直接访问是线程不安全的。
+- 处理逻辑和副作用应放到validator里去。比如修改FLAGS_foo后得更新另一处的值，如果只是写在程序初始化的地方，而不是validator里，那么重载时这段逻辑就运行不到了。
+
+如果你确认某个gflag不需要额外的线程同步和处理逻辑就可以重载，那么可以用如下方式为其注册一个总是返回true的validator：
+
+```c++
+DEFINE_bool(hex_log_id, false, "Show log_id in hexadecimal");
+BAIDU_RPC_VALIDATE_GFLAG(hex_log_id, brpc::PassValidate/*always true*/);
+```
+
+这个flag是单纯的开关，修改后不需要更新其他数据（没有处理逻辑），代码中前面看到true后面看到false也不会产生什么后果（不需要线程同步），所以我们让其默认可重载。
+
+对于int32和int64类型，有一个判断是否为正数的常用validator：
+
+```c++
+DEFINE_int32(health_check_interval, 3, "seconds between consecutive health-checkings");
+BAIDU_RPC_VALIDATE_GFLAG(health_check_interval, brpc::PositiveInteger);
+```
+
+以上操作都可以在命令行中进行：
+
+```shell
+$ curl brpc.baidu.com:8765/flags/health_check_interval
+Name | Value | Description | Defined At
+---------------------------------------
+health_check_interval (R) | 3 | seconds between consecutive health-checkings | src/brpc/socket_map.cpp
+```
+
+1.0.251.32399后增加了-immutable_flags，打开后所有的gflags将不能被动态修改。当一个服务对某个gflag值比较敏感且不希望在线上被误改，可打开这个开关。打开这个开关的同时也意味着你无法动态修改线上的配置，每次修改都要重启程序，对于还在调试阶段或待收敛阶段的程序不建议打开。

docs/cn/getting_started.md

+# BUILD
+
+brpc prefers static linking if possible, so that deps don't have to be installed on every
+machine running the code. 
+
+## Ubuntu/LinuxMint/WSL
+### compile
+1. install common deps: git g++ make libssl-dev
+2. install gflags protobuf leveldb: libgflags-dev libprotobuf-dev libprotoc-dev protobuf-compiler libleveldb-dev. If you need to statically link leveldb, install libsnappy-dev as well.
+3. git clone this repo. cd into the repo and run
+```
+$ sh config_brpc.sh --headers=/usr/include --libs=/usr/lib
+```
+4. make
+
+### run example
+```
+$ cd example/echo_c++
+$ make
+$ ./echo_server &
+$ ./echo_client
+```
+
+### run examples with cpu/heap profilers
+Install libgoogle-perftools-dev and re-run config_brpc.sh before compiling
+
+### compile tests
+Install gmock and gtest, use the gtest embedded in gmock and don't install libgtest-dev
+```
+$ sudo apt-get install google-mock
+$ cd /usr/src
+$ sudo cmake .
+$ sudo make
+$ sudo mv lib*.a gtest/lib*.a /usr/lib
+$ sudo mv gtest/include/gtest /usr/include/
+```
+Rerun config_brpc.sh and run make in test/
+
+# Supported deps
+
+## GCC: 4.8-7.1
+
+c++11 is  turned on by default to remove dependency on boost (atomic).
+
+The over-aligned issues in GCC7 is suppressed temporarily now.
+
+Using other versions of gcc may generate warnings, contact us to fix.
+
+Adding `-D__const__=` to cxxflags in your makefiles is a must avoid [errno issue in gcc4+](thread_local.md)。
+
+## Clang: 3.5-4.0
+
+unittests can't be compiled with clang yet.
+
+## glibc: 2.12-2.25
+
+no known issues.
+
+## protobuf: 2.4-3.2
+
+Be compatible with pb 3.0 and pb 2.x with the same file: 
+Don't use new types in proto3 and start the proto file with `syntax="proto2";`
+[tools/add_syntax_equal_proto2_to_all.sh](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/tools/add_syntax_equal_proto2_to_all.sh)can add `syntax="proto2"` to all proto files without it.
+protobuf 3.3-3.4 is not tested yet.
+
+## gflags: 2.0-2.21
+
+no known issues.
+
+## openssl: 0.97-1.1
+
+required by https.
+
+## tcmalloc: 1.7-2.5
+
+brpc does **not** link [tcmalloc](http://goog-perftools.sourceforge.net/doc/tcmalloc.html) by default. Users link tcmalloc on-demand.
+
+Comparing to ptmalloc embedded in glibc, tcmalloc often improves performance. However different versions of tcmalloc may behave really differently. For example, tcmalloc 2.1 may make multi-threaded examples in brpc perform significantly worse(due to a spinlock in tcmalloc) than the one using tcmalloc 1.7 and 2.5. Even different minor versions may differ. When you program behave unexpectedly, remove tcmalloc or try another version.
+
+Code compiled with gcc 4.8.2 when linking to a tcmalloc compiled with earlier GCC may crash or deadlock before main(), E.g:
+
+![img](../images/tcmalloc_stuck.png)
+
+When you meet the issue, compile tcmalloc with the same GCC as the RPC code.
+
+Another common issue with tcmalloc is that it does not return memory to system as early as ptmalloc. So when there's an invalid memory access, the program may not crash directly,  instead it crashes at a unrelated place, or even not crash. When you program has weird memory issues, try removing tcmalloc.
+
+If you want to use [cpu profiler](cpu_profiler.md) or [heap profiler](heap_profiler.md), do link `libtcmalloc_and_profiler.a`. These two profilers are based on tcmalloc.[contention profiler](contention_profiler.md) does not require tcmalloc.
+
+When you remove tcmalloc, not only remove the linking with tcmalloc but also the macros: `-DBRPC_ENABLE_CPU_PROFILER` and `-DBRPC_ENABLE_HEAP_PROFILER`.
+
+## valgrind: 3.8+
+
+brpc detects valgrind automatically (and registers stacks of bthread). Older valgrind (say 3.2) is not supported.
+
+# Track instances
+
+We provide a program to help you to track and monitor all brpc instances. Just run [trackme_server](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/tree/tools/trackme_server/) somewhere and launch need-to-be-tracked instances with -trackme_server=SERVER. The trackme_server will receive pings from instances periodically and print logs when it does. You can aggregate instance addresses from the log and call builtin services of the instances for further information.

docs/cn/heap_profiler.md

+brpc可以分析内存是被哪些函数占据的。heap profiler的原理是每分配满一些内存就采样调用处的栈，“一些”由环境变量TCMALLOC_SAMPLE_PARAMETER控制，默认524288，即512K字节。根据栈表现出的函数调用关系汇总为我们看到的结果图。在实践中heap profiler对原程序的影响不明显。
+
+# 开启方法
+
+1. 链接`libtcmalloc_and_profiler.a`
+
+   1. 如果tcmalloc使用frame pointer而不是libunwind回溯栈，请确保在CXXFLAGS或CFLAGS中加上`-fno-omit-frame-pointer`，否则函数间的调用关系会丢失，最后产生的图片中都是彼此独立的函数方框。
+
+2. 定义宏BRPC_ENABLE_HEAP_PROFILER, 一般加入编译参数-DBRPC_ENABLE_HEAP_PROFILER。
+
+3. 在shell中`export TCMALLOC_SAMPLE_PARAMETER=524288`。该变量指每分配这么多字节内存时做一次统计，默认为0，代表不开启内存统计。[官方文档](http://goog-perftools.sourceforge.net/doc/tcmalloc.html)建议设置为524288。这个变量也可在运行前临时设置，如`TCMALLOC_SAMPLE_PARAMETER=524288 ./server`。如果没有这个环境变量，可能会看到这样的结果：
+
+   ```
+   $ tools/pprof --text localhost:9002/pprof/heap           
+   Fetching /pprof/heap profile from http://localhost:9002/pprof/heap to
+     /home/gejun/pprof/echo_server.1419559063.localhost.pprof.heap
+   Wrote profile to /home/gejun/pprof/echo_server.1419559063.localhost.pprof.heap
+   /home/gejun/pprof/echo_server.1419559063.localhost.pprof.heap: header size >= 2**16
+   ```
+
+4. 如果只是brpc client或没有使用brpc，看[这里](dummy_server.md)。 
+
+注意要关闭Server端的认证，否则可能会看到这个：
+
+```
+$ tools/pprof --text localhost:9002/pprof/heap
+Use of uninitialized value in substitution (s///) at tools/pprof line 2703.
+http://localhost:9002/pprof/symbol doesn't exist
+```
+
+server端可能会有这样的日志：
+
+```
+FATAL: 12-26 10:01:25:   * 0 [src/brpc/policy/giano_authenticator.cpp:65][4294969345] Giano fails to verify credentical, 70003
+WARNING: 12-26 10:01:25:   * 0 [src/brpc/input_messenger.cpp:132][4294969345] Authentication failed, remote side(127.0.0.1:22989) of sockfd=5, close it
+```
+
+# 图示
+
+![img](../images/heap_profiler_1.png)
+
+左上角是当前程序通过malloc分配的内存总量，顺着箭头上的数字可以看到内存来自哪些函数。
+
+点击左上角的text选择框可以查看文本格式的结果，有时候这种按分配量排序的形式更方便。
+
+![img](../images/heap_profiler_2.png)
+
+左上角的两个选择框作用分别是：
+
+- 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）在命令行中查看文本格式结果：
+
+```
+$ tools/pprof --text db-rpc-dev00.db01:8765/pprof/heap    
+Fetching /pprof/heap profile from http://db-rpc-dev00.db01:8765/pprof/heap to
+  /home/gejun/pprof/play_server.1453216025.db-rpc-dev00.db01.pprof.heap
+Wrote profile to /home/gejun/pprof/play_server.1453216025.db-rpc-dev00.db01.pprof.heap
+Adjusting heap profiles for 1-in-524288 sampling rate
+Heap version 2
+Total: 38.9 MB
+    35.8  92.0%  92.0%     35.8  92.0% ::cpp_alloc
+     2.1   5.4%  97.4%      2.1   5.4% butil::FlatMap
+     0.5   1.3%  98.7%      0.5   1.3% butil::IOBuf::append
+     0.5   1.3% 100.0%      0.5   1.3% butil::IOBufAsZeroCopyOutputStream::Next
+     0.0   0.0% 100.0%      0.6   1.5% MallocExtension::GetHeapSample
+     0.0   0.0% 100.0%      0.5   1.3% ProfileHandler::Init
+     0.0   0.0% 100.0%      0.5   1.3% ProfileHandlerRegisterCallback
+     0.0   0.0% 100.0%      0.5   1.3% __do_global_ctors_aux
+     0.0   0.0% 100.0%      1.6   4.2% _end
+     0.0   0.0% 100.0%      0.5   1.3% _init
+     0.0   0.0% 100.0%      0.6   1.5% brpc::CloseIdleConnections
+     0.0   0.0% 100.0%      1.1   2.9% brpc::GlobalUpdate
+     0.0   0.0% 100.0%      0.6   1.5% brpc::PProfService::heap
+     0.0   0.0% 100.0%      1.9   4.9% brpc::Socket::Create
+     0.0   0.0% 100.0%      2.9   7.4% brpc::Socket::Write
+     0.0   0.0% 100.0%      3.8   9.7% brpc::Span::CreateServerSpan
+     0.0   0.0% 100.0%      1.4   3.5% brpc::SpanQueue::Push
+     0.0   0.0% 100.0%      1.9   4.8% butil::ObjectPool
+     0.0   0.0% 100.0%      0.8   2.0% butil::ResourcePool
+     0.0   0.0% 100.0%      1.0   2.6% butil::iobuf::tls_block
+     0.0   0.0% 100.0%      1.0   2.6% bthread::TimerThread::Bucket::schedule
+     0.0   0.0% 100.0%      1.6   4.1% bthread::get_stack
+     0.0   0.0% 100.0%      4.2  10.8% bthread_id_create
+     0.0   0.0% 100.0%      1.1   2.9% bvar::Variable::describe_series_exposed
+     0.0   0.0% 100.0%      1.0   2.6% bvar::detail::AgentGroup
+     0.0   0.0% 100.0%      0.5   1.3% bvar::detail::Percentile::operator
+     0.0   0.0% 100.0%      0.5   1.3% bvar::detail::PercentileSamples
+     0.0   0.0% 100.0%      0.5   1.3% bvar::detail::Sampler::schedule
+     0.0   0.0% 100.0%      6.5  16.8% leveldb::Arena::AllocateNewBlock
+     0.0   0.0% 100.0%      0.5   1.3% leveldb::VersionSet::LogAndApply
+     0.0   0.0% 100.0%      4.2  10.8% pthread_mutex_unlock
+     0.0   0.0% 100.0%      0.5   1.3% pthread_once
+     0.0   0.0% 100.0%      0.5   1.3% std::_Rb_tree
+     0.0   0.0% 100.0%      1.5   3.9% std::basic_string
+     0.0   0.0% 100.0%      3.5   9.0% std::string::_Rep::_S_create
+```
+
+brpc还提供一个类似的growth profiler分析内存的分配去向（不考虑释放）。 
+
+![img](../images/growth_profiler.png)
+

docs/cn/io.md

+一般有三种操作IO的方式：
+
+- blocking IO: 发起IO操作后阻塞当前线程直到IO结束，标准的同步IO，如默认行为的posix [read](http://linux.die.net/man/2/read)和[write](http://linux.die.net/man/2/write)。
+- non-blocking IO: 发起IO操作后不阻塞，用户可阻塞等待多个IO操作同时结束。non-blocking也是一种同步IO：“批量的同步”。如linux下的[poll](http://linux.die.net/man/2/poll),[select](http://linux.die.net/man/2/select), [epoll](http://linux.die.net/man/4/epoll)，BSD下的[kqueue](https://www.freebsd.org/cgi/man.cgi?query=kqueue&sektion=2)。
+- asynchronous IO: 发起IO操作后不阻塞，用户得递一个回调待IO结束后被调用。如windows下的[OVERLAPPED](https://msdn.microsoft.com/en-us/library/windows/desktop/ms684342(v=vs.85).aspx) + [IOCP](https://msdn.microsoft.com/en-us/library/windows/desktop/aa365198(v=vs.85).aspx)。linux的native AIO只对文件有效。
+
+linux一般使用non-blocking IO提高IO并发度。当IO并发度很低时，non-blocking IO不一定比blocking IO更高效，因为后者完全由内核负责，而read/write这类系统调用已高度优化，效率显然高于一般得多个线程协作的non-blocking IO。但当IO并发度愈发提高时，blocking IO阻塞一个线程的弊端便显露出来：内核得不停地在线程间切换才能完成有效的工作，一个cpu core上可能只做了一点点事情，就马上又换成了另一个线程，cpu cache没得到充分利用，另外大量的线程会使得依赖thread-local加速的代码性能明显下降，如tcmalloc，一旦malloc变慢，程序整体性能往往也会随之下降。而non-blocking IO一般由少量event dispatching线程和一些运行用户逻辑的worker线程组成，这些线程往往会被复用（换句话说调度工作转移到了用户态），event dispatching和worker可以同时在不同的核运行（流水线化），内核不用频繁的切换就能完成有效的工作。线程总量也不用很多，所以对thread-local的使用也比较充分。这时候non-blocking IO就往往比blocking IO快了。不过non-blocking IO也有自己的问题，它需要调用更多系统调用，比如[epoll_ctl](http://man7.org/linux/man-pages/man2/epoll_ctl.2.html)，由于epoll实现为一棵红黑树，epoll_ctl并不是一个很快的操作，特别在多核环境下，依赖epoll_ctl的实现往往会面临棘手的扩展性问题。non-blocking需要更大的缓冲，否则就会触发更多的事件而影响效率。non-blocking还得解决不少多线程问题，代码比blocking复杂很多。
+
+# 收消息
+
+“消息”指从连接读入的有边界的二进制串，可能是来自上游client的request或来自下游server的response。brpc使用一个或多个[EventDispatcher](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/event_dispatcher.h)(简称为EDISP)等待任一fd发生事件。和常见的“IO线程”不同，EDISP不负责读取。IO线程的问题在于一个线程同时只能读一个fd，当多个繁忙的fd聚集在一个IO线程中时，一些读取就被延迟了。多租户、复杂分流算法，[Streaming RPC](streaming_rpc.md)等功能会加重这个问题。高负载下偶尔的长延时read也会拖慢一个IO线程中所有fd的读取，对可用性的影响幅度较大。
+
+由于epoll的[一个bug](https://patchwork.kernel.org/patch/1970231/)及epoll_ctl较大的开销，EDISP使用Edge triggered模式。当收到事件时，EDISP给一个原子变量加1，只有当加1前的值是0时启动一个bthread处理对应fd上的数据。在背后，EDISP把所在的pthread让给了新建的bthread，使其有更好的cache locality，可以尽快地读取fd上的数据。而EDISP所在的bthread会被偷到另外一个pthread继续执行，这个过程即是bthread的work stealing调度。要准确理解那个原子变量的工作方式可以先阅读[atomic instructions](atomic_instructions.md)，再看[Socket::StartInputEvent](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/socket.cpp)。这些方法使得brpc读取同一个fd时产生的竞争是[wait-free](http://en.wikipedia.org/wiki/Non-blocking_algorithm#Wait-freedom)的。
+
+[InputMessenger](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/input_messenger.h)负责从fd上切割和处理消息，它通过用户回调函数理解不同的格式。Parse一般是把消息从二进制流上切割下来，运行时间较固定；Process则是进一步解析消息(比如反序列化为protobuf)后调用用户回调，时间不确定。InputMessenger会逐一尝试用户指定的多套回调，当某一个Parse成功切割下一个消息后，调用对应的Process。由于一个连接上往往只有一种消息格式，InputMessenger会记录下上次的选择，而避免每次都重复尝试。若一次从某个fd读取出n个消息(n > 1)，InputMessenger会启动n-1个bthread分别处理前n-1个消息，最后一个消息则会在原地被Process。
+
+可以看到，fd间和fd内的消息都会在brpc中获得并发，这使brpc非常擅长大消息的读取，在高负载时仍能及时处理不同来源的消息，减少长尾的存在。
+
+# 发消息
+
+"消息”指向连接写出的有边界的二进制串，可能是发向上游client的response或下游server的request。多个线程可能会同时向一个fd发送消息，而写fd又是非原子的，所以如何高效率地排队不同线程写出的数据包是这里的关键。brpc使用一种wait-free MPSC链表来实现这个功能。所有待写出的数据都放在一个单链表节点中，next指针初始化为一个特殊值(Socket::WriteRequest::UNCONNECTED)。当一个线程想写出数据前，它先尝试和对应的链表头(Socket::_write_head)做原子交换，返回值是交换前的链表头。如果返回值为空，说明它获得了写出的权利，它会在原地写一次数据。否则说明有另一个线程在写，它把next指针指向返回的头，那样正在写的线程之后会看到并写出这块数据。这套方法可以让写竞争是wait-free的，而获得写权利的线程虽然在原理上不是wait-free也不是lock-free，可能会被一个值仍为UNCONNECTED的节点锁定（这需要发起写的线程正好在原子交换后，在设置next指针前，仅仅一条指令的时间内被OS换出），但在实践中很少出现。在当前的实现中，如果获得写权利的线程一下子无法写出所有的数据，会启动一个KeepWrite线程继续写，直到所有的数据都被写出。这套逻辑非常复杂，大致原理如下图，细节请阅读[socket.cpp](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/socket.cpp)。
+
+![img](../images/write.png)
+
+由于brpc的写出总能很快地返回，调用线程可以更快地处理新任务，后台写线程也能每次拿到一批任务批量写出，在大吞吐时容易形成流水线效应而提高IO效率。
+
+# Socket
+
+和fd相关的数据均在[Socket](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/socket.h)中，是rpc最复杂的结构之一，这个结构的独特之处在于用64位的SocketId指代Socket对象以方便在多线程环境下使用fd。常用的三个方法：
+
+- Create：创建Socket，并返回其SocketId。
+- Address：取得id对应的Socket，包装在一个会自动释放的unique_ptr中(SocketUniquePtr)，当Socket被SetFailed后，返回指针为空。只要Address返回了非空指针，其内容保证不会变化，直到指针自动析构。这个函数是wait-free的。
+- SetFailed：标记一个Socket为失败，之后所有对那个SocketId的Address会返回空指针（直到健康检查成功）。当Socket对象没人使用后会被回收。这个函数是lock-free的。
+
+可以看到Socket类似[shared_ptr](http://en.cppreference.com/w/cpp/memory/shared_ptr)，SocketId类似[weak_ptr](http://en.cppreference.com/w/cpp/memory/weak_ptr)，但Socket独有的SetFailed可以在需要时确保Socket不能被继续Address而最终引用计数归0，单纯使用shared_ptr/weak_ptr则无法保证这点，当一个server需要退出时，如果请求仍频繁地到来，对应Socket的引用计数可能迟迟无法清0而导致server无法退出。另外weak_ptr无法直接作为epoll的data，而SocketId可以。这些因素使我们设计了Socket，这个类的核心部分自14年10月完成后很少改动，非常稳定。
+
+存储SocketUniquePtr还是SocketId取决于是否需要强引用。像Controller贯穿了RPC的整个流程，和Socket中的数据有大量交互，它存放的是SocketUniquePtr。epoll主要是提醒对应fd上发生了事件，如果Socket回收了，那这个事件是可有可无的，所以它存放了SocketId。由于SocketUniquePtr只要有效，其中的数据就不会变，这个机制使用户不用关心麻烦的race conditon和ABA problem，可以放心地对共享的fd进行操作。这种方法也规避了隐式的引用计数，内存的ownership明确，程序的质量有很好的保证。brpc中有大量的SocketUniquePtr和SocketId，它们确实简化了我们的开发。
+
+事实上，Socket不仅仅用于管理原生的fd，它也被用来管理其他资源。比如SelectiveChannel中的每个Sub Channel都被置入了一个Socket中，这样SelectiveChannel可以像普通channel选择下游server那样选择一个Sub Channel进行发送。这个假Socket甚至还实现了健康检查。Streaming RPC也使用了Socket以复用wait-free的写出过程。
+
+# The full picture
+
+![img](../images/rpc_flow.png)

docs/cn/iobuf.md

+brpc使用[butil::IOBuf](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/butil/iobuf.h)作为存储附件或http body的数据结构，它是一种非连续零拷贝缓冲，在其他项目中得到了验证并有出色的性能。IOBuf的接口和std::string类似，但不相同。
+
+如果你之前使用Kylin中的BufHandle，你将更能感受到IOBuf的便利性：前者几乎没有实现完整，直接暴露了内部结构，用户得小心翼翼地处理引用计数，极易出错。BufHandle是很多bug的诱因。
+
+# IOBuf能做的：
+
+- 默认构造不分配内存。
+- 可以拷贝，修改拷贝不影响原IOBuf。拷贝的是IOBuf的管理结构而不是数据。
+- 可以append另一个IOBuf，不拷贝数据。
+- 可以append字符串，拷贝数据。
+- 可以从fd读取，可以写入fd。
+- 可以和protobuf相互转化。
+- IOBufBuilder可以把IOBuf当std::ostream用。
+
+# IOBuf不能做的：
+
+- 程序内的通用存储结构。IOBuf应保持较短的生命周期，以避免一个IOBuf锁定了多个block (8K each)。
+
+# 切割
+
+切下16字节的IOBuf：
+
+```c++
+source_buf.cut(&heading_iobuf, 16); // 当source_buf不足16字节时，切掉所有字节。
+```
+
+跳过16字节：
+
+```c++
+source_buf.pop_front(16); // 当source_buf不足16字节时，清空它
+```
+
+# 拼接
+
+append另一个IOBuf：
+
+```c++
+buf.append(another_buf);  // no data copy
+```
+
+append std::string
+
+```c++
+buf.append(str);  // copy data of str into buf
+```
+
+# 解析
+
+解析IOBuf为protobuf
+
+```c++
+IOBufAsZeroCopyInputStream wrapper(&iobuf);
+pb_message.ParseFromZeroCopyStream(&wrapper);
+```
+
+解析IOBuf为自定义结构
+
+```c++
+IOBufAsZeroCopyInputStream wrapper(&iobuf);
+CodedInputStream coded_stream(&wrapper);
+coded_stream.ReadLittleEndian32(&value);
+...
+```
+
+# 序列化
+
+protobuf序列化为IOBuf
+
+```c++
+IOBufAsZeroCopyOutputStream wrapper(&iobuf);
+pb_message.SerializeToZeroCopyStream(&wrapper);
+```
+
+把可打印数据送入IOBuf
+
+```c++
+IOBufBuilder os;
+os << "anything can be sent to std::ostream";
+os.buf();  // IOBuf
+```
+
+# 打印
+
+```c++
+std::cout << iobuf;
+std::string str = iobuf.to_string();
+```
+
+# 性能
+
+IOBuf有很高的综合性能：
+
+- 从文件读入->切割12+16字节->拷贝->合并到另一个缓冲->写出到/dev/null这一流程的吞吐是240.423MB/s或8586535次/s
+- 从文件读入->切割12+128字节->拷贝->合并到另一个缓冲->写出到/dev/null这一流程的吞吐是790.022MB/s或5643014次/s
+- 从文件读入->切割12+1024字节->拷贝->合并到另一个缓冲->写出到/dev/null这一流程的吞吐是1519.99MB/s或1467171次/s

docs/cn/load_balancing.md

+上游一般通过名字服务发现所有的下游节点，并通过多种负载均衡方法把流量分配给下游节点。当下游节点出现问题时，它可能会被隔离以提高负载均衡的效率。被隔离的节点定期被健康检查，成功后重新加入正常节点。
+
+# 名字服务
+
+在brpc中，[NamingService](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/naming_service.h)用于获得服务名对应的所有节点。一个直观的做法是定期调用一个函数以获取最新的节点列表。但这会带来一定的延时（定期调用的周期一般在若干秒左右），作为通用接口不太合适。特别当名字服务提供事件通知时(比如zk)，这个特性没有被利用。所以我们反转了控制权：不是我们调用用户函数，而是用户在获得列表后调用我们的接口，对应[NamingServiceActions](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/naming_service.h)。当然我们还是得启动进行这一过程的函数，对应NamingService::RunNamingService。下面以三个实现解释这套方式：
+
+- bns：没有事件通知，所以我们只能定期去获得最新列表，默认间隔是[5秒](http://brpc.baidu.com:8765/flags/ns_access_interval)。为了简化这类定期获取的逻辑，brpc提供了[PeriodicNamingService](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/periodic_naming_service.h) 供用户继承，用户只需要实现单次如何获取（GetServers）。获取后调用NamingServiceActions::ResetServers告诉框架。框架会对列表去重，和之前的列表比较，通知对列表有兴趣的观察者(NamingServiceWatcher)。这套逻辑会运行在独立的bthread中，即NamingServiceThread。一个NamingServiceThread可能被多个Channel共享，通过intrusive_ptr管理ownership。
+- file：列表即文件。合理的方式是在文件更新后重新读取。[该实现](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/policy/file_naming_service.cpp)使用[FileWatcher](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/butil/files/file_watcher.h)关注文件的修改时间，当文件修改后，读取并调用NamingServiceActions::ResetServers告诉框架。
+- list：列表就在服务名里（逗号分隔）。在读取完一次并调用NamingServiceActions::ResetServers后就退出了，因为列表再不会改变了。
+
+如果用户需要建立这些对象仍然是不够方便的，因为总是需要一些工厂代码根据配置项建立不同的对象，鉴于此，我们把工厂类做进了框架，并且是非常方便的形式：
+
+```
+"protocol://service-name"
+ 
+e.g.
+bns://<node-name>            # baidu naming service
+file://<file-path>           # load addresses from the file
+list://addr1,addr2,...       # use the addresses separated by comma
+http://<url>                 # Domain Naming Service, aka DNS.
+```
+
+这套方式是可扩展的，实现了新的NamingService后在[global.cpp](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/global.cpp)中依葫芦画瓢注册下就行了，如下图所示：
+
+![img](../images/register_ns.png)
+
+看到这些熟悉的字符串格式，容易联想到ftp:// zk:// galileo://等等都是可以支持的。用户在新建Channel时传入这类NamingService描述，并能把这些描述写在各类配置文件中。
+
+# 负载均衡
+
+brpc中[LoadBalancer](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/brpc/load_balancer.h)从多个服务节点中选择一个节点，目前的实现见[负载均衡](client.md#负载均衡)。
+
+Load balancer最重要的是如何让不同线程中的负载均衡不互斥，解决这个问题的技术是[DoublyBufferedData](lalb.md#doublybuffereddata)。
+
+和NamingService类似，我们使用字符串来指代一个load balancer，在global.cpp中注册：
+
+![img](../images/register_lb.png)
+
+# 健康检查
+
+对于那些无法连接却仍在NamingService的节点，brpc会定期连接它们，成功后对应的Socket将被”复活“，并可能被LoadBalancer选择上，这个过程就是健康检查。注意：被健康检查或在LoadBalancer中的节点一定在NamingService中。换句话说，只要一个节点不从NamingService删除，它要么是正常的（会被LoadBalancer选上），要么在做健康检查。
+
+传统的做法是使用一个线程做所有连接的健康检查，brpc简化了这个过程：为需要的连接动态创建一个bthread专门做健康检查（Socket::HealthCheckThread）。这个线程的生命周期被对应连接管理。具体来说，当Socket被SetFailed后，健康检查线程就可能启动（如果SocketOptions.health_check_interval为正数的话）：
+
+- 健康检查线程先在确保没有其他人在使用Socket了后关闭连接。目前是通过对Socket的引用计数判断的。这个方法之所以有效在于Socket被SetFailed后就不能被Address了，所以引用计数只减不增。
+- 定期连接直到远端机器被连接上，在这个过程中，如果Socket析构了，那么该线程也就随之退出了。
+- 连上后复活Socket(Socket::Revive)，这样Socket就又能被其他地方，包括LoadBalancer访问到了（通过Socket::Address）。

docs/cn/memcache_client.md

+[memcached](http://memcached.org/)是常用的缓存服务，为了使用户更快捷地访问memcached并充分利用bthread的并发能力，brpc直接支持memcache协议。示例程序：[example/memcache_c++](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/tree/example/memcache_c++/)
+
+**注意**：brpc只支持memcache的二进制协议。memcached在1.3前只有文本协议，但在当前看来支持的意义甚微。如果你的memcached早于1.3，升级版本。
+
+相比使用[libmemcached](http://libmemcached.org/libMemcached.html)(官方client)的优势有：
+
+- 线程安全。用户不需要为每个线程建立独立的client。
+- 支持同步、异步、批量同步、批量异步等访问方式，能使用ParallelChannel等组合访问方式。
+- 有明确的request和response。而libmemcached是没有的，收到的消息不能直接和发出的消息对应上，用户需要自己做维护工作。
+- 支持多种[连接方式](client.md#连接方式)。支持超时、backup request、取消、tracing、内置服务等一系列RPC基本福利。
+
+当前实现充分利用了RPC的并发机制并尽量避免了拷贝。一个client可以轻松地把一个同机memcached实例(版本1.4.15)压到极限：单连接9万，多连接33万。在大部分情况下，brpc应该能充分发挥memcached的性能。
+
+# 访问单台memcached
+
+创建一个访问memcached的Channel：
+
+```c++
+#include <brpc/memcache.h>
+#include <brpc/channel.h>
+ 
+ChannelOptions options;
+options.protocol = brpc::PROTOCOL_MEMCACHE;
+if (channel.Init("0.0.0.0:11211", &options) != 0) {  // 11211是memcached的默认端口
+   LOG(FATAL) << "Fail to init channel to memcached";
+   return -1;
+}
+... 
+```
+
+往memcached中设置一份数据。
+
+```c++
+// 写入key="hello" value="world" flags=0xdeadbeef，10秒失效，无视cas。
+brpc::MemcacheRequest request;
+brpc::MemcacheResponse response;
+brpc::Controller cntl;
+if (!request.Set("hello", "world", 0xdeadbeef/*flags*/, 10/*expiring seconds*/, 0/*ignore cas*/)) {
+    LOG(FATAL) << "Fail to SET request";
+    return -1;
+} 
+channel.CallMethod(NULL, &cntl, &request, &response, NULL/*done*/);
+if (cntl.Failed()) {
+    LOG(FATAL) << "Fail to access memcached, " << cntl.ErrorText();
+    return -1;
+}  
+if (!response.PopSet(NULL)) {
+    LOG(FATAL) << "Fail to SET memcached, " << response.LastError();
+    return -1;   
+}
+...
+```
+
+上述的代码有如下注意点：
+
+- 请求类型必须为MemcacheRequest，回复类型必须为MemcacheResponse，否则CallMethod会失败。不需要stub，直接调用channel.CallMethod，method填NULL。
+- 调用request.XXX()增加操作，本例XXX=Set，一个request多次调用不同的操作，这些操作会被同时送到memcached（常被称为pipeline模式）。
+- 依次调用response.PopXXX()弹出操作结果，本例XXX=Set，成功返回true，失败返回false，调用response.LastError()可获得错误信息。XXX必须和request的依次对应，否则失败。本例中若用PopGet就会失败，错误信息为“not a GET response"。
+- Pop结果独立于RPC结果。即使Set失败，RPC可能还是成功的。RPC失败意味着连接断开，超时之类的。“不能把某个值设入memcached”对于RPC来说还是成功的。如果业务上认为要成功操作才算成功，那么你不仅要判RPC成功，还要判PopXXX是成功的。
+
+目前支持的请求操作有：
+
+```c++
+bool Set(const Slice& key, const Slice& value, uint32_t flags, uint32_t exptime, uint64_t cas_value);
+bool Add(const Slice& key, const Slice& value, uint32_t flags, uint32_t exptime, uint64_t cas_value);
+bool Replace(const Slice& key, const Slice& value, uint32_t flags, uint32_t exptime, uint64_t cas_value);
+bool Append(const Slice& key, const Slice& value, uint32_t flags, uint32_t exptime, uint64_t cas_value);
+bool Prepend(const Slice& key, const Slice& value, uint32_t flags, uint32_t exptime, uint64_t cas_value);
+bool Delete(const Slice& key);
+bool Flush(uint32_t timeout);
+bool Increment(const Slice& key, uint64_t delta, uint64_t initial_value, uint32_t exptime);
+bool Decrement(const Slice& key, uint64_t delta, uint64_t initial_value, uint32_t exptime);
+bool Touch(const Slice& key, uint32_t exptime);
+bool Version();
+```
+
+对应的回复操作：
+
+```c++
+// Call LastError() of the response to check the error text when any following operation fails.
+bool PopGet(IOBuf* value, uint32_t* flags, uint64_t* cas_value);
+bool PopGet(std::string* value, uint32_t* flags, uint64_t* cas_value);
+bool PopSet(uint64_t* cas_value);
+bool PopAdd(uint64_t* cas_value);
+bool PopReplace(uint64_t* cas_value);
+bool PopAppend(uint64_t* cas_value);
+bool PopPrepend(uint64_t* cas_value);
+bool PopDelete();
+bool PopFlush();
+bool PopIncrement(uint64_t* new_value, uint64_t* cas_value);
+bool PopDecrement(uint64_t* new_value, uint64_t* cas_value);
+bool PopTouch();
+bool PopVersion(std::string* version);
+```
+
+# 访问memcached集群
+
+建立一个使用c_md5负载均衡算法的channel，每个MemcacheRequest只包含一个操作或确保所有的操作始终落在同一台server，就能访问挂载在对应名字服务下的memcached集群了。如果request包含了多个操作，在当前实现下这些操作总会送向同一个server。比方说一个request中包含了多个Get操作，而对应的key分布在多个server上，那么结果就肯定不对了，这个情况下你必须把一个request分开为多个。
+
+或者你可以沿用常见的[twemproxy](https://github.com/twitter/twemproxy)方案。这个方案虽然需要额外部署proxy，还增加了延时，但client端仍可以像访问单点一样的访问它。

docs/cn/memory_management.md

+内存管理总是程序中的重要一环，在多线程时代，一个好的内存分配大都在如下两点间权衡：
+
+- 线程间竞争少。内存分配的粒度大都比较小，对性能敏感，如果不同的线程在大多数分配时会竞争同一份资源或同一把锁，性能将会非常糟糕，原因无外乎和cache一致性有关，已被大量的malloc方案证明。
+- 浪费的空间少。如果每个线程各申请各的，速度也许不错，但万一一个线程总是申请，另一个线程总是释放，内存就爆炸了。线程之间总是要共享内存的，如何共享就是方案的关键了。
+
+一般的应用可以使用[tcmalloc](http://goog-perftools.sourceforge.net/doc/tcmalloc.html)、[jemalloc](https://github.com/jemalloc/jemalloc)等成熟的内存分配方案，但这对于较为底层，关注性能长尾的应用是不够的。多线程框架广泛地通过传递对象的ownership来让问题异步化，如何让分配这些小对象的开销变的更小是值得研究的。其中的一个特点较为显著：
+
+- 大多数结构是等长的。
+
+这个属性可以大幅简化内存分配的过程，获得比通用malloc更稳定、快速的性能。brpc中的ResourcePool<T>和ObjectPool<T>即提供这类分配。
+
+> 这篇文章不鼓励用户使用ResourcePool<T>或ObjectPool<T>，事实上我们反对用户在程序中使用这两个类。因为”等长“的副作用是某个类型独占了一部分内存，这些内存无法再被其他类型使用，如果不加控制的滥用，反而会在程序中产生大量彼此隔离的内存分配体系，既浪费内存也不见得会有更好的性能。
+
+# ResourcePool<T>
+
+创建一个类型为T的对象并返回一个偏移量，这个偏移量可以在O(1)时间内转换为对象指针。这个偏移量相当于指针，但它的值在一般情况下小于2^32，所以我们可以把它作为64位id的一部分。对象可以被归还，但归还后对象并没有删除，也没有被析构，而是仅仅进入freelist。下次申请时可能会取到这种使用过的对象，需要重置后才能使用。当对象被归还后，通过对应的偏移量仍可以访问到对象，即ResourcePool只负责内存分配，并不解决ABA问题。但对于越界的偏移量，ResourcePool会返回空。
+
+由于对象等长，ResourcePool通过批量分配和归还内存以避免全局竞争，并降低单次的开销。每个线程的分配流程如下：
+
+1. 查看thread-local free block。如果还有free的对象，返回。没有的话步骤2。
+2. 尝试从全局取一个free block，若取到的话回到步骤1，否则步骤3。
+3. 从全局取一个block，返回其中第一个对象。
+
+原理是比较简单的。工程实现上数据结构、原子变量、memory fence等问题会复杂一些。下面以bthread_t的生成过程说明ResourcePool是如何被应用的。
+
+# ObjectPool<T>
+
+这是ResourcePool<T>的变种，不返回偏移量，而直接返回对象指针。内部结构和ResourcePool类似，一些代码更加简单。对于用户来说，这就是一个多线程下的对象池，brpc里也是这么用的。比如Socket::Write中把每个待写出的请求包装为WriteRequest，这个对象就是用ObjectPool<WriteRequest>分配的。
+
+# 生成bthread_t
+
+用户期望通过创建bthread获得更高的并发度，所以创建bthread必须很快。 在目前的实现中创建一个bthread的平均耗时小于200ns。如果每次都要从头创建，是不可能这么快的。创建过程更像是从一个bthread池子中取一个实例，我们又同时需要一个id来指代一个bthread，所以这儿正是ResourcePool的用武之地。bthread在代码中被称作Task，其结构被称为TaskMeta，定义在[task_meta.h](http://icode.baidu.com/repo/baidu/opensource/baidu-rpc/files/master/blob/src/bthread/task_meta.h)中，所有的TaskMeta由ResourcePool<TaskMeta>分配。
+
+bthread的大部分函数都需要在O(1)时间内通过bthread_t访问到TaskMeta，并且当bthread_t失效后，访问应返回NULL以让函数做出返回错误。解决方法是：bthread_t由32位的版本和32位的偏移量组成。版本解决[ABA问题](http://en.wikipedia.org/wiki/ABA_problem)，偏移量由ResourcePool<TaskMeta>分配。查找时先通过偏移量获得TaskMeta，再检查版本，如果版本不匹配，说明bthread失效了。注意：这只是大概的说法，在多线程环境下，即使版本相等，bthread仍可能随时失效，在不同的bthread函数中处理方法都是不同的，有些函数会加锁，有些则能忍受版本不相等。
+
+![img](../images/resource_pool.png)
+
+这种id生成方式在brpc中应用广泛，brpc中的SocketId，bthread_id_t也是用类似的方法分配的。
+
+# 栈
+
+使用ResourcePool加快创建的副作用是：一个pool中所有bthread的栈必须是一样大的。这似乎限制了用户的选择，不过基于我们的观察，大部分用户并不关心栈的具体大小，而只需要两种大小的栈：尺寸普通但数量较少，尺寸小但数量众多。所以我们用不同的pool管理不同大小的栈，用户可以根据场景选择。两种栈分别对应属性BTHREAD_ATTR_NORMAL（栈默认为1M）和BTHREAD_ATTR_SMALL（栈默认为32K）。用户还可以指定BTHREAD_ATTR_LARGE，这个属性的栈大小和pthread一样，由于尺寸较大，bthread不会对其做caching，创建速度较慢。server默认使用BTHREAD_ATTR_NORMAL运行用户代码。
+
+栈使用[mmap](http://linux.die.net/man/2/mmap)分配，bthread还会用mprotect分配4K的guard page以检测栈溢出。由于mmap+mprotect不能超过max_map_count（默认为65536），当bthread非常多后可能要调整此参数。另外当有很多bthread时，内存问题可能不仅仅是栈，也包括各类用户和系统buffer。
+
+goroutine在1.3前通过[segmented stacks](https://gcc.gnu.org/wiki/SplitStacks)动态地调整栈大小，发现有[hot split](https://docs.google.com/document/d/1wAaf1rYoM4S4gtnPh0zOlGzWtrZFQ5suE8qr2sD8uWQ/pub)问题后换成了变长连续栈（类似于vector resizing，只适合内存托管的语言）。由于bthread基本只会在64位平台上使用，虚存空间庞大，对变长栈需求不明确。加上segmented stacks的性能有影响，bthread暂时没有变长栈的计划。

docs/cn/parallel_http.md

+parallel_http能同时访问大量的http服务（几万个），适合在命令行中查询线上所有server的内置信息，供其他工具进一步过滤和聚合。curl很难做到这点，即使多个curl以后台的方式运行，并行度一般也只有百左右，访问几万台机器需要等待极长的时间。