Struct glommio::io::DmaStreamReader

pub struct DmaStreamReader { /* private fields */ }

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.

This function returns a ReadResult. It contains all the bytes read, which can be less than the requested amount. Users are expected to call this in a loop like they would AsyncRead::poll_read.

The buffer is 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 and the remaining bytes will be 0.

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();
});

pub fn poll_get_buffer_aligned(
    &mut self,
    cx: &mut Context<'_>,
    len: u64
) -> Poll<Result<ReadResult, ()>>

A variant of get_buffer_aligned that can be called from a poll function context.

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.