1 #region Copyright notice and license 2 3 // Copyright 2018 The 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; 20 21 namespace Grpc.Core 22 { 23 /// <summary> 24 /// Provides access to the payload being deserialized when deserializing messages. 25 /// </summary> 26 public abstract class DeserializationContext 27 { 28 /// <summary> 29 /// Get the total length of the payload in bytes. 30 /// </summary> 31 public abstract int PayloadLength { get; } 32 33 /// <summary> 34 /// Gets the entire payload as a newly allocated byte array. 35 /// Once the byte array is returned, the byte array becomes owned by the caller and won't be ever accessed or reused by gRPC again. 36 /// NOTE: Obtaining the buffer as a newly allocated byte array is the simplest way of accessing the payload, 37 /// but it can have important consequences in high-performance scenarios. 38 /// In particular, using this method usually requires copying of the entire buffer one extra time. 39 /// Also, allocating a new buffer each time can put excessive pressure on GC, especially if 40 /// the payload is more than 86700 bytes large (which means the newly allocated buffer will be placed in LOH, 41 /// and LOH object can only be garbage collected via a full ("stop the world") GC run). 42 /// NOTE: Deserializers are expected not to call this method (or other payload accessor methods) more than once per received message 43 /// (as there is no practical reason for doing so) and <c>DeserializationContext</c> implementations are free to assume so. 44 /// </summary> 45 /// <returns>byte array containing the entire payload.</returns> PayloadAsNewBuffer()46 public virtual byte[] PayloadAsNewBuffer() 47 { 48 throw new NotImplementedException(); 49 } 50 51 /// <summary> 52 /// Gets the entire payload as a ReadOnlySequence. 53 /// The ReadOnlySequence is only valid for the duration of the deserializer routine and the caller must not access it after the deserializer returns. 54 /// Using the read only sequence is the most efficient way to access the message payload. Where possible it allows directly 55 /// accessing the received payload without needing to perform any buffer copying or buffer allocations. 56 /// NOTE: When using this method, it is recommended to use C# 7.2 compiler to make it more useful (using Span type directly from your code requires C# 7.2)." 57 /// NOTE: Deserializers are expected not to call this method (or other payload accessor methods) more than once per received message 58 /// (as there is no practical reason for doing so) and <c>DeserializationContext</c> implementations are free to assume so. 59 /// </summary> 60 /// <returns>read only sequence containing the entire payload.</returns> PayloadAsReadOnlySequence()61 public virtual System.Buffers.ReadOnlySequence<byte> PayloadAsReadOnlySequence() 62 { 63 throw new NotImplementedException(); 64 } 65 } 66 } 67