Struct plumber_rs::pipe::Pipe

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

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

Methods

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.

unsafe fn initializer(&self) -> Initializer

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

Determines if this Reader can work with buffers of uninitialized memory.

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

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

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

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

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

Read the exact number of bytes required to fill buf.

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

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an [Iterator] over its bytes.

fn chars(self) -> Chars<Self>

Deprecated since 1.27.0

: Use str::from_utf8 instead: https://doc.rust-lang.org/nightly/std/str/struct.Utf8Error.html#examples

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

the semantics of a partial read/write of where errors happen is currently unclear and may change

Transforms this Read instance to an [Iterator] over [char]s.

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

Creates an adaptor which will chain this stream with another.

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

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

impl<ST> Write for Pipe<ST>

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

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

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

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

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

Attempts to write an entire buffer into this write.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

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

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

Creates a "by reference" adaptor for this instance of Write.