From b8a542cd234d32c8da7cb8474e26c9c21f3c9581 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Tue, 8 Jan 2019 09:20:15 -0800 Subject: [PATCH 1/2] Update Send message interception methods docs --- include/grpcpp/impl/codegen/interceptor.h | 27 +++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/include/grpcpp/impl/codegen/interceptor.h b/include/grpcpp/impl/codegen/interceptor.h index 5dea796a3b7..32a2d439d94 100644 --- a/include/grpcpp/impl/codegen/interceptor.h +++ b/include/grpcpp/impl/codegen/interceptor.h @@ -107,6 +107,24 @@ class InterceptorBatchMethods { /// of the hijacking interceptor. virtual void Hijack() = 0; + /// Send Message Methods + /// GetSerializedSendMessage and GetSendMessage/ModifySendMessage are the + /// available methods to view and modify the request payload. An interceptor + /// can access the payload in either serialized form or non-serialized form + /// but not both at the same time. + /// gRPC performs serialization in a lazy manner, which means + /// that a call to GetSerializedSendMessage will result in a serialization + /// operation if the payload stored is not in the serialized form already. The + /// non-serialized form is lost and GetSendMessage will no longer return a + /// valid pointer, and this will remain true for later interceptors too. This + /// can change however if ModifySendMessage is used to replace the current + /// payload. Note that ModifySendMessage requires a new payload message in the + /// non-serialized form. This will overwrite the existing payload irrespective + /// of whether it had been serialized earlier. Also note that gRPC Async API + /// requires early serialization of the payload which means that the payload + /// would be available in the serialized form only unless an interceptor + /// replaces the payload with ModifySendMessage. + /// Returns a modifable ByteBuffer holding the serialized form of the message /// that is going to be sent. Valid for PRE_SEND_MESSAGE interceptions. /// A return value of nullptr indicates that this ByteBuffer is not valid. @@ -114,15 +132,16 @@ class InterceptorBatchMethods { /// Returns a non-modifiable pointer to the non-serialized form of the message /// to be sent. Valid for PRE_SEND_MESSAGE interceptions. A return value of - /// nullptr indicates that this field is not valid. Also note that this is - /// only supported for sync and callback APIs at the present moment. + /// nullptr indicates that this field is not valid. virtual const void* GetSendMessage() = 0; /// Overwrites the message to be sent with \a message. \a message should be in /// the non-serialized form expected by the method. Valid for PRE_SEND_MESSAGE /// interceptions. Note that the interceptor is responsible for maintaining - /// the life of the message for the duration on the send operation, i.e., till - /// POST_SEND_MESSAGE. + /// the life of the message till it is serialized or it receives the + /// POST_SEND_MESSAGE interception point, whichever happens earlier. The + /// modifying interceptor may itself force early serialization by calling + /// GetSerializedSendMessage. virtual void ModifySendMessage(const void* message) = 0; /// Checks whether the SEND MESSAGE op succeeded. Valid for POST_SEND_MESSAGE From 73b1a918e4ae437ec7ac5f1d1c63c9fc2f153073 Mon Sep 17 00:00:00 2001 From: Yash Tibrewal Date: Tue, 8 Jan 2019 09:28:09 -0800 Subject: [PATCH 2/2] Slight update to grammar. Can probably be improved more --- include/grpcpp/impl/codegen/interceptor.h | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/include/grpcpp/impl/codegen/interceptor.h b/include/grpcpp/impl/codegen/interceptor.h index 32a2d439d94..03520867f9c 100644 --- a/include/grpcpp/impl/codegen/interceptor.h +++ b/include/grpcpp/impl/codegen/interceptor.h @@ -114,16 +114,16 @@ class InterceptorBatchMethods { /// but not both at the same time. /// gRPC performs serialization in a lazy manner, which means /// that a call to GetSerializedSendMessage will result in a serialization - /// operation if the payload stored is not in the serialized form already. The - /// non-serialized form is lost and GetSendMessage will no longer return a - /// valid pointer, and this will remain true for later interceptors too. This - /// can change however if ModifySendMessage is used to replace the current - /// payload. Note that ModifySendMessage requires a new payload message in the - /// non-serialized form. This will overwrite the existing payload irrespective - /// of whether it had been serialized earlier. Also note that gRPC Async API - /// requires early serialization of the payload which means that the payload - /// would be available in the serialized form only unless an interceptor - /// replaces the payload with ModifySendMessage. + /// operation if the payload stored is not in the serialized form already; the + /// non-serialized form will be lost and GetSendMessage will no longer return + /// a valid pointer, and this will remain true for later interceptors too. + /// This can change however if ModifySendMessage is used to replace the + /// current payload. Note that ModifySendMessage requires a new payload + /// message in the non-serialized form. This will overwrite the existing + /// payload irrespective of whether it had been serialized earlier. Also note + /// that gRPC Async API requires early serialization of the payload which + /// means that the payload would be available in the serialized form only + /// unless an interceptor replaces the payload with ModifySendMessage. /// Returns a modifable ByteBuffer holding the serialized form of the message /// that is going to be sent. Valid for PRE_SEND_MESSAGE interceptions.