1 | // Licensed to the Apache Software Foundation (ASF) under one |
2 | // or more contributor license agreements. See the NOTICE file |
3 | // distributed with this work for additional information |
4 | // regarding copyright ownership. The ASF licenses this file |
5 | // to you under the Apache License, Version 2.0 (the |
6 | // "License"); you may not use this file except in compliance |
7 | // with the License. You may obtain a copy of the License at |
8 | // |
9 | // http://www.apache.org/licenses/LICENSE-2.0 |
10 | // |
11 | // Unless required by applicable law or agreed to in writing, |
12 | // software distributed under the License is distributed on an |
13 | // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
14 | // KIND, either express or implied. See the License for the |
15 | // specific language governing permissions and limitations |
16 | // under the License. |
17 | |
18 | |
19 | #ifndef BRPC_SELECTIVE_CHANNEL_H |
20 | #define BRPC_SELECTIVE_CHANNEL_H |
21 | |
22 | // To brpc developers: This is a header included by user, don't depend |
23 | // on internal structures, use opaque pointers instead. |
24 | |
25 | #include "brpc/socket_id.h" |
26 | #include "brpc/channel.h" |
27 | |
28 | |
29 | namespace brpc { |
30 | |
31 | // A combo channel to split traffic to sub channels, aka "schan". The main |
32 | // purpose of schan is to load balance between groups of servers. |
33 | // SelectiveChannel is a fully functional Channel: |
34 | // * synchronous and asynchronous RPC. |
35 | // * deletable immediately after an asynchronous call. |
36 | // * cancelable call_id (cancels all sub calls). |
37 | // * timeout. |
38 | // Due to its designing goal, schan has a separate layer of retrying and |
39 | // backup request. Namely when schan fails to access a sub channel, it may |
40 | // retry another channel. sub channels inside a schan share the information |
41 | // of accessed servers and avoid retrying accessed servers by best efforts. |
42 | // When a schan would send a backup request, it calls a sub channel with |
43 | // the request. Since a sub channel can be a combo channel as well, the |
44 | // "backup request" may be "backup requests". |
45 | // ^ |
46 | // CAUTION: |
47 | // ======= |
48 | // Currently SelectiveChannel requires `request' to CallMethod be |
49 | // valid before the RPC ends. Other channels do not. If you're doing async |
50 | // calls with SelectiveChannel, make sure that `request' is owned and deleted |
51 | // in `done'. |
52 | class SelectiveChannel : public ChannelBase/*non-copyable*/ { |
53 | public: |
54 | typedef SocketId ChannelHandle; |
55 | |
56 | SelectiveChannel(); |
57 | ~SelectiveChannel(); |
58 | |
59 | // You MUST initialize a schan before using it. `load_balancer_name' is the |
60 | // name of load balancing algorithm which is listed in brpc/channel.h |
61 | // if `options' is NULL, use default options. |
62 | int Init(const char* load_balancer_name, const ChannelOptions* options); |
63 | |
64 | // Add a sub channel, which will be deleted along with schan or explicitly |
65 | // by RemoveAndDestroyChannel. |
66 | // On success, handle is set with the key for removal. |
67 | // NOTE: Different from pchan, schan can add channels at any time. |
68 | // Returns 0 on success, -1 otherwise. |
69 | int AddChannel(ChannelBase* sub_channel, ChannelHandle* handle); |
70 | |
71 | // Remove and destroy the sub_channel associated with `handle'. |
72 | void RemoveAndDestroyChannel(ChannelHandle handle); |
73 | |
74 | // Send request by a sub channel. schan may retry another sub channel |
75 | // according to retrying/backup-request settings. |
76 | void CallMethod(const google::protobuf::MethodDescriptor* method, |
77 | google::protobuf::RpcController* controller, |
78 | const google::protobuf::Message* request, |
79 | google::protobuf::Message* response, |
80 | google::protobuf::Closure* done); |
81 | |
82 | // True iff Init() was successful. |
83 | bool initialized() const; |
84 | |
85 | void Describe(std::ostream& os, const DescribeOptions& options) const; |
86 | |
87 | private: |
88 | int CheckHealth(); |
89 | |
90 | Channel _chan; |
91 | }; |
92 | |
93 | } // namespace brpc |
94 | |
95 | |
96 | #endif // BRPC_SELECTIVE_CHANNEL_H |
97 | |