From c3d71f8b28d1fffff26f93b4da6e3aed75f78466 Mon Sep 17 00:00:00 2001 From: Mehrdad Afshari Date: Wed, 21 Feb 2018 23:29:10 -0800 Subject: [PATCH] Add more documentation comments for continuation --- .../Grpc.Core/Interceptors/Interceptor.cs | 174 +++++++++++++++++- 1 file changed, 170 insertions(+), 4 deletions(-) diff --git a/src/csharp/Grpc.Core/Interceptors/Interceptor.cs b/src/csharp/Grpc.Core/Interceptors/Interceptor.cs index c277aab2a50..56a30c34af6 100644 --- a/src/csharp/Grpc.Core/Interceptors/Interceptor.cs +++ b/src/csharp/Grpc.Core/Interceptors/Interceptor.cs @@ -31,6 +31,12 @@ namespace Grpc.Core.Interceptors { /// /// Represents a continuation for intercepting simple blocking invocations. + /// A delegate of this type is passed to the BlockingUnaryCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// context and request values as it sees fit. /// /// Request message type for this invocation. /// Response message type for this invocation. @@ -39,12 +45,23 @@ namespace Grpc.Core.Interceptors /// The /// instance to pass to the next step in the invocation process. /// + /// + /// The response value of the invocation to return to the caller. + /// The interceptor can choose to return the return value of the + /// continuation delegate or an arbitrary value as it sees fit. + /// public delegate TResponse BlockingUnaryCallContinuation(TRequest request, ClientInterceptorContext context) where TRequest : class where TResponse : class; /// /// Represents a continuation for intercepting simple asynchronous invocations. + /// A delegate of this type is passed to the AsyncUnaryCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// request value and context as it sees fit. /// /// Request message type for this invocation. /// Response message type for this invocation. @@ -53,12 +70,24 @@ namespace Grpc.Core.Interceptors /// The /// instance to pass to the next step in the invocation process. /// + /// + /// An instance of + /// representing an asynchronous invocation of a unary RPC. + /// The interceptor can choose to return the same object returned from + /// the continuation delegate or an arbitrarily constructed instance as it sees fit. + /// public delegate AsyncUnaryCall AsyncUnaryCallContinuation(TRequest request, ClientInterceptorContext context) where TRequest : class where TResponse : class; /// /// Represents a continuation for intercepting asynchronous server-streaming invocations. + /// A delegate of this type is passed to the AsyncServerStreamingCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// request value and context as it sees fit. /// /// Request message type for this invocation. /// Response message type for this invocation. @@ -67,12 +96,24 @@ namespace Grpc.Core.Interceptors /// The /// instance to pass to the next step in the invocation process. /// + /// + /// An instance of + /// representing an asynchronous invocation of a server-streaming RPC. + /// The interceptor can choose to return the same object returned from + /// the continuation delegate or an arbitrarily constructed instance as it sees fit. + /// public delegate AsyncServerStreamingCall AsyncServerStreamingCallContinuation(TRequest request, ClientInterceptorContext context) where TRequest : class where TResponse : class; /// /// Represents a continuation for intercepting asynchronous client-streaming invocations. + /// A delegate of this type is passed to the AsyncClientStreamingCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// request value and context as it sees fit. /// /// Request message type for this invocation. /// Response message type for this invocation. @@ -80,17 +121,35 @@ namespace Grpc.Core.Interceptors /// The /// instance to pass to the next step in the invocation process. /// + /// + /// An instance of + /// representing an asynchronous invocation of a client-streaming RPC. + /// The interceptor can choose to return the same object returned from + /// the continuation delegate or an arbitrarily constructed instance as it sees fit. + /// public delegate AsyncClientStreamingCall AsyncClientStreamingCallContinuation(ClientInterceptorContext context) where TRequest : class where TResponse : class; /// /// Represents a continuation for intercepting asynchronous duplex invocations. + /// A delegate of this type is passed to the AsyncDuplexStreamingCall method + /// when an outgoing invocation is being intercepted and calling the + /// delegate will invoke the next interceptor in the chain, or the underlying + /// call invoker if called from the last interceptor. The interceptor is + /// allowed to call it zero, one, or multiple times, passing it the appropriate + /// request value and context as it sees fit. /// /// /// The /// instance to pass to the next step in the invocation process. /// + /// + /// An instance of + /// representing an asynchronous invocation of a duplex-streaming RPC. + /// The interceptor can choose to return the same object returned from + /// the continuation delegate or an arbitrarily constructed instance as it sees fit. + /// public delegate AsyncDuplexStreamingCall AsyncDuplexStreamingCallContinuation(ClientInterceptorContext context) where TRequest : class where TResponse : class; @@ -106,8 +165,15 @@ namespace Grpc.Core.Interceptors /// /// The callback that continues the invocation process. /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// request value and context arguments, or substitute them as it sees fit. /// - /// The response message of the current invocation. + /// + /// The response message of the current invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or an arbitrary + /// value as it sees fit. + /// public virtual TResponse BlockingUnaryCall(TRequest request, ClientInterceptorContext context, BlockingUnaryCallContinuation continuation) where TRequest : class where TResponse : class @@ -126,7 +192,16 @@ namespace Grpc.Core.Interceptors /// /// The callback that continues the invocation process. /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// request value and context arguments, or substitute them as it sees fit. /// + /// + /// An instance of + /// representing an asynchronous unary invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or construct its + /// own substitute as it sees fit. + /// public virtual AsyncUnaryCall AsyncUnaryCall(TRequest request, ClientInterceptorContext context, AsyncUnaryCallContinuation continuation) where TRequest : class where TResponse : class @@ -145,7 +220,16 @@ namespace Grpc.Core.Interceptors /// /// The callback that continues the invocation process. /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// request value and context arguments, or substitute them as it sees fit. /// + /// + /// An instance of + /// representing an asynchronous server-streaming invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or construct its + /// own substitute as it sees fit. + /// public virtual AsyncServerStreamingCall AsyncServerStreamingCall(TRequest request, ClientInterceptorContext context, AsyncServerStreamingCallContinuation continuation) where TRequest : class where TResponse : class @@ -163,7 +247,16 @@ namespace Grpc.Core.Interceptors /// /// The callback that continues the invocation process. /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// context argument, or substitute as it sees fit. /// + /// + /// An instance of + /// representing an asynchronous client-streaming invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or construct its + /// own substitute as it sees fit. + /// public virtual AsyncClientStreamingCall AsyncClientStreamingCall(ClientInterceptorContext context, AsyncClientStreamingCallContinuation continuation) where TRequest : class where TResponse : class @@ -181,7 +274,16 @@ namespace Grpc.Core.Interceptors /// /// The callback that continues the invocation process. /// This can be invoked zero or more times by the interceptor. + /// The interceptor can invoke the continuation passing the given + /// context argument, or substitute as it sees fit. /// + /// + /// An instance of + /// representing an asynchronous duplex-streaming invocation. + /// The interceptor can simply return the return value of the + /// continuation delegate passed to it intact, or construct its + /// own substitute as it sees fit. + /// public virtual AsyncDuplexStreamingCall AsyncDuplexStreamingCall(ClientInterceptorContext context, AsyncDuplexStreamingCallContinuation continuation) where TRequest : class where TResponse : class @@ -190,10 +292,27 @@ namespace Grpc.Core.Interceptors } /// - /// Server-side handler for intercepting unary calls. + /// Server-side handler for intercepting and incoming unary call. /// /// Request message type for this method. /// Response message type for this method. + /// The request value of the incoming invocation. + /// + /// An instance of representing + /// the context of the invocation. + /// + /// + /// A delegate that asynchronously proceeds with the invocation, calling + /// the next interceptor in the chain, or the service request handler, + /// in case of the last interceptor and return the response value of + /// the RPC. The interceptor can choose to call it zero or more times + /// at its discretion. + /// + /// + /// A future representing the response value of the RPC. The interceptor + /// can simply return the return value from the continuation intact, + /// or an arbitrary response value as it sees fit. + /// public virtual Task UnaryServerHandler(TRequest request, ServerCallContext context, UnaryServerMethod continuation) where TRequest : class where TResponse : class @@ -206,6 +325,25 @@ namespace Grpc.Core.Interceptors /// /// Request message type for this method. /// Response message type for this method. + /// The request stream of the incoming invocation. + /// + /// An instance of representing + /// the context of the invocation. + /// + /// + /// A delegate that asynchronously proceeds with the invocation, calling + /// the next interceptor in the chain, or the service request handler, + /// in case of the last interceptor and return the response value of + /// the RPC. The interceptor can choose to call it zero or more times + /// at its discretion. + /// + /// + /// A future representing the response value of the RPC. The interceptor + /// can simply return the return value from the continuation intact, + /// or an arbitrary response value as it sees fit. The interceptor has + /// the ability to wrap or substitute the request stream when calling + /// the continuation. + /// public virtual Task ClientStreamingServerHandler(IAsyncStreamReader requestStream, ServerCallContext context, ClientStreamingServerMethod continuation) where TRequest : class where TResponse : class @@ -214,10 +352,24 @@ namespace Grpc.Core.Interceptors } /// - /// Server-side handler for intercepting server streaming calls. + /// Server-side handler for intercepting server streaming call. /// /// Request message type for this method. /// Response message type for this method. + /// The request value of the incoming invocation. + /// The response stream of the incoming invocation. + /// + /// An instance of representing + /// the context of the invocation. + /// + /// + /// A delegate that asynchronously proceeds with the invocation, calling + /// the next interceptor in the chain, or the service request handler, + /// in case of the last interceptor and the interceptor can choose to + /// call it zero or more times at its discretion. The interceptor has + /// the ability to wrap or substitute the request value and the response stream + /// when calling the continuation. + /// public virtual Task ServerStreamingServerHandler(TRequest request, IServerStreamWriter responseStream, ServerCallContext context, ServerStreamingServerMethod continuation) where TRequest : class where TResponse : class @@ -226,10 +378,24 @@ namespace Grpc.Core.Interceptors } /// - /// Server-side handler for intercepting bidi streaming calls. + /// Server-side handler for intercepting bidirectional streaming calls. /// /// Request message type for this method. /// Response message type for this method. + /// The request stream of the incoming invocation. + /// The response stream of the incoming invocation. + /// + /// An instance of representing + /// the context of the invocation. + /// + /// + /// A delegate that asynchronously proceeds with the invocation, calling + /// the next interceptor in the chain, or the service request handler, + /// in case of the last interceptor and the interceptor can choose to + /// call it zero or more times at its discretion. The interceptor has + /// the ability to wrap or substitute the request and response streams + /// when calling the continuation. + /// public virtual Task DuplexStreamingServerHandler(IAsyncStreamReader requestStream, IServerStreamWriter responseStream, ServerCallContext context, DuplexStreamingServerMethod continuation) where TRequest : class where TResponse : class