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