Trait Transform

pub trait Transform {
    // Required method
    fn transform(
        self: Pin<&mut Self>,
        buf: &mut TransformBuf<'_, '_>,
    ) -> Result<()>;

    // Provided method
    fn poll_finish(
        self: Pin<&mut Self>,
        cx: &mut Context<'_>,
        buf: &mut ReadBuf<'_>,
    ) -> Poll<Result<()>> { ... }
}

Chainable, in-place, streaming data transformer.

Transform operates on TransformBufs similar to how AsyncRead operats on ReadBuf. A Transform sits somewhere in a chain of transforming readers. The head (most upstream part) of the chain is always an AsyncRead: the data source. The tail (all downstream parts) is composed only of other Transforms:

                         downstream --->
 AsyncRead | Transform | .. | Transform
<---- upstream

When the upstream source makes data available, the Transform::transform() method is called. Transforms may obtain the subset of the filled section added by an upstream data source with TransformBuf::fresh(). They may modify this data at will, potentially changing the size of the filled section. For example, TransformBuf::spoil() “removes” all of the fresh data, and TransformBuf::fresh_mut() can be used to modify the data in-place.

Additionally, new data may be added in-place via the traditional approach: write to (or overwrite) the initialized section of the buffer and mark it as filled. All of the remaining filled data will be passed to downstream transforms as “fresh” data. To add data to the end of the (potentially rewritten) stream, the Transform::poll_finish() method can be implemented.

Required Methods

fn transform(self: Pin<&mut Self>, buf: &mut TransformBuf<'_, '_>) -> Result<()>

Called when data is read from the upstream source. For any given fresh data, this method is called only once. TransformBuf::fresh() is guaranteed to contain at least one byte.

While this method is not async (it does not return Poll), it is nevertheless executed in an async context and should respect all such restrictions including not blocking.

Provided Methods

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

Called when the upstream is finished, that is, it has no more data to fill. At this point, the transform becomes an async reader. This method thus has identical semantics to AsyncRead::poll_read(). This method may never be called if the upstream does not finish.

The default implementation returns Poll::Ready(Ok(())).

Implementors