1 #region Copyright notice and license 2 3 // Copyright 2015 gRPC authors. 4 // 5 // Licensed under the Apache License, Version 2.0 (the "License"); 6 // you may not use this file except in compliance with the License. 7 // 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, software 12 // distributed under the License is distributed on an "AS IS" BASIS, 13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 // See the License for the specific language governing permissions and 15 // limitations under the License. 16 17 #endregion 18 19 using System.Threading; 20 using System.Threading.Tasks; 21 22 namespace Grpc.Core 23 { 24 /// <summary> 25 /// A stream of messages to be read. 26 /// Messages can be awaited <c>await reader.MoveNext()</c>, that returns <c>true</c> 27 /// if there is a message available and <c>false</c> if there are no more messages 28 /// (i.e. the stream has been closed). 29 /// <para> 30 /// On the client side, the last invocation of <c>MoveNext()</c> either returns <c>false</c> 31 /// if the call has finished successfully or throws <c>RpcException</c> if call finished 32 /// with an error. Once the call finishes, subsequent invocations of <c>MoveNext()</c> will 33 /// continue yielding the same result (returning <c>false</c> or throwing an exception). 34 /// </para> 35 /// <para> 36 /// On the server side, <c>MoveNext()</c> does not throw exceptions. 37 /// In case of a failure, the request stream will appear to be finished 38 /// (<c>MoveNext</c> will return <c>false</c>) and the <c>CancellationToken</c> 39 /// associated with the call will be cancelled to signal the failure. 40 /// </para> 41 /// <para> 42 /// <c>MoveNext()</c> operations can be cancelled via a cancellation token. Cancelling 43 /// an individual read operation has the same effect as cancelling the entire call 44 /// (which will also result in the read operation returning prematurely), but the per-read cancellation 45 /// tokens passed to MoveNext() only result in cancelling the call if the read operation haven't finished 46 /// yet. 47 /// </para> 48 /// </summary> 49 /// <typeparam name="T">The message type.</typeparam> 50 public interface IAsyncStreamReader<out T> 51 { 52 /// <summary> 53 /// Gets the current element in the iteration. 54 /// </summary> 55 T Current { get; } 56 57 /// <summary> 58 /// Advances the reader to the next element in the sequence, returning the result asynchronously. 59 /// </summary> 60 /// <param name="cancellationToken">Cancellation token that can be used to cancel the operation.</param> 61 /// <returns> 62 /// Task containing the result of the operation: true if the reader was successfully advanced 63 /// to the next element; false if the reader has passed the end of the sequence.</returns> MoveNext(CancellationToken cancellationToken)64 Task<bool> MoveNext(CancellationToken cancellationToken); 65 } 66 } 67