@ -53,16 +53,38 @@ class ClientAsyncStreamingInterface {
/// Request notification of the reading of the initial metadata. Completion
/// will be notified by \a tag on the associated completion queue.
/// This call is optional, but if it is used, it cannot be used concurrently
/// with or after the \a Read method.
/// with or after the \a AsyncReaderInterface:: Read method.
///
/// \param[in] tag Tag identifying this request.
virtual void ReadInitialMetadata ( void * tag ) = 0 ;
/// Indicate that the stream is to be finished and request notification
/// Should not be used concurrently with other operations
/// Indicate that the stream is to be finished and request notification for
/// when the call has been ended.
/// Should not be used concurrently with other operations.
///
/// It is appropriate to call this method when both:
/// * the client side has no more message to send
/// (this can be declared implicitly by calling this method, or
/// explicitly through an earlier call to the <i>WritesDone</i> method
/// of the class in use, e.g. \a ClientAsyncWriterInterface::WritesDone or
/// \a ClientAsyncReaderWriterInterface::WritesDone).
/// * there are no more messages to be received from the server (this can
/// be known implicitly by the calling code, or explicitly from an
/// earlier call to \a AsyncReaderInterface::Read that yielded a failed
/// result, e.g. cq->Next(&read_tag, &ok) filled in 'ok' with 'false').
///
/// This function will return when either:
/// - all incoming messages have been read and the server has returned
/// a status.
/// - the server has returned a non-OK status.
/// - the call failed for some reason and the library generated a
/// status.
///
/// Note that implementations of this method attempt to receive initial
/// metadata from the server if initial metadata hasn't yet been received.
///
/// \param[out] status To be updated with the operation status.
/// \param[in] tag Tag identifying this request.
/// \param[out] status To be updated with the operation status.
virtual void Finish ( Status * status , void * tag ) = 0 ;
} ;
@ -77,11 +99,14 @@ class AsyncReaderInterface {
/// This is thread-safe with respect to \a Write or \a WritesDone methods. It
/// should not be called concurrently with other streaming APIs
/// on the same stream. It is not meaningful to call it concurrently
/// with another \a Read on the same stream since reads on the same stream
/// are delivered in order.
/// with another \a AsyncReaderInterface:: Read on the same stream since reads
/// on the same stream are delivered in order.
///
/// \param[out] msg Where to eventually store the read message.
/// \param[in] tag The tag identifying the operation.
///
/// Side effect: note that this method attempt to receive initial metadata for
/// a stream if it hasn't yet been received.
virtual void Read ( R * msg , void * tag ) = 0 ;
} ;
@ -96,7 +121,7 @@ class AsyncWriterInterface {
/// Only one write may be outstanding at any given time. This means that
/// after calling Write, one must wait to receive \a tag from the completion
/// queue BEFORE calling Write again.
/// This is thread-safe with respect to \a Read
/// This is thread-safe with respect to \a AsyncReaderInterface:: Read
///
/// \param[in] msg The message to be written.
/// \param[in] tag The tag identifying the operation.
@ -109,7 +134,7 @@ class AsyncWriterInterface {
/// after calling Write, one must wait to receive \a tag from the completion
/// queue BEFORE calling Write again.
/// WriteOptions \a options is used to set the write options of this message.
/// This is thread-safe with respect to \a Read
/// This is thread-safe with respect to \a AsyncReaderInterface:: Read
///
/// \param[in] msg The message to be written.
/// \param[in] options The WriteOptions to be used to write this message.
@ -117,11 +142,11 @@ class AsyncWriterInterface {
virtual void Write ( const W & msg , WriteOptions options , void * tag ) = 0 ;
/// Request the writing of \a msg and coalesce it with the writing
/// of trailing metadata, using WriteOptions \a options with identifying tag
/// \a tag.
/// of trailing metadata, using WriteOptions \a options with
/// identifying tag \a tag.
///
/// For client, WriteLast is equivalent of performing Write and WritesDone in
/// a single step.
/// For client, WriteLast is equivalent of performing Write and
/// WritesDone in a single step.
/// For server, WriteLast buffers the \a msg. The writing of \a msg is held
/// until Finish is called, where \a msg and trailing metadata are coalesced
/// and write is initiated. Note that WriteLast can only buffer \a msg up to
@ -140,10 +165,17 @@ template <class R>
class ClientAsyncReaderInterface : public ClientAsyncStreamingInterface ,
public AsyncReaderInterface < R > { } ;
/// Async client-side API for doing server-streaming RPCs,
/// where the incoming message stream coming from the server has
/// messages of type \a R.
template < class R >
class ClientAsyncReader final : public ClientAsyncReaderInterface < R > {
public :
/// Create a stream and write the first request out.
/// \a tag will be notified on \a cq when the call has been started and
/// \a request has been written out.
/// Note that \a context will be used to fill in custom initial metadata
/// used to send to the server when starting the call.
template < class W >
static ClientAsyncReader * Create ( ChannelInterface * channel ,
CompletionQueue * cq , const RpcMethod & method ,
@ -160,6 +192,14 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> {
assert ( size = = sizeof ( ClientAsyncReader ) ) ;
}
/// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata
/// method for semantics.
///
/// Side effect:
/// - upon receiving initial metadata from the server,
/// the \a ClientContext associated with this call is updated, and the
/// calling code can access the received metadata through the
/// \a ClientContext.
void ReadInitialMetadata ( void * tag ) override {
GPR_CODEGEN_ASSERT ( ! context_ - > initial_metadata_received_ ) ;
@ -177,6 +217,11 @@ class ClientAsyncReader final : public ClientAsyncReaderInterface<R> {
call_ . PerformOps ( & read_ops_ ) ;
}
/// See the \a ClientAsyncStreamingInterface.Finish method for semantics.
///
/// Side effect:
/// - the \a ClientContext associated with this call is updated with
/// possible initial and trailing metadata received from the server.
void Finish ( Status * status , void * tag ) override {
finish_ops_ . set_output_tag ( tag ) ;
if ( ! context_ - > initial_metadata_received_ ) {
@ -214,16 +259,27 @@ template <class W>
class ClientAsyncWriterInterface : public ClientAsyncStreamingInterface ,
public AsyncWriterInterface < W > {
public :
/// Signal the client is done with the writes.
/// Thread-safe with respect to \a Read
/// Signal the client is done with the writes (half-close the client stream) .
/// Thread-safe with respect to \a AsyncReaderInterface:: Read
///
/// \param[in] tag The tag identifying the operation.
virtual void WritesDone ( void * tag ) = 0 ;
} ;
/// Async API on the client side for doing client-streaming RPCs,
/// where the outgoing message stream going to the server contains
/// messages of type \a W.
template < class W >
class ClientAsyncWriter final : public ClientAsyncWriterInterface < W > {
public :
/// Create a stream and write the first request out.
/// \a tag will be notified on \a cq when the call has been started (i.e.
/// intitial metadata sent) and \a request has been written out.
/// Note that \a context will be used to fill in custom initial metadata
/// used to send to the server when starting the call.
/// \a response will be filled in with the single expected response
/// message from the server upon a successful call to the \a Finish
/// method of this instance.
template < class R >
static ClientAsyncWriter * Create ( ChannelInterface * channel ,
CompletionQueue * cq , const RpcMethod & method ,
@ -240,6 +296,13 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> {
assert ( size = = sizeof ( ClientAsyncWriter ) ) ;
}
/// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method for
/// semantics.
///
/// Side effect:
/// - upon receiving initial metadata from the server, the \a ClientContext
/// associated with this call is updated, and the calling code can access
/// the received metadata through the \a ClientContext.
void ReadInitialMetadata ( void * tag ) override {
GPR_CODEGEN_ASSERT ( ! context_ - > initial_metadata_received_ ) ;
@ -272,6 +335,13 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> {
call_ . PerformOps ( & write_ops_ ) ;
}
/// See the \a ClientAsyncStreamingInterface.Finish method for semantics.
///
/// Side effect:
/// - the \a ClientContext associated with this call is updated with
/// possible initial and trailing metadata received from the server.
/// - attempts to fill in the \a response parameter passed to this class's
/// constructor with the server's response message.
void Finish ( Status * status , void * tag ) override {
finish_ops_ . set_output_tag ( tag ) ;
if ( ! context_ - > initial_metadata_received_ ) {
@ -310,23 +380,34 @@ class ClientAsyncWriter final : public ClientAsyncWriterInterface<W> {
finish_ops_ ;
} ;
/// Client-side interface for asynchronous bi-directional streaming.
/// Async client-side interface for bi-directional streaming,
/// where the client-to-server message stream has messages of type \a W,
/// and the server-to-client message stream has messages of type \a R.
template < class W , class R >
class ClientAsyncReaderWriterInterface : public ClientAsyncStreamingInterface ,
public AsyncWriterInterface < W > ,
public AsyncReaderInterface < R > {
public :
/// Signal the client is done with the writes.
/// Thread-safe with respect to \a Read
/// Signal the client is done with the writes (half-close the client stream) .
/// Thread-safe with respect to \a AsyncReaderInterface:: Read
///
/// \param[in] tag The tag identifying the operation.
virtual void WritesDone ( void * tag ) = 0 ;
} ;
/// Async client-side interface for bi-directional streaming,
/// where the outgoing message stream going to the server
/// has messages of type \a W, and the incoming message stream coming
/// from the server has messages of type \a R.
template < class W , class R >
class ClientAsyncReaderWriter final
: public ClientAsyncReaderWriterInterface < W , R > {
public :
/// Create a stream and write the first request out.
/// \a tag will be notified on \a cq when the call has been started (i.e.
/// intitial metadata sent).
/// Note that \a context will be used to fill in custom initial metadata
/// used to send to the server when starting the call.
static ClientAsyncReaderWriter * Create ( ChannelInterface * channel ,
CompletionQueue * cq ,
const RpcMethod & method ,
@ -343,6 +424,13 @@ class ClientAsyncReaderWriter final
assert ( size = = sizeof ( ClientAsyncReaderWriter ) ) ;
}
/// See the \a ClientAsyncStreamingInterface.ReadInitialMetadata method
/// for semantics of this method.
///
/// Side effect:
/// - upon receiving initial metadata from the server, the \a ClientContext
/// is updated with it, and then the receiving initial metadata can
/// be accessed through this \a ClientContext.
void ReadInitialMetadata ( void * tag ) override {
GPR_CODEGEN_ASSERT ( ! context_ - > initial_metadata_received_ ) ;
@ -384,6 +472,10 @@ class ClientAsyncReaderWriter final
call_ . PerformOps ( & write_ops_ ) ;
}
/// See the \a ClientAsyncStreamingInterface.Finish method for semantics.
/// Side effect
/// - the \a ClientContext associated with this call is updated with
/// possible initial and trailing metadata sent from the server.
void Finish ( Status * status , void * tag ) override {
finish_ops_ . set_output_tag ( tag ) ;
if ( ! context_ - > initial_metadata_received_ ) {
@ -422,17 +514,62 @@ template <class W, class R>
class ServerAsyncReaderInterface : public ServerAsyncStreamingInterface ,
public AsyncReaderInterface < R > {
public :
/// Indicate that the stream is to be finished with a certain status code
/// and also send out \a msg response to the client.
/// Request notification for when the server has sent the response and the
/// appropriate signals to the client to end the call.
/// Should not be used concurrently with other operations.
///
/// It is appropriate to call this method when:
/// * all messages from the client have been received (either known
/// implictly, or explicitly because a previous
/// \a AsyncReaderInterface::Read operation with a non-ok result,
/// e.g., cq->Next(&read_tag, &ok) filled in 'ok' with 'false').
///
/// This operation will end when the server has finished sending out initial
/// metadata (if not sent already), response message, and status, or if
/// some failure occurred when trying to do so.
///
/// \param[in] tag Tag identifying this request.
/// \param[in] status To be sent to the client as the result of this call.
/// \param[in] msg To be sent to the client as the response for this call.
virtual void Finish ( const W & msg , const Status & status , void * tag ) = 0 ;
/// Indicate that the stream is to be finished with a certain
/// non-OK status code.
/// Request notification for when the server has sent the appropriate
/// signals to the client to end the call.
/// Should not be used concurrently with other operations.
///
/// This call is meant to end the call with some error, and can be called at
/// any point that the server would like to "fail" the call (though note
/// this shouldn't be called concurrently with any other "sending" call, like
/// \a AsyncWriterInterface::Write).
///
/// This operation will end when the server has finished sending out initial
/// metadata (if not sent already), and status, or if some failure occurred
/// when trying to do so.
///
/// \param[in] tag Tag identifying this request.
/// \param[in] status To be sent to the client as the result of this call.
/// - Note: \a status must have a non-OK code.
virtual void FinishWithError ( const Status & status , void * tag ) = 0 ;
} ;
/// Async server-side API for doing client-streaming RPCs,
/// where the incoming message stream from the client has messages of type \a R,
/// and the single response message sent from the server is type \a W.
template < class W , class R >
class ServerAsyncReader final : public ServerAsyncReaderInterface < W , R > {
public :
explicit ServerAsyncReader ( ServerContext * ctx )
: call_ ( nullptr , nullptr , nullptr ) , ctx_ ( ctx ) { }
/// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics.
///
/// Implicit input parameter:
/// - The initial metadata that will be sent to the client from this op will
/// be taken from the \a ServerContext associated with the call.
void SendInitialMetadata ( void * tag ) override {
GPR_CODEGEN_ASSERT ( ! ctx_ - > sent_initial_metadata_ ) ;
@ -452,6 +589,14 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> {
call_ . PerformOps ( & read_ops_ ) ;
}
/// See the \a ServerAsyncReaderInterface.Read method for semantics
///
/// Side effect:
/// - also sends initial metadata if not alreay sent.
/// - uses the \a ServerContext associated with this call to send possible
/// initial and trailing metadata.
///
/// Note: \a msg is not sent if \a status has a non-OK code.
void Finish ( const W & msg , const Status & status , void * tag ) override {
finish_ops_ . set_output_tag ( tag ) ;
if ( ! ctx_ - > sent_initial_metadata_ ) {
@ -472,6 +617,12 @@ class ServerAsyncReader final : public ServerAsyncReaderInterface<W, R> {
call_ . PerformOps ( & finish_ops_ ) ;
}
/// See the \a ServerAsyncReaderInterface.Read method for semantics
///
/// Side effect:
/// - also sends initial metadata if not alreay sent.
/// - uses the \a ServerContext associated with this call to send possible
/// initial and trailing metadata.
void FinishWithError ( const Status & status , void * tag ) override {
GPR_CODEGEN_ASSERT ( ! status . ok ( ) ) ;
finish_ops_ . set_output_tag ( tag ) ;
@ -503,14 +654,32 @@ template <class W>
class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface ,
public AsyncWriterInterface < W > {
public :
/// Indicate that the stream is to be finished with a certain status code.
/// Request notification for when the server has sent the appropriate
/// signals to the client to end the call.
/// Should not be used concurrently with other operations.
///
/// It is appropriate to call this method when either:
/// * all messages from the client have been received (either known
/// implictly, or explicitly because a previous \a
/// AsyncReaderInterface::Read operation with a non-ok
/// result (e.g., cq->Next(&read_tag, &ok) filled in 'ok' with 'false'.
/// * it is desired to end the call early with some non-OK status code.
///
/// This operation will end when the server has finished sending out initial
/// metadata (if not sent already), response message, and status, or if
/// some failure occurred when trying to do so.
///
/// \param[in] tag Tag identifying this request.
/// \param[in] status To be sent to the client as the result of this call.
virtual void Finish ( const Status & status , void * tag ) = 0 ;
/// Request the writing of \a msg and coalesce it with trailing metadata which
/// contains \a status, using WriteOptions options with identifying tag \a
/// tag.
/// contains \a status, using WriteOptions options with
/// identifying tag \a tag.
///
/// WriteAndFinish is equivalent of performing WriteLast and Finish in a
/// single step.
/// WriteAndFinish is equivalent of performing WriteLast and Finish
/// in a single step.
///
/// \param[in] msg The message to be written.
/// \param[in] options The WriteOptions to be used to write this message.
@ -520,12 +689,21 @@ class ServerAsyncWriterInterface : public ServerAsyncStreamingInterface,
const Status & status , void * tag ) = 0 ;
} ;
/// Async server-side API for doing server streaming RPCs,
/// where the outgoing message stream from the server has messages of type \a W.
template < class W >
class ServerAsyncWriter final : public ServerAsyncWriterInterface < W > {
public :
explicit ServerAsyncWriter ( ServerContext * ctx )
: call_ ( nullptr , nullptr , nullptr ) , ctx_ ( ctx ) { }
/// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics.
///
/// Implicit input parameter:
/// - The initial metadata that will be sent to the client from this op will
/// be taken from the \a ServerContext associated with the call.
///
/// \param[in] tag Tag identifying this request.
void SendInitialMetadata ( void * tag ) override {
GPR_CODEGEN_ASSERT ( ! ctx_ - > sent_initial_metadata_ ) ;
@ -559,6 +737,13 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> {
call_ . PerformOps ( & write_ops_ ) ;
}
/// See the \a ServerAsyncWriterInterface.WriteAndFinish method for semantics.
///
/// Implicit input parameter:
/// - the \a ServerContext associated with this call is used
/// for sending trailing (and initial) metadata to the client.
///
/// Note: \a status must have an OK code.
void WriteAndFinish ( const W & msg , WriteOptions options , const Status & status ,
void * tag ) override {
write_ops_ . set_output_tag ( tag ) ;
@ -569,6 +754,14 @@ class ServerAsyncWriter final : public ServerAsyncWriterInterface<W> {
call_ . PerformOps ( & write_ops_ ) ;
}
/// See the \a ServerAsyncWriterInterface.Finish method for semantics.
///
/// Implicit input parameter:
/// - the \a ServerContext associated with this call is used for sending
/// trailing (and initial if not already sent) metadata to the client.
///
/// Note: there are no restrictions are the code of
/// \a status,it may be non-OK
void Finish ( const Status & status , void * tag ) override {
finish_ops_ . set_output_tag ( tag ) ;
EnsureInitialMetadataSent ( & finish_ops_ ) ;
@ -606,11 +799,30 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface,
public AsyncWriterInterface < W > ,
public AsyncReaderInterface < R > {
public :
/// Indicate that the stream is to be finished with a certain status code.
/// Request notification for when the server has sent the appropriate
/// signals to the client to end the call.
/// Should not be used concurrently with other operations.
///
/// It is appropriate to call this method when either:
/// * all messages from the client have been received (either known
/// implictly, or explicitly because a previous \a
/// AsyncReaderInterface::Read operation
/// with a non-ok result (e.g., cq->Next(&read_tag, &ok) filled in 'ok'
/// with 'false'.
/// * it is desired to end the call early with some non-OK status code.
///
/// This operation will end when the server has finished sending out initial
/// metadata (if not sent already), response message, and status, or if some
/// failure occurred when trying to do so.
///
/// \param[in] tag Tag identifying this request.
/// \param[in] status To be sent to the client as the result of this call.
virtual void Finish ( const Status & status , void * tag ) = 0 ;
/// Request the writing of \a msg and coalesce it with trailing metadata which
/// contains \a status, using WriteOptions options with identifying tag \a
/// tag.
/// contains \a status, using WriteOptions options with
/// identifying tag \a tag.
///
/// WriteAndFinish is equivalent of performing WriteLast and Finish in a
/// single step.
@ -623,6 +835,10 @@ class ServerAsyncReaderWriterInterface : public ServerAsyncStreamingInterface,
const Status & status , void * tag ) = 0 ;
} ;
/// Async server-side API for doing bidirectional streaming RPCs,
/// where the incoming message stream coming from the client has messages of
/// type \a R, and the outgoing message stream coming from the server has
/// messages of type \a W.
template < class W , class R >
class ServerAsyncReaderWriter final
: public ServerAsyncReaderWriterInterface < W , R > {
@ -630,6 +846,13 @@ class ServerAsyncReaderWriter final
explicit ServerAsyncReaderWriter ( ServerContext * ctx )
: call_ ( nullptr , nullptr , nullptr ) , ctx_ ( ctx ) { }
/// See \a ServerAsyncStreamingInterface::SendInitialMetadata for semantics.
///
/// Implicit input parameter:
/// - The initial metadata that will be sent to the client from this op will
/// be taken from the \a ServerContext associated with the call.
///
/// \param[in] tag Tag identifying this request.
void SendInitialMetadata ( void * tag ) override {
GPR_CODEGEN_ASSERT ( ! ctx_ - > sent_initial_metadata_ ) ;
@ -667,6 +890,14 @@ class ServerAsyncReaderWriter final
call_ . PerformOps ( & write_ops_ ) ;
}
/// See the \a ServerAsyncReaderWriterInterface.WriteAndFinish
/// method for semantics.
///
/// Implicit input parameter:
/// - the \a ServerContext associated with this call is used
/// for sending trailing (and initial) metadata to the client.
///
/// Note: \a status must have an OK code.
void WriteAndFinish ( const W & msg , WriteOptions options , const Status & status ,
void * tag ) override {
write_ops_ . set_output_tag ( tag ) ;
@ -677,6 +908,14 @@ class ServerAsyncReaderWriter final
call_ . PerformOps ( & write_ops_ ) ;
}
/// See the \a ServerAsyncReaderWriterInterface.Finish method for semantics.
///
/// Implicit input parameter:
/// - the \a ServerContext associated with this call is used for sending
/// trailing (and initial if not already sent) metadata to the client.
///
/// Note: there are no restrictions are the code of \a status,
/// it may be non-OK
void Finish ( const Status & status , void * tag ) override {
finish_ops_ . set_output_tag ( tag ) ;
EnsureInitialMetadataSent ( & finish_ops_ ) ;
Craig Tiller
8 years ago