Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. pw_rpc2
  5. Readers and writers
  6. pw::rpc2::Writer< Message > Class Template Reference
Loading...
Searching...
No Matches
Public Member Functions | Friends | List of all members
pw::rpc2::Writer< Message > Class Template Reference
pw_rpc2 » Readers and writers

Overview

template<typename Message>
class pw::rpc2::Writer< Message >

Outbound stream handle for sending zero or more messages to the peer.

  • Server side (server- and bidirectional-streaming RPCs): streams response messages to the client. Finish() (or ~Writer()) completes the RPC with kOk.
  • Client side (client- and bidirectional-streaming RPCs): streams request messages to the server. Finish() (or ~Writer()) closes the request stream while keeping the call open for responses. Call Cancel() to abort the call instead.

Every Writer can copy a ConstBuf with WriteCopy() or reserve a buffer with ReserveWrite(). Typed writers (such as Writer<pwpb::Msg>) also serialize messages with Write().

Messages are sent in the order their writes complete or their reservations are committed, not the order Write(), WriteCopy(), ReserveWrite(), or Finish() was called. Await each write (or commit its reservation) before starting the next write or Finish().

On a server, if the method's future or coroutine completes before its Writer has finished the stream (for example, if the Writer was moved to a subtask that was not joined before returning), the call ends with an error, which the client sees as kCancelled, and any remaining writes fail.

Inheritance diagram for pw::rpc2::Writer< Message >:
pw::rpc2::internal::WriterBase

Public Member Functions

 Writer (const Writer &)=delete
 
Writer & operator= (const Writer &)=delete
 
 Writer (Writer &&) noexcept=default
 
Writer & operator= (Writer &&) noexcept=default
 
template<typename M = Message, typename = internal::EnableIfCopyableMessage<M>>
WriteFuture< Message > Write (const Message &message)
 
template<typename M = Message, typename = std::enable_if_t<!std::is_same_v<M, ConstBuf>>>
WriteFuture< Message > Write (Message &&message)
 
WriteFuture< ConstBuf > WriteCopy (ConstBuf &&message)
 
ReserveWriteFuture ReserveWrite (size_t max_message_size)
 
WriteFuture Finish ()
 
- Public Member Functions inherited from pw::rpc2::internal::WriterBase
 WriterBase (const WriterBase &)=delete
 
WriterBase & operator= (const WriterBase &)=delete
 
bool is_closed () const
 
void Cancel ()
 

Friends

struct internal::CallAccess
 

Additional Inherited Members

- Protected Types inherited from pw::rpc2::internal::WriterBase
enum  OnDestroy : bool { kFinishOnDestroy = false , kErrorOnDestroy = true }
 
- Protected Member Functions inherited from pw::rpc2::internal::WriterBase
 WriterBase (const IntrusivePtr< Call > &call, OnDestroy on_destroy)
 
 WriterBase (IntrusivePtr< Call > &&call, OnDestroy on_destroy)
 
 WriterBase (WriterBase &&) noexcept=default
 
WriterBase & operator= (WriterBase &&other) noexcept
 
size_t payload_limit () const
 
ReserveWriteFuture ReserveMessage (size_t max_message_size) const
 
ReserveWriteFuture ReserveStreamEnd () const
 
ReserveWriteFuture ReserveResponse (size_t max_message_size) const
 

Member Function Documentation

◆ Finish()

template<typename Message >
WriteFuture pw::rpc2::Writer< Message >::Finish ( )
inline

Completes the outbound message stream normally.

The peer's Reader::Read() resolves to kEndOfStream after all prior messages have been read. On a server, this completes the RPC with kOk; on a client, it closes the request stream while keeping the inbound side open.

Destroying a Writer without calling Finish() or Cancel() finishes the stream on a best-effort basis. Await Finish() to wait for buffer space and observe whether completion was committed.

Warning
On a server, committing Finish() retires the call and destroys the method's future or coroutine on the connection's next poll. Perform all per-call work before calling Finish().

◆ ReserveWrite()

template<typename Message >
ReserveWriteFuture pw::rpc2::Writer< Message >::ReserveWrite ( size_t  max_message_size)
inline

Reserves a buffer of at least max_message_size bytes for writing a message in place.

◆ Write() [1/2]

template<typename Message >
template<typename M = Message, typename = internal::EnableIfCopyableMessage<M>>
WriteFuture< Message > pw::rpc2::Writer< Message >::Write ( const Message &  message)
inline

Serializes and sends message. Not available on RawWriter; use WriteCopy() instead.

Note
message is copied into the returned future. This overload is disabled for pw_protobuf messages with callback fields (since copying a message drops its callbacks); move them into Write(Message&&) instead.

◆ Write() [2/2]

template<typename Message >
template<typename M = Message, typename = std::enable_if_t<!std::is_same_v<M, ConstBuf>>>
WriteFuture< Message > pw::rpc2::Writer< Message >::Write ( Message &&  message)
inline

Serializes and sends message, moving it into the returned future. Not available on RawWriter; use WriteCopy() instead.

◆ WriteCopy()

template<typename Message >
WriteFuture< ConstBuf > pw::rpc2::Writer< Message >::WriteCopy ( ConstBuf &&  message)
inline

Copies message into the outbound stream.

Pass ConstBuf::Unowned(bytes) to copy from bytes that outlive the returned future, or move in an owned ConstBuf, which is released once copied.

The documentation for this class was generated from the following file: