Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. Comms
  5. pw_transport
  6. pw::transport::ForwardingSocketPair Class Reference
pw::transport::ForwardingSocketPair Class Reference

Overview

A connected pair of in-memory ReliableSocket endpoints that forward datagrams to each other.

Writes committed on first() are delivered as reads on second(), and writes committed on second() are delivered as reads on first(). Datagrams are forwarded without copying by transferring ownership of the underlying Buf from the writer's reservation to the reader's queue.

The underlying socket endpoints are reference-counted and allocated from the provided Allocator. Copies of the ReliableSocket handles returned by first() and second() may outlive the ForwardingSocketPair object itself; the shared state is automatically destroyed and deallocated once all handles and futures for both endpoints have been released.

Closing one socket (or dropping all handles to it) prevents further writes in both directions. Datagrams that were already committed before the socket closed can still be read by the peer, after which the peer socket also closes. Calling Close() on the ForwardingSocketPair closes both endpoints immediately and discards any unread datagrams.

Memory and locking

Each write reservation allocates its buffer from the pair's allocator. The buffer is freed when the reader releases the received ConstBuf, or when the reservation is canceled or fails to commit. Both sockets in a pair share one pw::sync::InterruptSpinLock, and the allocator is called while that lock is held, so it must not block (for example, it must not be guarded by a pw::sync::Mutex).

If the allocator cannot provide a write buffer, TryReserveWrite returns std::nullopt and ReserveWrite remains pending. Pending reservations are only retried when write capacity is released (the peer reads a datagram, or a reservation is canceled or fails to commit), not when unrelated memory is freed. Size the allocator to hold queue_depth maximum-size datagrams in each direction to avoid stalls.

Public Member Functions

constexpr ForwardingSocketPair ()=default
 
 ForwardingSocketPair (const ForwardingSocketPair &)=delete
 
ForwardingSocketPair & operator= (const ForwardingSocketPair &)=delete
 
 ForwardingSocketPair (ForwardingSocketPair &&) noexcept=default
 
ForwardingSocketPair & operator= (ForwardingSocketPair &&) noexcept=default
 
const ReliableSocket & first () const
 Returns the first socket in the pair.
 
const ReliableSocket & second () const
 Returns the second socket in the pair.
 
void Close ()
 

Static Public Member Functions

static ForwardingSocketPair Create (Allocator &allocator, const ForwardingSocketOptions &options={})
 
static Result< ForwardingSocketPair > TryCreate (Allocator &allocator, const ForwardingSocketOptions &options={})
 

Constructor & Destructor Documentation

◆ ForwardingSocketPair()

constexpr pw::transport::ForwardingSocketPair::ForwardingSocketPair ( )
constexprdefault

Creates an empty, uninitialized pair with null first() and second() sockets.

Member Function Documentation

◆ Close()

void pw::transport::ForwardingSocketPair::Close ( )
inline

Terminally closes both sockets in the pair immediately, discarding any unread datagrams in both directions.

◆ Create()

static ForwardingSocketPair pw::transport::ForwardingSocketPair::Create ( Allocator &  allocator,
const ForwardingSocketOptions &  options = {} 
)
static

Creates a connected pair of sockets, allocating the socket endpoints, queues, and write buffers from allocator.

Parameters
allocatorAllocator used for endpoints, queues, and write buffers. See "Memory and locking" in the class documentation for requirements.
optionsQueue depth and maximum message size. Asserts if options.queue_depth is 0.

Crash-asserts if allocator cannot allocate the initial socket pair state or queues. Use TryCreate for fallible creation.

◆ TryCreate()

static Result< ForwardingSocketPair > pw::transport::ForwardingSocketPair::TryCreate ( Allocator &  allocator,
const ForwardingSocketOptions &  options = {} 
)
static

Fallibly creates a connected pair of sockets, allocating the socket endpoints, queues, and write buffers from allocator.

Parameters
allocatorAllocator used for endpoints, queues, and write buffers. See "Memory and locking" in the class documentation for requirements.
optionsQueue depth and maximum message size. Asserts if options.queue_depth is 0.
Returns
  • OK: The socket pair was created.
  • RESOURCE_EXHAUSTED: allocator could not allocate the socket pair state or queues.

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