Struct glommio::io::DmaStreamReader

pub struct DmaStreamReader { /* fields omitted */ }

Provides linear access to a DmaFile. The DmaFile is a convenient way to manage a file through Direct I/O, but its interface is conductive to random access, as a position must always be specified.

In situations where the file must be scanned linearly - either because a large chunk is to be read or because we are scanning the whole file, it may be more convenient to use a linear scan API.

The DmaStreamReader implements AsyncRead, which can offer the user with a convenient way of issuing reads. However note that this mandates a copy between the Dma Buffer used to read the file contents and the user-specified buffer.

To avoid that copy the DmaStreamReader provides the get_buffer_aligned method which exposes the buffer as a byte slice. Different situations will call for different APIs to be used.

Implementations

impl DmaStreamReader

pub async fn close(self) -> Result<(), ()>

Closes this DmaStreamReader.

It is illegal to close the DmaStreamReader more than once.

Examples

use glommio::{
    io::{DmaFile, DmaStreamReaderBuilder},
    LocalExecutor,
};

let ex = LocalExecutor::default();
ex.run(async {
    let file = DmaFile::open("myfile.txt").await.unwrap();
    let mut reader = DmaStreamReaderBuilder::new(file).build();
    reader.close().await.unwrap();
});

pub fn skip(&mut self, bytes: u64)

Skip reading bytes from this DmaStreamReader.

The file cursor is advanced by the provided bytes. As this is a linear access API, once those bytes are skipped they are gone. If you need to read those bytes, just not now, it is better to read them and save them in some temporary buffer.

Examples

use glommio::{
    io::{DmaFile, DmaStreamReaderBuilder},
    LocalExecutor,
};

let ex = LocalExecutor::default();
ex.run(async {
    let file = DmaFile::open("myfile.txt").await.unwrap();
    let mut reader = DmaStreamReaderBuilder::new(file).build();
    assert_eq!(reader.current_pos(), 0);
    reader.skip(8);
    assert_eq!(reader.current_pos(), 8);
    reader.close().await.unwrap();
});

pub fn current_pos(&self) -> u64

Acquires the current position of this DmaStreamReader.

Examples

use glommio::{
    io::{DmaFile, DmaStreamReaderBuilder},
    LocalExecutor,
};

let ex = LocalExecutor::default();
ex.run(async {
    let file = DmaFile::open("myfile.txt").await.unwrap();
    let mut reader = DmaStreamReaderBuilder::new(file).build();
    assert_eq!(reader.current_pos(), 0);
    reader.skip(8);
    assert_eq!(reader.current_pos(), 8);
    reader.close().await.unwrap();
});

pub async fn get_buffer_aligned(&mut self, len: u64) -> Result<ReadResult, ()>

Allows access to the buffer that holds the current position with no extra copy length may not cross into a different buffer. Users of this API are expected to be aware of their buffer size (selectable in the DmaStreamReaderBuilder) and act accordingly.

The buffer is also not released until the returned ReadResult goes out of scope. So if you plan to keep this alive for a long time this is probably the wrong API.

If EOF is hit while reading with this method, the number of bytes in the returned buffer will be less than number requested.

Let’s say you want to open a file and check if its header is sane: this is a good API for that.

But if after such header there is an index that you want to keep in memory, then you are probably better off with one of the methods from AsyncReadExt.

Examples

use glommio::{
    io::{DmaFile, DmaStreamReaderBuilder},
    LocalExecutor,
};

let ex = LocalExecutor::default();
ex.run(async {
    let file = DmaFile::open("myfile.txt").await.unwrap();
    let mut reader = DmaStreamReaderBuilder::new(file).build();
    assert_eq!(reader.current_pos(), 0);
    let result = reader.get_buffer_aligned(512).await.unwrap();
    assert_eq!(result.len(), 512);
    println!("First 512 bytes: {:?}", &*result);
    reader.close().await.unwrap();
});

Trait Implementations

impl AsyncRead for DmaStreamReader

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

Attempt to read from the AsyncRead into buf.

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

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl Debug for DmaStreamReader

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

Formats the value using the given formatter.