Struct Pipe 

pub struct Pipe<ST> { /* private fields */ }

The Rust wrapper of a Plumber pipe port.

In Plumber, we use a integer as identifer of the pipe port when we write the servlet. This is called pipe_t in the C API. However, In rust, we implemented the Pipe object which allows us directly read and write the pipe with the object.

• ST: The type of the state. This is only used when we want to implement a stateful port

Implementations

impl<ST> Pipe<ST>

pub fn as_bufreader(&self) -> BufReader<PipeRef>

Get a std::io::BufReader object from current pipe port.

This is useful when we want to do text IO to the pipe

Returns the ownership of the newly created reader

pub fn as_descriptor(&self) -> PipeDescriptor

Get the actual pipe descriptor managed by this pipe object

Return the pipe descriptor

pub fn define( name: &str, flags: PipeFlags, type_expr: Option<&str>, ) -> Option<Pipe<ST>>

Define a new pipe port for the current servlet.

This function creates the pipe port in Rust as well as Plumber framework. Since Plumber only allows pipe port declaration during the initialization stage, so if this function is called from execution or cleanup stage, the result will be a failure.

• name The name of the port. It will be used for the dataflow graph construction
• flags The initial pipe flag of this pipe.
• type_expr The type expression for the protocol of this pipe port. See Plumber’s protocol typing documentations for detail.

Returns either None on creating failure or Some of ownership of the newly created pipe object

pub fn eof(&mut self) -> Option<bool>

Check if the pipe contains no more data.

This is meaningful only when we are currently executing some execution task with this servlet. Which means it only can be called from either exec and async_init, async_cleanup stage of a servlet. Otherwise it will returns a failure.

The EOF function in Plumber defines a little bit different from normal EOF. It indicates if it’s possible to have further data.

If this function returns true, it’s possible we have more data in the furture, but it’s not means we current have data to read. It’s also possible that there’s no more data but the framework is not able to realize that currently.

If this function returns false, it indicates there are definitely no more data can be read from this port.

Returns either None on error case or the check result

pub fn flags(&mut self) -> Option<PipeFlags>

Get the runtime flags of this port.

Since Plumber allows the pipe flag to be changed inside the execution stage. So this function is used to check what is the current pipe flags.

Return either None on error or the current pipe flag

pub fn check_flag(&mut self, flag: PipeFlags) -> Option<bool>

Test if the pipe port has the required pipe flags been set.

Returns either None on error or the current pipe flag

pub fn set_flags(&mut self, flag: PipeFlags) -> Option<()>

Set the runtime flags of the pipe port

• flag The pipe flag we want to add to the pipe

Return the operation result None indicates failure, Some Indicates success

pub fn clear_flags(&mut self, flag: PipeFlags) -> Option<()>

Unset the runtime flags for a pipe port

• flag The pipe flag we want to unset

Return the operation result None indicates failure, Some for success

pub fn get_state<'a>(&mut self) -> Option<&'a ST>

Get the associated state for current pipe resource.

Plumber allows stateful pipe port, which means in the execution state, the servlet can attach a state object with the pipe resource. After the state is attached, and PIPE_PERSIST flag is set, the framework will manage the state for the servlet.

When the servlet is active again due to the same communication resource, the object can be retrieved.

Returns the retrieved reference to the Obect.

Note: Plumber framework always manage the ownership of the pushed state objects. So in this function only a reference will be returned. All the memory management is done by Plumber rather than Rust.

pub fn push_state(&mut self, obj: Box<ST>) -> Option<()>

Push the state object to the pipe. This will attach the state to the pipe communication resources.

See the documentation of get_state for more detailed description of state mechanism.

• obj: The box that contains the ownership of the state we want to push

Return The operation result.

Note: This function always takes the ownership of the state object, even if it returns a failure.

Trait Implementations

impl<ST> Read for Pipe<ST>

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

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

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Reads all bytes until EOF in this source, appending them to buf.

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

Reads the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Reads the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

fn read_array<const N: usize>(&mut self) -> Result<[u8; N], Error>

where Self: Sized,

🔬This is a nightly-only experimental API. (read_array)

Read and return a fixed array of bytes from this source.

impl<ST> Write for Pipe<ST>

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

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

fn flush(&mut self) -> Result<()>

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

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

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

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, args: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.