Struct embassy_sync::pipe::Pipe

source ·
pub struct Pipe<M, const N: usize>
where M: RawMutex,
{ /* private fields */ }
Expand description

A bounded byte-oriented pipe for communicating between asynchronous tasks with backpressure.

The pipe will buffer up to the provided number of bytes. Once the buffer is full, attempts to write new bytes will wait until buffer space is freed up.

All data written will become available in the same order as it was written.

Implementations§

source§

impl<M, const N: usize> Pipe<M, N>
where M: RawMutex,

source

pub const fn new() -> Self

Establish a new bounded pipe. For example, to create one with a NoopMutex:

use embassy_sync::pipe::Pipe;
use embassy_sync::blocking_mutex::raw::NoopRawMutex;

// Declare a bounded pipe, with a buffer of 256 bytes.
let mut pipe = Pipe::<NoopRawMutex, 256>::new();
source

pub fn split(&mut self) -> (Reader<'_, M, N>, Writer<'_, M, N>)

Split this pipe into a BufRead-capable reader and a writer.

The reader and writer borrow the current pipe mutably, so it is not possible to use it directly while they exist. This is needed because implementing BufRead requires there is a single reader.

The writer is cloneable, the reader is not.

source

pub fn write<'a>(&'a self, buf: &'a [u8]) -> WriteFuture<'a, M, N>

Write some bytes to the pipe.

This method writes a nonzero amount of bytes from buf into the pipe, and returns the amount of bytes written.

If it is not possible to write a nonzero amount of bytes because the pipe’s buffer is full, this method will wait until it isn’t. See try_write for a variant that returns an error instead of waiting.

It is not guaranteed that all bytes in the buffer are written, even if there’s enough free space in the pipe buffer for all. In other words, it is possible for write to return without writing all of buf (returning a number less than buf.len()) and still leave free space in the pipe buffer. You should always write in a loop, or use helpers like write_all from the embedded-io crate.

source

pub async fn write_all(&self, buf: &[u8])

Write all bytes to the pipe.

This method writes all bytes from buf into the pipe

source

pub fn try_write(&self, buf: &[u8]) -> Result<usize, TryWriteError>

Attempt to immediately write some bytes to the pipe.

This method will either write a nonzero amount of bytes to the pipe immediately, or return an error if the pipe is empty. See write for a variant that waits instead of returning an error.

source

pub fn read<'a>(&'a self, buf: &'a mut [u8]) -> ReadFuture<'a, M, N>

Read some bytes from the pipe.

This method reads a nonzero amount of bytes from the pipe into buf and returns the amount of bytes read.

If it is not possible to read a nonzero amount of bytes because the pipe’s buffer is empty, this method will wait until it isn’t. See try_read for a variant that returns an error instead of waiting.

It is not guaranteed that all bytes in the buffer are read, even if there’s enough space in buf for all. In other words, it is possible for read to return without filling buf (returning a number less than buf.len()) and still leave bytes in the pipe buffer. You should always read in a loop, or use helpers like read_exact from the embedded-io crate.

source

pub fn try_read(&self, buf: &mut [u8]) -> Result<usize, TryReadError>

Attempt to immediately read some bytes from the pipe.

This method will either read a nonzero amount of bytes from the pipe immediately, or return an error if the pipe is empty. See read for a variant that waits instead of returning an error.

source

pub fn clear(&self)

Clear the data in the pipe’s buffer.

source

pub fn is_full(&self) -> bool

Return whether the pipe is full (no free space in the buffer)

source

pub fn is_empty(&self) -> bool

Return whether the pipe is empty (no data buffered)

source

pub fn capacity(&self) -> usize

Total byte capacity.

This is the same as the N generic param.

source

pub fn len(&self) -> usize

Used byte capacity.

source

pub fn free_capacity(&self) -> usize

Free byte capacity.

This is equivalent to capacity() - len()

Trait Implementations§

source§

impl<M: RawMutex, const N: usize> ErrorType for &Pipe<M, N>

§

type Error = Infallible

Error type of all the IO operations on this type.
source§

impl<M: RawMutex, const N: usize> ErrorType for Pipe<M, N>

§

type Error = Infallible

Error type of all the IO operations on this type.
source§

impl<M: RawMutex, const N: usize> Read for &Pipe<M, N>

source§

async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>

Read some bytes from this source into the specified buffer, returning how many bytes were read. Read more
source§

async fn read_exact( &mut self, buf: &mut [u8] ) -> Result<(), ReadExactError<Self::Error>>

Read the exact number of bytes required to fill buf. Read more
source§

impl<M: RawMutex, const N: usize> Read for Pipe<M, N>

source§

async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>

Read some bytes from this source into the specified buffer, returning how many bytes were read. Read more
source§

async fn read_exact( &mut self, buf: &mut [u8] ) -> Result<(), ReadExactError<Self::Error>>

Read the exact number of bytes required to fill buf. Read more
source§

impl<M: RawMutex, const N: usize> Write for &Pipe<M, N>

source§

async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

Write a buffer into this writer, returning how many bytes were written. Read more
source§

async fn flush(&mut self) -> Result<(), Self::Error>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.
source§

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

Write an entire buffer into this writer. Read more
source§

impl<M: RawMutex, const N: usize> Write for Pipe<M, N>

source§

async fn write(&mut self, buf: &[u8]) -> Result<usize, Self::Error>

Write a buffer into this writer, returning how many bytes were written. Read more
source§

async fn flush(&mut self) -> Result<(), Self::Error>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.
source§

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

Write an entire buffer into this writer. Read more

Auto Trait Implementations§

§

impl<M, const N: usize> !Freeze for Pipe<M, N>

§

impl<M, const N: usize> !RefUnwindSafe for Pipe<M, N>

§

impl<M, const N: usize> Send for Pipe<M, N>
where M: Send,

§

impl<M, const N: usize> Sync for Pipe<M, N>
where M: Sync,

§

impl<M, const N: usize> Unpin for Pipe<M, N>
where M: Unpin,

§

impl<M, const N: usize> UnwindSafe for Pipe<M, N>
where M: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.