Struct opendal::BlockingOperator

pub struct BlockingOperator { /* private fields */ }

BlockingOperator is the entry for all public blocking APIs.

Read concepts for know more about Operator.

Examples

Read more backend init examples in services

use opendal::services::Fs;
use opendal::BlockingOperator;
use opendal::Operator;
#[tokio::main]
async fn main() -> Result<()> {
    // Create fs backend builder.
    let mut builder = Fs::default();
    // Set the root for fs, all operations will happen under this root.
    //
    // NOTE: the root must be absolute path.
    builder.root("/tmp");

    // Build an `BlockingOperator` to start operating the storage.
    let _: BlockingOperator = Operator::new(builder)?.finish().blocking();

    Ok(())
}

Implementations

impl BlockingOperator

pub fn limit(&self) -> usize

Get current operator’s limit

pub fn with_limit(&self, limit: usize) -> Self

Specify the batch limit.

Default: 1000

pub fn info(&self) -> OperatorInfo

Get information of underlying accessor.

Examples

use opendal::BlockingOperator;

let info = op.info();

impl BlockingOperator

Operator blocking API.

pub fn stat(&self, path: &str) -> Result<Metadata>

Get current path’s metadata without cache directly.

Notes

Use stat if you:

• Want detect the outside changes of path.
• Don’t want to read from cached metadata.

You may want to use metadata if you are working with entries returned by Lister. It’s highly possible that metadata you want has already been cached.

Examples

use opendal::ErrorKind;
if let Err(e) = op.stat("test") {
    if e.kind() == ErrorKind::NotFound {
        println!("file not exist")
    }
}

pub fn metadata(
    &self,
    entry: &Entry,
    flags: impl Into<FlagSet<Metakey>>
) -> Result<Metadata>

Get current metadata with cache in blocking way.

metadata will check the given query with already cached metadata first. And query from storage if not found.

Notes

Use metadata if you are working with entries returned by Lister. It’s highly possible that metadata you want has already been cached.

You may want to use stat, if you:

• Want detect the outside changes of file.
• Don’t want to read from cached file metadata.

Behavior

Visiting not fetched metadata will lead to panic in debug build. It must be a bug, please fix it instead.

Examples

Query already cached metadata

By query metadata with None, we can only query in-memory metadata cache. In this way, we can make sure that no API call will send.

use opendal::Entry;

let meta = op.metadata(&entry, None)?;
// content length COULD be correct.
let _ = meta.content_length();
// etag COULD be correct.
let _ = meta.etag();

Query content length and content type

use opendal::Entry;
use opendal::Metakey;

let meta = op.metadata(&entry, { Metakey::ContentLength | Metakey::ContentType })?;
// content length MUST be correct.
let _ = meta.content_length();
// etag COULD be correct.
let _ = meta.etag();

Query all metadata

By query metadata with Complete, we can make sure that we have fetched all metadata of this entry.

use opendal::Entry;
use opendal::Metakey;

let meta = op.metadata(&entry, { Metakey::Complete })?;
// content length MUST be correct.
let _ = meta.content_length();
// etag MUST be correct.
let _ = meta.etag();

pub fn is_exist(&self, path: &str) -> Result<bool>

Check if this path exists or not.

Example

use anyhow::Result;
use opendal::BlockingOperator;
fn test(op: BlockingOperator) -> Result<()> {
    let _ = op.is_exist("test")?;

    Ok(())
}

pub fn create_dir(&self, path: &str) -> Result<()>

Create a dir at given path.

Notes

To indicate that a path is a directory, it is compulsory to include a trailing / in the path. Failure to do so may result in NotADirectory error being returned by OpenDAL.

Behavior

• Create on existing dir will succeed.
• Create dir is always recursive, works like mkdir -p

Examples

op.create_dir("path/to/dir/")?;

pub fn read(&self, path: &str) -> Result<Vec<u8>>

Read the whole path into a bytes.

This function will allocate a new bytes internally. For more precise memory control or reading data lazily, please use BlockingOperator::reader

Examples

let bs = op.read("path/to/file")?;

pub fn range_read(
    &self,
    path: &str,
    range: impl RangeBounds<u64>
) -> Result<Vec<u8>>

Read the specified range of path into a bytes.

This function will allocate a new bytes internally. For more precise memory control or reading data lazily, please use BlockingOperator::range_reader

Examples

let bs = op.range_read("path/to/file", 1024..2048)?;

pub fn reader(&self, path: &str) -> Result<BlockingReader>

Create a new reader which can read the whole path.

Examples

let r = op.reader("path/to/file")?;

pub fn range_reader(
    &self,
    path: &str,
    range: impl RangeBounds<u64>
) -> Result<BlockingReader>

Create a new reader which can read the specified range.

Examples

let r = op.range_reader("path/to/file", 1024..2048)?;

pub fn write(&self, path: &str, bs: impl Into<Bytes>) -> Result<()>

Write bytes into given path.

Notes

• Write will make sure all bytes has been written, or an error will be returned.

Examples

use bytes::Bytes;

op.write("path/to/file", vec![0; 4096])?;

pub fn write_with(
    &self,
    path: &str,
    args: OpWrite,
    bs: impl Into<Bytes>
) -> Result<()>

Write data with option described in OpenDAL rfc-0661

Notes

• Write will make sure all bytes has been written, or an error will be returned.

Examples

use bytes::Bytes;
use opendal::ops::OpWrite;

let bs = b"hello, world!".to_vec();
let ow = OpWrite::new().with_content_type("text/plain");
let _ = op.write_with("hello.txt", ow, bs)?;

pub fn writer(&self, path: &str) -> Result<BlockingWriter>

Write multiple bytes into given path.

Notes

• Write will make sure all bytes has been written, or an error will be returned.

Examples

use bytes::Bytes;

let mut w = op.writer("path/to/file")?;
w.append(vec![0; 4096])?;
w.append(vec![1; 4096])?;
w.close()?;

pub fn delete(&self, path: &str) -> Result<()>

Delete given path.

Notes

• Delete not existing error won’t return errors.

Examples

op.delete("path/to/file")?;

pub fn list(&self, path: &str) -> Result<BlockingLister>

List current dir path.

This function will create a new handle to list entries.

An error will be returned if path doesn’t end with /.

Examples

let mut ds = op.list("path/to/dir/")?;
while let Some(mut de) = ds.next() {
    let meta = op.metadata(&de?, {
        use opendal::Metakey::*;
        Mode
    })?;
    match meta.mode() {
        EntryMode::FILE => {
            println!("Handling file")
        }
        EntryMode::DIR => {
            println!("Handling dir like start a new list via de.path()")
        }
        EntryMode::Unknown => continue,
    }
}

pub fn scan(&self, path: &str) -> Result<BlockingLister>

List dir in flat way.

This function will create a new handle to list entries.

An error will be returned if given path doesn’t end with /.

Examples

let mut ds = op.list("path/to/dir/")?;
while let Some(mut de) = ds.next() {
    let meta = op.metadata(&de?, {
        use opendal::Metakey::*;
        Mode
    })?;
    match meta.mode() {
        EntryMode::FILE => {
            println!("Handling file")
        }
        EntryMode::DIR => {
            println!("Handling dir like start a new list via meta.path()")
        }
        EntryMode::Unknown => continue,
    }
}

Trait Implementations

impl Clone for BlockingOperator

fn clone(&self) -> BlockingOperator

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for BlockingOperator

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

Formats the value using the given formatter.