Skip to main content
Pigweed's logo Pigweed
code_xml
  1. Home
  2. Reference
  3. C/C++
  4. Comms
  5. pw_transfer
  6. pw::transfer::TransferService Class Reference
Loading...
Searching...
No Matches
Public Types | Public Member Functions | List of all members
pw::transfer::TransferService Class Reference
Comms » pw_transfer

Overview

RPC service for running server-side pw_transfer transfers.

Register Handler instances with RegisterHandler() for each transferable resource, and register the TransferService with a pw::rpc::Server.

Inheritance diagram for pw::transfer::TransferService:

Public Types

using StartCallback = pw::Function< void(uint32_t session_id, uint32_t resource_id)>
 Callback invoked from the transfer thread when a server transfer starts.
 
using EndCallback = pw::Function< void(uint32_t session_id, Status status)>
 Callback invoked from the transfer thread when a server transfer ends.
 

Public Member Functions

 TransferService (TransferThread &transfer_thread, uint32_t max_window_size_bytes, chrono::SystemClock::duration chunk_timeout=cfg::kDefaultServerTimeout, uint8_t max_retries=cfg::kDefaultMaxServerRetries, uint32_t extend_window_divisor=cfg::kDefaultExtendWindowDivisor, uint32_t max_lifetime_retries=cfg::kDefaultMaxLifetimeRetries)
 
 TransferService (TransferThread &transfer_thread, uint32_t max_window_size_bytes, StartCallback &&on_start, EndCallback &&on_end)
 
 TransferService (const TransferService &)=delete
 
 TransferService (TransferService &&)=delete
 
TransferService & operator= (const TransferService &)=delete
 
TransferService & operator= (TransferService &&)=delete
 
void Read (RawServerReaderWriter &reader_writer)
 
void Write (RawServerReaderWriter &reader_writer)
 
void GetResourceStatus (ConstByteSpan request, rpc::RawUnaryResponder &responder)
 
bool RegisterHandler (Handler &handler)
 
bool UnregisterHandler (Handler &handler)
 
constexpr void set_max_pending_bytes (uint32_t pending_bytes)
 
constexpr void set_max_window_size_bytes (uint32_t max_window_size_bytes)
 
constexpr void set_max_chunk_size_bytes (uint32_t max_chunk_size_bytes)
 
constexpr void set_chunk_timeout (chrono::SystemClock::duration chunk_timeout)
 
constexpr void set_max_retries (uint8_t max_retries)
 
constexpr Status set_extend_window_divisor (uint32_t extend_window_divisor)
 

Constructor & Destructor Documentation

◆ TransferService() [1/2]

pw::transfer::TransferService::TransferService ( TransferThread &  transfer_thread,
uint32_t  max_window_size_bytes,
chrono::SystemClock::duration  chunk_timeout = cfg::kDefaultServerTimeout,
uint8_t  max_retries = cfg::kDefaultMaxServerRetries,
uint32_t  extend_window_divisor = cfg::kDefaultExtendWindowDivisor,
uint32_t  max_lifetime_retries = cfg::kDefaultMaxLifetimeRetries 
)
inline

Initializes a TransferService that can be registered with an RPC server.

The transfer service runs all transfer tasks on transfer_thread, which may be shared between a TransferService and a Client.

Parameters
[in]transfer_threadThread on which transfer events are processed.
[in]max_window_size_bytesMaximum amount of data in bytes to request at a time during a write transfer, unless further restricted by a handler's stream. Should span multiple chunks; the protocol automatically adjusts its window size as a transfer progresses.
[in]chunk_timeoutMaximum time to wait for a chunk before retrying or timing out.
[in]max_retriesMaximum retries for a single chunk before aborting.
[in]extend_window_divisorFractional window position at which a receive transfer extends its window size.
[in]max_lifetime_retriesMaximum total retries allowed across the lifetime of a transfer.

◆ TransferService() [2/2]

pw::transfer::TransferService::TransferService ( TransferThread &  transfer_thread,
uint32_t  max_window_size_bytes,
StartCallback &&  on_start,
EndCallback &&  on_end 
)
inline

Initializes a TransferService with server transfer lifecycle callbacks.

