Struct embassy_sync::pipe::Pipe

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

A bounded pipe for communicating between asynchronous tasks with backpressure.

The pipe will buffer up to the provided number of messages. Once the buffer is full, attempts to write new messages will wait until a message is read from the pipe.

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

Implementations

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

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();

pub fn writer(&self) -> Writer<'_, M, N>

Get a writer for this pipe.

pub fn reader(&self) -> Reader<'_, M, N>

Get a reader for this pipe.

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

Write a value, waiting until there is capacity.

Writeing completes when the value has been pushed to the pipe’s queue. This doesn’t mean the value has been read yet.

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

Attempt to immediately write a message.

This method differs from write by returning immediately if the pipe’s buffer is full, instead of waiting.

Errors

If the pipe capacity has been reached, i.e., the pipe has n buffered values where n is the argument passed to Pipe, then an error is returned.

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

Receive the next value.

If there are no messages in the pipe’s buffer, this method will wait until a message is written.

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

Attempt to immediately read a message.

This method will either read a message from the pipe immediately or return an error if the pipe is empty.

pub fn clear(&self)

Clear the data in the pipe’s buffer.

pub fn is_full(&self) -> bool

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

pub fn is_empty(&self) -> bool

Return whether the pipe is empty (no data buffered)

pub fn capacity(&self) -> usize

Total byte capacity.

This is the same as the N generic param.

pub fn len(&self) -> usize

Used byte capacity.

pub fn free_capacity(&self) -> usize

Free byte capacity.

This is equivalent to capacity() - len()

Trait Implementations

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

type Error = Infallible

Error type of all the IO operations on this type.

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

type Error = Infallible

Error type of all the IO operations on this type.

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

type ReadFuture<'a>
where
    Self: 'a = impl Future<Output = Result<usize, <&Pipe<M, N> as Io>::Error>> + 'a

Future returned by read.

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

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

fn read_exact(
    &'a mut self,
    buf: &'a mut [u8]
) -> impl Future<Output = Result<(), ReadExactError<Self::Error>>> + 'a

Read the exact number of bytes required to fill buf.

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

type ReadFuture<'a>
where
    Self: 'a = impl Future<Output = Result<usize, <Pipe<M, N> as Io>::Error>> + 'a

Future returned by read.

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

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

fn read_exact(
    &'a mut self,
    buf: &'a mut [u8]
) -> impl Future<Output = Result<(), ReadExactError<Self::Error>>> + 'a

Read the exact number of bytes required to fill buf.

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

type WriteFuture<'a>
where
    Self: 'a = impl Future<Output = Result<usize, <&Pipe<M, N> as Io>::Error>> + 'a

Future returned by write.

fn write<'a>(&'a mut self, buf: &'a [u8]) -> Self::WriteFuture<'a>

Write a buffer into this writer, returning how many bytes were written.

type FlushFuture<'a>
where
    Self: 'a = impl Future<Output = Result<(), <&Pipe<M, N> as Io>::Error>> + 'a

Future returned by flush.

fn flush<'a>(&'a mut self) -> Self::FlushFuture<'a>

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

fn write_all(
    &'a mut self,
    buf: &'a [u8]
) -> impl Future<Output = Result<(), Self::Error>> + 'a

Write an entire buffer into this writer.

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

type WriteFuture<'a>
where
    Self: 'a = impl Future<Output = Result<usize, <Pipe<M, N> as Io>::Error>> + 'a

Future returned by write.

fn write<'a>(&'a mut self, buf: &'a [u8]) -> Self::WriteFuture<'a>

Write a buffer into this writer, returning how many bytes were written.

type FlushFuture<'a>
where
    Self: 'a = impl Future<Output = Result<(), <Pipe<M, N> as Io>::Error>> + 'a

Future returned by flush.

fn flush<'a>(&'a mut self) -> Self::FlushFuture<'a>

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

fn write_all(
    &'a mut self,
    buf: &'a [u8]
) -> impl Future<Output = Result<(), Self::Error>> + 'a

Write an entire buffer into this writer.