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,
impl<M, const N: usize> Pipe<M, N>where
M: RawMutex,
sourcepub const fn new() -> Self
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();
sourcepub fn split(&mut self) -> (Reader<'_, M, N>, Writer<'_, M, N>)
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.
sourcepub fn write<'a>(&'a self, buf: &'a [u8]) -> WriteFuture<'a, M, N> ⓘ
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.
sourcepub async fn write_all(&self, buf: &[u8])
pub async fn write_all(&self, buf: &[u8])
Write all bytes to the pipe.
This method writes all bytes from buf
into the pipe
sourcepub fn try_write(&self, buf: &[u8]) -> Result<usize, TryWriteError>
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.
sourcepub fn read<'a>(&'a self, buf: &'a mut [u8]) -> ReadFuture<'a, M, N> ⓘ
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.
sourcepub fn try_read(&self, buf: &mut [u8]) -> Result<usize, TryReadError>
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.
sourcepub fn free_capacity(&self) -> usize
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>
impl<M: RawMutex, const N: usize> ErrorType for &Pipe<M, N>
§type Error = Infallible
type Error = Infallible
source§impl<M: RawMutex, const N: usize> ErrorType for Pipe<M, N>
impl<M: RawMutex, const N: usize> ErrorType for Pipe<M, N>
§type Error = Infallible
type Error = Infallible
source§impl<M: RawMutex, const N: usize> Read for &Pipe<M, N>
impl<M: RawMutex, const N: usize> Read for &Pipe<M, N>
source§async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>
async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>
source§async fn read_exact(
&mut self,
buf: &mut [u8]
) -> Result<(), ReadExactError<Self::Error>>
async fn read_exact( &mut self, buf: &mut [u8] ) -> Result<(), ReadExactError<Self::Error>>
buf
. Read moresource§impl<M: RawMutex, const N: usize> Read for Pipe<M, N>
impl<M: RawMutex, const N: usize> Read for Pipe<M, N>
source§async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>
async fn read(&mut self, buf: &mut [u8]) -> Result<usize, Self::Error>
source§async fn read_exact(
&mut self,
buf: &mut [u8]
) -> Result<(), ReadExactError<Self::Error>>
async fn read_exact( &mut self, buf: &mut [u8] ) -> Result<(), ReadExactError<Self::Error>>
buf
. Read more