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
29namespace 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'.
52class SelectiveChannel : public ChannelBase/*non-copyable*/ {
53public:
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
87private:
88 int CheckHealth();
89
90 Channel _chan;
91};
92
93} // namespace brpc
94
95
96#endif // BRPC_SELECTIVE_CHANNEL_H
97