Struct mongodb::GridFsUploadStream

pub struct GridFsUploadStream { /* private fields */ }

A stream to which bytes can be written to be uploaded to a GridFS bucket.

Uploading to the Stream

The GridFsUploadStream type implements futures_io::AsyncWrite. It is recommended that users call the utility methods in AsyncWriteExt to interact with the stream.

Bytes can be written to the stream using the write methods in AsyncWriteExt. When close is invoked on the stream, any remaining bytes in the buffer are written to the chunks collection and a corresponding FilesCollectionDocument is written to the files collection. It is an error to write to, abort, or close the stream after close has been called.

use futures_util::io::AsyncWriteExt;

let bytes = vec![0u8; 100];
let mut upload_stream = bucket.open_upload_stream("example_file", None);
upload_stream.write_all(&bytes[..]).await?;
upload_stream.close().await?;

Aborting the Stream

A stream can be aborted by calling the abort method. This will remove any chunks associated with the stream from the chunks collection. It is an error to write to, abort, or close the stream after abort has been called.

use futures_util::io::AsyncWriteExt;

let bytes = vec![0u8; 100];
let mut upload_stream = bucket.open_upload_stream("example_file", None);
upload_stream.write_all(&bytes[..]).await?;
upload_stream.abort().await?;

In the event of an error during any operation on the GridFsUploadStream, any chunks associated with the stream will be removed from the chunks collection. Any subsequent attempts to write to, abort, or close the stream will return an error.

If a GridFsUploadStream is dropped prior to abort or close being called, its Drop implementation will spawn a task to remove any chunks associated with the stream from the chunks collection. Users should prefer calling abort explicitly to relying on the Drop implementation in order to await the task and inspect the result of the delete operation.

Flushing the Stream

Because all chunks besides the final chunk of a file must be exactly chunk_size_bytes, calling flush is not guaranteed to flush all bytes to the chunks collection. Any remaining buffered bytes will be written to the chunks collection upon a call to close.

Using tokio::io::AsyncWrite

Users who prefer to use tokio’s AsyncWrite trait can use the tokio_util::compat module.

use tokio_util::compat::FuturesAsyncWriteCompatExt;

let futures_upload_stream = bucket.open_upload_stream("example_file", None);
let tokio_upload_stream = futures_upload_stream.compat_write();

Implementations

impl GridFsUploadStream

pub fn id(&self) -> &Bson

Gets the stream’s unique Bson identifier. This value will be the id field for the FilesCollectionDocument uploaded to the files collection when the stream is closed.

pub async fn abort(&mut self) -> Result<()>

Aborts the stream, discarding any chunks that have already been written to the chunks collection. Once this method has been called, it is an error to attempt to write to, abort, or close the stream.

Trait Implementations

impl AsyncWrite for GridFsUploadStream

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

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.

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 Drop for GridFsUploadStream

fn drop(&mut self)

Executes the destructor for this type.