tokio-serial icon indicating copy to clipboard operation
tokio-serial copied to clipboard

Document the difference between master & slave in Serial::pair()

Open SillyFreak opened this issue 5 years ago • 0 comments

I've spent two or three hours trying to understand why a test case wouldn't work, it went roughly like this:

#[tokio::test]
async fn test_serial() -> Result<(), Box<dyn Error>> {
    let (mut rep, mut req) = Serial::pair()?;

    let f = tokio::spawn(async move {
        let mut buffer = [0u8; 1];
        rep.read_exact(&mut buffer).await?;

        let [command] = buffer;
        assert_eq!(command, 1);

        rep.write_all(&buffer).await?;
        rep.shutdown().await?;

        io::Result::<_>::Ok(())
    });

    req.write_all(&[1]).await?;

    let mut buffer = [0u8; 1];
    req.read_exact(&mut buffer).await?;

    let [response] = buffer;
    assert_eq!(response, 1);

    // may be a join error, or an IO error from inside the task
    f.await??;

    Ok(())
}

Turns out, switching req and rep at the beginning is the solution. The documentation mentions that

Attempting any IO or parameter settings on the slave tty after the master tty is closed will return errors.

but doesn't explain which one is the master and which the slave; at the time I had written the test case to the extent that the error occurred, I had forgotten that there was a distinction between master and slave I hadn't understood sufficiently. Linking the mio docs or adding one or two sentences to the docs would help here, I think.

SillyFreak avatar Dec 01 '19 14:12 SillyFreak