Unified async alignment reader/writer

[mbhall88]

I use the noodles_util::alignment readers and writers a lot. How easy would it be to implement an aync version of this transparent reader/writer?

If this is something you think would be reasonably straightforward I would be willing to draft a PR with some guidance on where to start.

[zaeleus]

If this is something you think would be reasonably straightforward I would be willing to draft a PR with some guidance on where to start.

Yes, give it a go! It's a loaded issue, consisting of four parts:

• the async alignment reader (Add async alignment reader #288),
• its builder (Add async alignment reader #288),
• the async alignment writer (Add async alignment writer #292),
• and also its builder (Add async alignment writer #292).

I recommend focusing on each individually, submitting a patch for review per part. It is a fair amount of work/code, but don't feel obligated to complete it all.

For the first part, I normalized the alignment format async reader methods, so you shouldn't have any problems outside of util. I also added an async variant format reader and builder to use as a reference.

Here are some instructions on how to proceed with the reader:

1. Add the alignment format dependencies (SAM, BAM, and CRAM) to the async feature in noodles-util/Cargo.toml. These use the optional dependency feature syntax.

   noodles/noodles-util/Cargo.toml

   Lines 23 to 28 in 782d892

   	async = [
   	"dep:futures",
   	"dep:tokio",
   	"noodles-bcf?/async",
   	"noodles-bgzf?/async",
   	"noodles-vcf?/async",

2. Add the modules.

   • noodles-util/src/alignment/async.rs (example)
   • noodles-util/src/alignment/async/io.rs (example)
   • noodles-util/src/alignment/async/io/reader.rs (example)

3. Implement Reader<R>. This will not use the I/O trait approach like the blocking version. Since well know all the format variants, use an enum instead. Feel free to start with the following scaffold.

//! Async alignment reader.

/// An async alignment reader.
pub enum Reader<R> {
    /// SAM.
    Sam(sam::r#async::io::Reader<R>),
    /// BAM.
    Bam(bam::r#async::io::Reader<R>),
    /// CRAM.
    Cram(cram::r#async::io::Reader<R>),
}

impl<R> Reader<R>
where
    R: AsyncBufRead + Unpin,
{
    /// Reads the SAM header.
    pub async fn read_header(&mut self) -> io::Result<sam::Header> {
        todo!()
    }

    /// Returns an iterator over records starting from the current stream position.
    pub fn records<'r, 'h: 'r>(
        &'r mut self,
        header: &'h sam::Header,
    ) -> impl Stream<Item = io::Result<Box<dyn sam::alignment::Record>>> + 'r {
        todo!()
    }
}

Let me know if you have any further questions or issues.

[mbhall88]

I wonder if it also makes sense to add an asynchronous version of an indexed reader? Given the implementations on SAM/BAM/CRAM are !Send I guess we probably need that auto trait before we could do that? And I hope I understand this correctly, we might also want Sync as currently it is !Sync, though my understanding is it doesn't have to be Sync to be used in async code correct?

[zaeleus]

I wonder if it also makes sense to add an asynchronous version of an indexed reader?

Tracked in #296.