Struct MutexUnblockHandle

pub struct MutexUnblockHandle<T: 'static + ?Sized>(/* private fields */);

Wrapper type for making an async-locked blocking::Unblock Stdio stream. Parameter is one of the io::Stdout/io::Stderr/io::Stdin types plus any blocking::Unblock or other wrappers. This holds a static reference to an internal shared mutex. Some things may need outer BufRead/BufWrite attachments to make it match the equivalent sync trait impls - this is done as much as possible to match the stdio inside the stdlib.

Unlike the std::io unlocked-handles, this does not implement the various futures_lite::io traits. You need to use MutexUnblockHandle::lock or other locking methods to get access to a handle which can be used with these traits. Unlike the Standard Library, these handles are not re-entrant, which means that attempting to lock them in some inner future while the outer lock is held will cause a deadlock.

An important note is that Unblock implements Unpin unconditionally. This makes it easy to make generic implementations that will work nicely.

Implementations

impl<T: ?Sized> MutexUnblockHandle<T>

pub async fn lock(&self) -> MutexUnblockGuard<'static, T>

Locks this handle asynchronously.

Examples found in repository

examples/helloworld-noflush.rs (line 10)

fn main() -> std::io::Result<()> {
    futures_lite::future::block_on(async {
        let mut stdout_handle = astdio::stdout().lock().await;
        // Note how we do not need to bother flushing this - it's auto-handled by the crate
        stdout_handle.write_all(b"Hello world!\n").await
    })
}

pub async fn lock_into_sync(&self) -> BlockOn<MutexUnblockGuard<'static, T>>

Lock this handle, but produce something that implements the synchronous std::io traits.

Examples found in repository

examples/helloworld-re-syncify.rs (line 9)

fn main() -> std::io::Result<()> {
    futures_lite::future::block_on(async {
        use std::io::Write;
        let mut stdout_sync_handle = astdio::stdout().lock_into_sync().await;
        // Note how we do not need to bother flushing this - it's auto-handled by the crate, and is
        // basically just println! here.
        //
        // However - in reality, this is not ideal because `BlockOn` uses
        // futures_lite::future::block_on internally - it's better to use the async traits
        // internally where possible if you're inside a future like this.
        writeln!(stdout_sync_handle, "Hello world, from sync!")
    })
}

pub fn lock_blocking(&self) -> MutexUnblockGuard<'static, T>

Lock this handle in a sync context. Do not call in an async context or risk deadlocks!.

pub fn lock_blocking_into_sync(&self) -> BlockOn<MutexUnblockGuard<'static, T>>

Lock this handle in a sync context, but producing something that implements the synchronous std::io traits.

Do not call in an async context or risk deadlocks!.

pub fn try_lock(&self) -> Option<MutexUnblockGuard<'static, T>>

Attempt to lock this handle if you can

pub fn try_lock_into_sync( &self, ) -> Option<BlockOn<MutexUnblockGuard<'static, T>>>

Attempt to lock this handle and wrap it in something that can be used with the synchronous std::io traits.

Trait Implementations

impl<T: Debug + 'static + ?Sized> Debug for MutexUnblockHandle<T>

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

Formats the value using the given formatter.