Parameters
[in]transfer_threadThread on which transfer events are processed.
[in]max_window_size_bytesMaximum amount of data in bytes to request at a time during a write transfer.
[in]on_startCallback invoked when a server transfer begins.
[in]on_endCallback invoked when a server transfer completes.
Warning
The on_start and on_end callbacks are invoked from the transfer thread, so the implementation of the callbacks:
  1. Must not attempt to interact with the transfer thread, as doing so can cause deadlock or internal state corruption.
  2. Must return quickly to avoid stalling the transfer thread or the RPC thread.

Member Function Documentation

◆ GetResourceStatus()

void pw::transfer::TransferService::GetResourceStatus ( ConstByteSpan  request,
rpc::RawUnaryResponder &  responder 
)

RPC handler for GetResourceStatus unary requests.

Parameters
[in]requestSerialized ResourceStatusRequest protobuf payload.
[in]responderRaw unary responder used to send the status response.

◆ Read()

void pw::transfer::TransferService::Read ( RawServerReaderWriter &  reader_writer)
inline

RPC handler for bidirectional server read transfers.

Parameters
[in]reader_writerActive raw RPC bidirectional stream.

◆ RegisterHandler()

bool pw::transfer::TransferService::RegisterHandler ( Handler &  handler)
inline

Registers a Handler for a transferable resource with the service.

Blocks until the registration event is processed by the transfer thread.

Parameters
[in]handlerResource handler to register. Must remain valid until unregistered.
Returns
true if the handler was registered, false if queuing the event on the transfer thread timed out.

◆ set_chunk_timeout()

constexpr void pw::transfer::TransferService::set_chunk_timeout ( chrono::SystemClock::duration  chunk_timeout)
inlineconstexpr

Sets the chunk timeout for server transfers.

Parameters
[in]chunk_timeoutDuration to wait for a chunk before retrying or aborting.

◆ set_extend_window_divisor()

constexpr Status pw::transfer::TransferService::set_extend_window_divisor ( uint32_t  extend_window_divisor)
inlineconstexpr

Sets the window divisor at which receive transfers extend their window.

Parameters
[in]extend_window_divisorFractional divisor (must be greater than 1).
Returns

◆ set_max_chunk_size_bytes()

constexpr void pw::transfer::TransferService::set_max_chunk_size_bytes ( uint32_t  max_chunk_size_bytes)
inlineconstexpr

Sets the maximum size for the data payload in a pw_transfer chunk.

Note that the max chunk size must always fit within the transfer thread's chunk buffer.

Parameters
[in]max_chunk_size_bytesMaximum chunk payload size in bytes.

◆ set_max_pending_bytes()

constexpr void pw::transfer::TransferService::set_max_pending_bytes ( uint32_t  pending_bytes)
inlineconstexpr
Deprecated:
Use set_max_window_size_bytes() instead.
Parameters
[in]pending_bytesMaximum receive window size in bytes.

◆ set_max_retries()

constexpr void pw::transfer::TransferService::set_max_retries ( uint8_t  max_retries)
inlineconstexpr

Sets the maximum number of retries per chunk on the server.

Parameters
[in]max_retriesMaximum retries per chunk.

◆ set_max_window_size_bytes()

constexpr void pw::transfer::TransferService::set_max_window_size_bytes ( uint32_t  max_window_size_bytes)
inlineconstexpr

Sets the maximum receive window size in bytes for write transfers.

Parameters
[in]max_window_size_bytesMaximum receive window size in bytes.

◆ UnregisterHandler()

bool pw::transfer::TransferService::UnregisterHandler ( Handler &  handler)
inline

Unregisters a previously registered Handler from the service.

Blocks until the handler is fully cleaned up on the transfer thread.

Parameters
[in]handlerResource handler to unregister.
Returns
true if the handler was unregistered, false if queuing the event on the transfer thread timed out.

◆ Write()

void pw::transfer::TransferService::Write ( RawServerReaderWriter &  reader_writer)
inline

RPC handler for bidirectional server write transfers.

Parameters
[in]reader_writerActive raw RPC bidirectional stream.
The documentation for this class was generated from the following file: