Struct EndpointWrite 

pub struct EndpointWrite<EpType: BulkOrInterrupt> { /* private fields */ }

Wrapper for a Bulk or Interrupt OUT Endpoint that manages transfers to provide a higher-level buffered API.

Most of the functionality of this type is provided through standard IO traits; you’ll want to use one of the following:

• std::io::Write for blocking IO.
• With the tokio cargo feature, tokio::io::AsyncWrite. Tokio also provides AsyncWriteExt with additional methods.
• With the smol cargo feature, futures_io::AsyncWrite for async IO. futures_lite provides AsyncWriteExt with additional methods.

Written data is buffered and may not be sent until the buffer is full or submit / submit_end or flush / flush_end are called.

Implementations

impl<EpType: BulkOrInterrupt> EndpointWrite<EpType>

pub fn new(endpoint: Endpoint<EpType, Out>, transfer_size: usize) -> Self

Create a new EndpointWrite wrapping the given endpoint.

The transfer_size parameter is the size of the buffer passed to the OS for each transfer. It will be rounded up to the next multiple of the endpoint’s max packet size. Data will be buffered and sent in chunks of this size, unless flush or submit are called to force sending a partial buffer immediately.

pub fn set_num_transfers(&mut self, num_transfers: usize)

Set the maximum number of transfers that can be queued with the OS before backpressure is applied.

If more than num_transfers transfers are pending, calls to write will block or async methods will return Pending until a transfer completes.

Panics if num_transfers is zero.

pub fn with_num_transfers(self, num_transfers: usize) -> Self

Set the maximum number of transfers that can be queued with the OS before backpressure is applied.

See Self::set_num_transfers – this is for method chaining with EndpointWrite::new().

pub fn set_write_timeout(&mut self, timeout: Duration)

Set the timeout for a transfer in the blocking write APIs.

This affects the std::io::Write implementation only, and not the async trait implementations.

When a timeout occurs, writing new data fails but transfers for previously-written data are not cancelled. The data passed in the failed write call is not written to the buffer, though note that functions like write_all that call write multiple times may have successfully written some of the data.

pub fn with_write_timeout(self, timeout: Duration) -> Self

Set the timeout for an individual transfer for the blocking write APIs.

See Self::set_write_timeout – this is for method chaining with EndpointWrite::new().

pub fn into_inner(self) -> Endpoint<EpType, Out>

Destroy this EndpointWrite and return the underlying Endpoint.

Any pending transfers are not cancelled.

pub fn submit(&mut self)

Submit any buffered data to the OS immediately.

This submits the current buffer even if it not full, but does not wait for the transfer to complete or confirm that it was successful (see Write::flush). If the buffer is empty, this does nothing.

pub fn submit_end(&mut self)

Submit any buffered data to the OS immediately, terminating with a short or zero-length packet.

Some USB protocols use packets shorter than the endpoint’s max packet size as a delimiter marking the end of a message. This method forces such a delimiter by adding a zero-length packet if the current buffer is a multiple of the endpoint’s max packet size.

This does not wait for the transfer to complete or confirm that it was successful (see Self::flush_end). If the buffer is empty, this sends a zero-length packet.

pub fn flush_end(&mut self) -> Result<(), Error>

Submit any buffered data immediately, terminating with a short or zero-length packet, and wait for all pending transfers to complete or fail.

pub async fn flush_end_async(&mut self) -> Result<(), Error>

Submit any buffered data immediately, terminating with a short or zero-length packet, and wait for all pending transfers to complete.

Async version of Self::flush_end.

Trait Implementations

impl<EpType: BulkOrInterrupt> AsyncWrite for EndpointWrite<EpType>

Available on crate feature smol only.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Write data to the endpoint.

Data is buffered and not written until the buffer is full or submit() or flush() are called. Writing will return Poll::Pending if there are already too many transfers pending, as configured by set_num_transfers.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Submit any buffered data immediately and wait for all pending transfers to complete or fail.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Attempt to write bytes from bufs into the object using vectored IO operations.

impl<EpType: BulkOrInterrupt> AsyncWrite for EndpointWrite<EpType>

Available on crate feature tokio only.

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Write data to the endpoint.

Data is buffered and not written until the buffer is full or submit() or flush() are called. Writing will return Poll::Pending if there are already too many transfers pending, as configured by set_num_transfers.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Submit any buffered data immediately and wait for all pending transfers to complete or fail.

fn poll_shutdown( self: Pin<&mut Self>, cx: &mut Context<'_>, ) -> Poll<Result<(), Error>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl<EpType: BulkOrInterrupt> Write for EndpointWrite<EpType>

fn write(&mut self, src: &[u8]) -> Result<usize>

Write data to the endpoint.

Data is buffered and not written until the buffer is full or submit() or flush() are called. Writing will block if there are already too many transfers pending, as configured by set_num_transfers.

fn flush(&mut self) -> Result<()>

Submit any buffered data immediately and wait for all pending transfers to complete or fail.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.