Struct Session 

pub struct Session { /* private fields */ }

Available on crate feature tokio only.

A managed asynchronous pseudoconsole session.

Session::wait drains and discards output concurrently, while Session::collect_output retains it. Use Session::into_parts for interactive or externally coordinated I/O.

The managed child always has kill-on-drop and Job kill-on-close enabled. Dropping an unfinished Session therefore terminates the root process and every descendant. The same guarantee applies when a future that owns the session—most notably Session::wait or Session::collect_output—is cancelled.

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 async fn wait(self) -> Result<ExitStatus>

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

Output and the root wait are polled concurrently. 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. Input shutdown is session teardown, not an ordinary stdin EOF signal.

Cancel safety

The future owns the session. Cancelling it drops the managed child and terminates the process tree.

Errors

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

pub async 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 and the root wait are polled concurrently. Once the root 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.

Cancel safety

The future owns the whole session. Cancelling it drops the managed child first and terminates the process tree.

Errors

Returns an error if 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 AsyncRead for Session

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_>, ) -> Poll<Result<()>>

Attempts to read from the AsyncRead into buf.

impl AsyncWrite for Session

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8], ) -> Poll<Result<usize>>

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Result<()>>

Attempts to flush the object, ensuring that any buffered data reach their destination.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Initiates or attempts to shut down this writer, returning success when the I/O connection has completely shut down.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>], ) -> Poll<Result<usize, Error>>

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

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl Debug for Session

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

Formats the value using the given formatter.