1 /* 2 * Copyright 2018 The gRPC Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package io.grpc.grpclb; 18 19 import io.grpc.Attributes; 20 import io.grpc.ConnectivityStateInfo; 21 import io.grpc.EquivalentAddressGroup; 22 import io.grpc.LoadBalancer.Subchannel; 23 import javax.annotation.concurrent.NotThreadSafe; 24 25 /** 26 * Manages life-cycle of Subchannels for {@link GrpclbState}. 27 * 28 * <p>All methods are run from the ChannelExecutor that the helper uses. 29 */ 30 @NotThreadSafe 31 interface SubchannelPool { 32 33 /** 34 * Registers a listener to received Subchannel status updates. 35 */ registerListener(PooledSubchannelStateListener listener)36 void registerListener(PooledSubchannelStateListener listener); 37 38 /** 39 * Takes a {@link Subchannel} from the pool for the given {@code eag} if there is one available. 40 * Otherwise, creates and returns a new {@code Subchannel} with the given {@code eag} and {@code 41 * defaultAttributes}. 42 */ takeOrCreateSubchannel(EquivalentAddressGroup eag, Attributes defaultAttributes)43 Subchannel takeOrCreateSubchannel(EquivalentAddressGroup eag, Attributes defaultAttributes); 44 45 /** 46 * Puts a {@link Subchannel} back to the pool. From this point the Subchannel is owned by the 47 * pool, and the caller should stop referencing to this Subchannel. 48 */ returnSubchannel(Subchannel subchannel, ConnectivityStateInfo lastKnownState)49 void returnSubchannel(Subchannel subchannel, ConnectivityStateInfo lastKnownState); 50 51 /** 52 * Shuts down all subchannels in the pool immediately. 53 */ clear()54 void clear(); 55 56 /** 57 * Receives state changes for a pooled {@link Subchannel}. 58 */ 59 interface PooledSubchannelStateListener { 60 61 /** 62 * Handles a state change on a Subchannel. The behavior is similar to {@link 63 * io.grpc.LoadBalancer.SubchannelStateListener}. 64 * 65 * <p>When a subchannel is reused, subchannel state change event will be triggered even if the 66 * underlying status remains same. 67 */ onSubchannelState(Subchannel subchannel, ConnectivityStateInfo newState)68 void onSubchannelState(Subchannel subchannel, ConnectivityStateInfo newState); 69 70 } 71 } 72