A industrial-grade RPC framework used throughout [Baidu](http://ir.baidu.com/phoenix.zhtml?c=188488&p=irol-irhome), with 1,000,000+ instances(not counting clients) and thousands kinds of services, called "**baidu-rpc**" inside Baidu. Only C++ implementation is opensourced right now.
An industrial-grade RPC framework used throughout [Baidu](http://ir.baidu.com/phoenix.zhtml?c=188488&p=irol-irhome), with 1,000,000+ instances(not counting clients) and thousands kinds of services, called "**baidu-rpc**" inside Baidu. Only C++ implementation is opensourced right now.
You can use it to:
You can use it to:
* Build a server that can talk in multiple protocols (**on same port**), or access all sorts of services
* Build a server that can talk in multiple protocols (**on same port**), or access all sorts of services
Description: A industrial-grade RPC framework used throughout Baidu, with 1,000,000+ instances(not counting clients) and thousands kinds of services, called "baidu-rpc" inside Baidu.
Description: An industrial-grade RPC framework used throughout Baidu, with 1,000,000+ instances(not counting clients) and thousands kinds of services, called "baidu-rpc" inside Baidu.
@@ -34,7 +34,7 @@ Note that Channel neither modifies `options` nor accesses `options` after comple
...
@@ -34,7 +34,7 @@ Note that Channel neither modifies `options` nor accesses `options` after comple
Init() can connect one server or a cluster(multiple servers).
Init() can connect one server or a cluster(multiple servers).
# Connect a server
# Connect to a server
```c++
```c++
// Take default values when options is NULL.
// Take default values when options is NULL.
...
@@ -53,7 +53,7 @@ Invalid "server_addr_and_port":
...
@@ -53,7 +53,7 @@ Invalid "server_addr_and_port":
- 127.0.0.1:90000 # too large port
- 127.0.0.1:90000 # too large port
- 10.39.2.300:8000 # invalid IP
- 10.39.2.300:8000 # invalid IP
# Connect a cluster
# Connect to a cluster
```c++
```c++
intInit(constchar*naming_service_url,
intInit(constchar*naming_service_url,
...
@@ -86,15 +86,30 @@ If the list in BNS is non-empty, but Channel says "no servers", the status bit o
...
@@ -86,15 +86,30 @@ If the list in BNS is non-empty, but Channel says "no servers", the status bit o
### file://\<path\>
### file://\<path\>
Servers are put in the file specified by `path`. In "file://conf/local_machine_list", "conf/local_machine_list" is the file and each line in the file is address of a server. brpc reloads the file when it's updated.
Servers are put in the file specified by `path`. For example, in "file://conf/machine_list", "conf/machine_list" is the file:
* in which each line is address of a server.
* contents after \# are comments and ignored.
* non-comment contents after addresses are tags, which are separated from addresses by one or more spaces, same address + different tags are treated as different instances.
* brpc reloads the file when it's updated.
```
# This line is ignored
10.24.234.17 tag1 # a comment
10.24.234.17 tag2 # an instance different from the instance on last line
10.24.234.18
10.24.234.19
```
Pros: easy to modify, convenient for unittests. Cons: need to update every client when the list changes, not suitable for online deployment.
### list://\<addr1\>,\<addr2\>...
### list://\<addr1\>,\<addr2\>...
Servers are directly written after list://, separated by comma. For example: "list://db-bce-81-3-186.db01:7000,m1-bce-44-67-72.m1:7000,cp01-rd-cos-006.cp01:7000" has 3 addresses.
Servers are directly written after list://, separated by comma. For example: "list://db-bce-81-3-186.db01:7000,m1-bce-44-67-72.m1:7000,cp01-rd-cos-006.cp01:7000" has 3 addresses.
Tags can be appended to addresses, separated with one or more spaces. Same address + different tags are treated as different instances.
Pros: directly configurable in CLI, convenient for unittests. Cons: cannot be updated at runtime, not suitable for online deployment at all.
### http://\<url\>
### http://\<url\>
Connect all servers under the domain, for example: http://www.baidu.com:80. Note: although Init() for connecting single server(2 parameters) accepts hostname as well, it only connects one server under the domain.
Connect all servers under the domain, for example: http://www.baidu.com:80. Note: although Init() for connecting single server(2 parameters) accepts hostname as well, it only connects one server under the domain.
Pros: Versatility of DNS, useable both in private or public network. Cons: limited by transmission formats of DNS, unable to implement notification mechanisms.
### consul://\<service-name\>
### consul://\<service-name\>
...
@@ -108,6 +123,18 @@ If the server list returned by the consul does not follow [response format](http
...
@@ -108,6 +123,18 @@ If the server list returned by the consul does not follow [response format](http
If consul is not accessible, the naming service can be automatically downgraded to file naming service. This feature is turned off by default and can be turned on by setting -consul\_enable\_degrade\_to\_file\_naming\_service. After downgrading, in the directory specified by -consul\_file\_naming\_service\_dir, the file whose name is the service-name will be used. This file can be generated by the consul-template, which holds the latest server list before the consul is unavailable. The consul naming service is automatically restored when consul is restored.
If consul is not accessible, the naming service can be automatically downgraded to file naming service. This feature is turned off by default and can be turned on by setting -consul\_enable\_degrade\_to\_file\_naming\_service. After downgrading, in the directory specified by -consul\_file\_naming\_service\_dir, the file whose name is the service-name will be used. This file can be generated by the consul-template, which holds the latest server list before the consul is unavailable. The consul naming service is automatically restored when consul is restored.
### More naming services
User can extend to more naming services by implementing brpc::NamingService, check [this link](https://github.com/brpc/brpc/blob/master/docs/cn/load_balancing.md#%E5%91%BD%E5%90%8D%E6%9C%8D%E5%8A%A1) for details.
### The tag in naming service
tag was used for implementing "coarse-grained wrr": different tags are appended to a same address to make different instances, such that the address gets traffic proportional to the number of different tags. However, you should consider using [wrr algorithm](#wrr) first which distributes traffic proportional to assigned weights and is more fine-grained.
### VIP related issues
VIP is often the public IP of layer-4 load balancer, which proxies traffic to RS behide. When a client connects to the VIP, a connection is established to a chosen RS. When the client connection is broken, the connection to the RS is reset as well.
If one client establishes only one connection to the VIP("single" connection type in brpc), all traffic from the client lands on one RS. If number of clients are large enough, each RS should gets many connections and roughly balanced, at least from the cluster perspective. However, if clients are not large enough or workload from clients are very different, some RS may be overloaded. Another issue is that when multiple VIP are listed together, the traffic to them may not be proportional to the number of RS behide them.
One solution to these issues is to use "pooled" connection type, so that one client may create multiple connections to one VIP (roughly the max concurrency recently) to make traffic land on different RS. If more than one VIP are present, consider using [wrr load balancing](#wrr) to assign weights to different VIP, or add different tags to VIP to form more instances.
Note: When the client uses "single" connection type, even if one VIP appended with different tags can get more traffic, the connection is still one. This is decided by current implementation in brpc.
### Naming Service Filter
### Naming Service Filter
Users can filter servers got from the NamingService before pushing to LoadBalancer.
Users can filter servers got from the NamingService before pushing to LoadBalancer.
A industrial-grade RPC framework used throughout [Baidu](http://ir.baidu.com/phoenix.zhtml?c=188488&p=irol-irhome), with 1,000,000+ instances(not counting clients) and thousands kinds of services, called "**baidu-rpc**" inside Baidu. Only C++ implementation is opensourced right now.
An industrial-grade RPC framework used throughout [Baidu](http://ir.baidu.com/phoenix.zhtml?c=188488&p=irol-irhome), with 1,000,000+ instances(not counting clients) and thousands kinds of services, called "**baidu-rpc**" inside Baidu. Only C++ implementation is opensourced right now.
You can use it to:
You can use it to:
* Build a server that can talk in multiple protocols (**on same port**), or access all sorts of services
* Build a server that can talk in multiple protocols (**on same port**), or access all sorts of services
