Struct Session 

pub struct Session { /* private fields */ }

Available on crate feature blocking only.

A managed blocking pseudoconsole session.

Reading and writing delegate to the session’s output and input streams. Session::wait drains and discards output concurrently, while Session::collect_output retains it. Use Session::into_parts for interactive or externally coordinated I/O.

Dropping an unfinished managed session closes its kill-on-close Job and terminates the root process together with every descendant.

Implementations

impl Session

pub const fn id(&self) -> u32

Returns the root process identifier.

pub fn try_wait(&mut self) -> Result<Option<ExitStatus>>

Returns the exit status when the root process has already exited.

Errors

Returns an error with crate::ErrorKind::Wait if Windows cannot query the process.

pub fn kill(&mut self) -> Result<()>

Terminates the root process and every descendant in its Job.

Errors

Returns an error with crate::ErrorKind::Kill if Windows cannot terminate the Job.

pub fn resize(&self, size: Size) -> Result<()>

Resizes the pseudoconsole.

Errors

Returns an error with crate::ErrorKind::Resize if the backend rejects the size, or an std::io::ErrorKind::NotConnected source after teardown.

pub fn size(&self) -> Size

Returns the last successfully applied terminal size.

pub fn clear(&self) -> Result<()>

Clears the pseudoconsole screen and scrollback.

Errors

Returns an error with crate::ErrorKind::UnsupportedFeature when the backend has no clear operation, crate::ErrorKind::Clear on backend failure, or an std::io::ErrorKind::NotConnected source after teardown.

pub fn supports_clear(&self) -> bool

Returns whether this backend supports clearing the console.

pub fn wait(self) -> Result<ExitStatus>

Waits for the root process while draining and discarding VT output.

Output is drained on a dedicated thread, so a child that writes more than the pipe capacity cannot deadlock. Once the root status is saved, remaining descendants are terminated and the teardown tail is drained to EOF without allocating an output-sized buffer.

Terminal input remains open until the root exits. Closing input is session teardown, not an ordinary stdin EOF signal.

Errors

Returns an error if the reader thread cannot be created, output cannot be drained, the root process status cannot be obtained, or the remaining process tree cannot be terminated.

pub fn collect_output(self) -> Result<SessionOutput>

Waits for the root process while collecting the remaining VT output.

Collection leaves terminal input open until the root exits, so the caller must first arrange for the program to finish through its own protocol. ConPTY has no ordinary stdin half-close: closing its input is terminal teardown and could replace the real exit status.

Output is drained on a dedicated thread while the root runs. Once its status is captured, any descendants still in the managed Job are terminated, terminal input is retired, and the reader drains the teardown tail to EOF. This gives released and legacy ConPTY backends the same finite, root-bounded completion rule.

Bytes already read from this Session are not included.

Collection is unbounded and may allocate as much memory as the child writes. Use Session::wait when output is unnecessary, or Session::into_parts to process it as a stream.

Examples

use conpty_oxide::blocking::Command;

let output = Command::new("cmd.exe")
    .args(["/d", "/c", "echo", "hello"])
    .spawn()?
    .collect_output()?;
assert!(output.status().success());
print!("{}", String::from_utf8_lossy(output.as_bytes()));

Errors

Returns an error if the reader thread cannot be created, output cannot be drained, the root process status cannot be obtained, or the remaining process tree cannot be terminated.

pub fn into_parts(self) -> SessionParts

Decomposes this session for interactive or externally coordinated I/O.

Splitting changes ownership only: root exit still terminates remaining descendants and advances output to EOF. It does not detach the session.

Trait Implementations

impl Debug for Session

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Read for Session

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<'_, u8>) -> 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<'_, u8>, ) -> 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.

fn read_le<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

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

Read and return a type (e.g. an integer) in little-endian order.

fn read_be<T>(&mut self) -> Result<T, Error>

where T: FromEndianBytes, Self: Sized,

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

Read and return a type (e.g. an integer) in big-endian order.

impl Write for Session

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.