1 /* 2 * Copyright 2016 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.internal; 18 19 import io.grpc.Status; 20 import javax.annotation.CheckReturnValue; 21 import javax.annotation.Nullable; 22 import javax.annotation.concurrent.ThreadSafe; 23 24 /** 25 * A {@link ClientTransport} that has life-cycle management. 26 * 27 * <p>{@link #start} must be the first method call to this interface and return before calling other 28 * methods. 29 * 30 * <p>Typically the transport owns the streams it creates through {@link #newStream}, while some 31 * implementations may transfer the streams to somewhere else. Either way they must conform to the 32 * contract defined by {@link #shutdown}, {@link Listener#transportShutdown} and 33 * {@link Listener#transportTerminated}. 34 */ 35 @ThreadSafe 36 public interface ManagedClientTransport extends ClientTransport { 37 38 /** 39 * Starts transport. This method may only be called once. 40 * 41 * <p>Implementations must not call {@code listener} from within {@link #start}; implementations 42 * are expected to notify listener on a separate thread or when the returned {@link Runnable} is 43 * run. This method and the returned {@code Runnable} should not throw any exceptions. 44 * 45 * @param listener non-{@code null} listener of transport events 46 * @return a {@link Runnable} that is executed after-the-fact by the original caller, typically 47 * after locks are released 48 */ 49 @CheckReturnValue 50 @Nullable start(Listener listener)51 Runnable start(Listener listener); 52 53 /** 54 * Initiates an orderly shutdown of the transport. Existing streams continue, but the transport 55 * will not own any new streams. New streams will either fail (once 56 * {@link Listener#transportShutdown} callback called), or be transferred off this transport (in 57 * which case they may succeed). This method may only be called once. 58 */ shutdown(Status reason)59 void shutdown(Status reason); 60 61 /** 62 * Initiates a forceful shutdown in which preexisting and new calls are closed. Existing calls 63 * should be closed with the provided {@code reason}. 64 */ shutdownNow(Status reason)65 void shutdownNow(Status reason); 66 67 /** 68 * Receives notifications for the transport life-cycle events. Implementation does not need to be 69 * thread-safe, so notifications must be properly synchronized externally. 70 */ 71 interface Listener { 72 /** 73 * The transport is shutting down. This transport will stop owning new streams, but existing 74 * streams may continue, and the transport may still be able to process {@link #newStream} as 75 * long as it doesn't own the new streams. Shutdown could have been caused by an error or normal 76 * operation. It is possible that this method is called without {@link #shutdown} being called. 77 * 78 * <p>This is called exactly once, and must be called prior to {@link #transportTerminated}. 79 * 80 * @param s the reason for the shutdown. 81 */ transportShutdown(Status s)82 void transportShutdown(Status s); 83 84 /** 85 * The transport completed shutting down. All resources have been released. All streams have 86 * either been closed or transferred off this transport. This transport may still be able to 87 * process {@link #newStream} as long as it doesn't own the new streams. 88 * 89 * <p>This is called exactly once, and must be called after {@link #transportShutdown} has been 90 * called. 91 */ transportTerminated()92 void transportTerminated(); 93 94 /** 95 * The transport is ready to accept traffic, because the connection is established. This is 96 * called at most once. 97 */ transportReady()98 void transportReady(); 99 100 /** 101 * Called whenever the transport's in-use state has changed. A transport is in-use when it has 102 * at least one stream. 103 */ transportInUse(boolean inUse)104 void transportInUse(boolean inUse); 105 } 106 } 107