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.CallOptions; 20 import io.grpc.ClientStreamTracer; 21 import io.grpc.InternalChannelz.SocketStats; 22 import io.grpc.InternalInstrumented; 23 import io.grpc.Metadata; 24 import io.grpc.MethodDescriptor; 25 import java.util.concurrent.Executor; 26 import javax.annotation.concurrent.ThreadSafe; 27 28 /** 29 * The client-side transport typically encapsulating a single connection to a remote 30 * server. However, streams created before the client has discovered any server address may 31 * eventually be issued on different connections. All methods on the transport and its callbacks 32 * are expected to execute quickly. 33 */ 34 @ThreadSafe 35 public interface ClientTransport extends InternalInstrumented<SocketStats> { 36 37 /** 38 * Creates a new stream for sending messages to a remote end-point. 39 * 40 * <p>This method returns immediately and does not wait for any validation of the request. If 41 * creation fails for any reason, {@link ClientStreamListener#closed} will be called to provide 42 * the error information. Any sent messages for this stream will be buffered until creation has 43 * completed (either successfully or unsuccessfully). 44 * 45 * <p>This method is called under the {@link io.grpc.Context} of the {@link io.grpc.ClientCall}. 46 * 47 * @param method the descriptor of the remote method to be called for this stream. 48 * @param headers to send at the beginning of the call 49 * @param callOptions runtime options of the call 50 * @param tracers a non-empty array of tracers. The last element in it is reserved to be set by 51 * the load balancer's pick result and otherwise is a no-op tracer. 52 * @return the newly created stream. 53 */ 54 // TODO(nmittler): Consider also throwing for stopping. newStream( MethodDescriptor<?, ?> method, Metadata headers, CallOptions callOptions, ClientStreamTracer[] tracers)55 ClientStream newStream( 56 MethodDescriptor<?, ?> method, Metadata headers, CallOptions callOptions, 57 // Using array for tracers instead of a list or composition for better performance. 58 ClientStreamTracer[] tracers); 59 60 /** 61 * Pings a remote endpoint. When an acknowledgement is received, the given callback will be 62 * invoked using the given executor. 63 * 64 * <p>Pings are not necessarily sent to the same endpont, thus a successful ping only means at 65 * least one endpoint responded, but doesn't imply the availability of other endpoints (if there 66 * is any). 67 * 68 * <p>This is an optional method. Transports that do not have any mechanism by which to ping the 69 * remote endpoint may throw {@link UnsupportedOperationException}. 70 */ ping(PingCallback callback, Executor executor)71 void ping(PingCallback callback, Executor executor); 72 73 /** 74 * A callback that is invoked when the acknowledgement to a {@link #ping} is received. Exactly one 75 * of the two methods should be called per {@link #ping}. 76 */ 77 interface PingCallback { 78 79 /** 80 * Invoked when a ping is acknowledged. The given argument is the round-trip time of the ping, 81 * in nanoseconds. 82 * 83 * @param roundTripTimeNanos the round-trip duration between the ping being sent and the 84 * acknowledgement received 85 */ onSuccess(long roundTripTimeNanos)86 void onSuccess(long roundTripTimeNanos); 87 88 /** 89 * Invoked when a ping fails. The given argument is the cause of the failure. 90 * 91 * @param cause the cause of the ping failure 92 */ onFailure(Throwable cause)93 void onFailure(Throwable cause); 94 } 95 } 96