Struct glommio::io::DmaStreamWriter

pub struct DmaStreamWriter { /* 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.

Very rarely does one need to issue random writes to a file. Therefore, the DmaStreamWriter is likely your go-to API when it comes to writing files.

The DmaStreamWriter implements AsyncWrite. Because it is backed by a Direct I/O file, the flush method has no effect. Closing the file issues a sync so that the data can be flushed from the internal NVMe caches.

Implementations

impl DmaStreamWriter

pub fn current_pos(&self) -> u64

Acquires the current position of this DmaStreamWriter.

Examples

use glommio::io::{DmaFile, DmaStreamWriterBuilder};
use glommio::LocalExecutor;
use futures::io::AsyncWriteExt;

let ex = LocalExecutor::default();
ex.run(async {
    let file = DmaFile::create("myfile.txt").await.unwrap();
    let mut writer = DmaStreamWriterBuilder::new(file).build();
    assert_eq!(writer.current_pos(), 0);
    writer.write_all(&[0, 1, 2, 3, 4]).await.unwrap();
    assert_eq!(writer.current_pos(), 5);
    writer.close().await.unwrap();
});

pub fn current_flushed_pos(&self) -> u64

Acquires the current position of this DmaStreamWriter that is flushed to the underlying media.

Warning: the position reported by this API is not restart or crash safe. You need to call sync for that. Although the DmaStreamWriter uses Direct I/O, modern storage devices have their own caches and may still lose data that sits on those caches upon a restart until sync is called (Note that close implies a sync).

However within the same session, new readers trying to read from any position before what we return in this method will be guaranteed to read the data we just wrote.

Examples

use glommio::io::{DmaFile, DmaStreamWriterBuilder};
use glommio::LocalExecutor;
use futures::io::AsyncWriteExt;

let ex = LocalExecutor::default();
ex.run(async {
    let file = DmaFile::create("myfile.txt").await.unwrap();
    let mut writer = DmaStreamWriterBuilder::new(file).build();
    assert_eq!(writer.current_pos(), 0);
    writer.write_all(&[0, 1, 2, 3, 4]).await.unwrap();
    assert_eq!(writer.current_pos(), 5);
    // The write above is not enough to cause a flush
    assert_eq!(writer.current_flushed_pos(), 0);
    writer.close().await.unwrap();
    // Close implies a forced-flush and a sync.
    assert_eq!(writer.current_flushed_pos(), 5);
});

pub async fn sync(&self) -> Result<u64, ()>

Waits for all currently in-flight buffers to return and be safely stored in the underlying storage

Note that the current buffer being written to is not flushed, as it may not be properly aligned. Buffers that are currently in-flight will be waited on, and a sync operation will be issued by the operating system.

Returns the flushed position of the file at the time the sync started.

Examples

use glommio::io::{DmaFile, DmaStreamWriterBuilder};
use glommio::LocalExecutor;
use futures::io::AsyncWriteExt;

let ex = LocalExecutor::default();
ex.run(async {
    let file = DmaFile::create("myfile.txt").await.unwrap();
       let mut writer = DmaStreamWriterBuilder::new(file)
            .with_buffer_size(4096)
            .with_write_behind(2)
            .build();
       let buffer = [0u8; 5000];
    writer.write_all(&buffer).await.unwrap();
    // with 5000 bytes written into a 4096-byte buffer a flush
    // has certainly started. But if very likely didn't finish right
    // away. It will not be reflected on current_flushed_pos(), but a
    // sync() will wait on it.
    assert_eq!(writer.current_flushed_pos(), 0);
    assert_eq!(writer.sync().await.unwrap(), 4096);
    writer.close().await.unwrap();
});

Trait Implementations

impl AsyncWrite for DmaStreamWriter

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

Attempt to write bytes from buf into the object.

fn poll_flush(self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to flush the object, ensuring that any buffered data reach their destination.

fn poll_close(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Attempt to close the object.

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

Attempt to write bytes from bufs into the object using vectored IO operations.

impl Debug for DmaStreamWriter

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

Formats the value using the given formatter.