Struct zbox::File

pub struct File { /* fields omitted */ }

A reference to an opened file in the repository.

An instance of a File can be read and/or written depending on what options it was opened with. Files also implement Seek to alter the logical cursor that the file contains internally.

Files are automatically closed when they go out of scope.

As ZboxFS internally cached file content, it is no need to use buffered reader, such as BufReader<R>.

Examples

Create a new file and write bytes to it:

use std::io::prelude::*;

let mut file = repo.create_file("/foo.txt")?;
file.write_all(b"Hello, world!")?;
file.finish()?;

Read the content of a file into a String:

use std::io::prelude::*;

let mut file = repo.open_file("/foo.txt")?;
let mut content = String::new();
file.read_to_string(&mut content)?;
assert_eq!(content, "Hello, world!");

Versioning

File contents support up to 255 revision versions. Version is immutable once it is created.

By default, the maximum number of versions of a File is 1, which is configurable by version_limit on both Repo and File level. File level option takes precedence.

After reaching this limit, the oldest Version will be automatically deleted after adding a new one.

Version number starts from 1 and continuously increases by 1.

Writing

File content is cached internally for deduplication and will be handled automatically, thus calling flush is not recommended.

File can be sent to multiple threads, but only one thread can modify it at a time, which is similar to a RwLock.

File is multi-versioned, each time updating its content will create a new permanent Version. There are two ways of writing data to a file:

• Multi-part Write

  This is done by updating File using Write trait multiple times. After all writing operations, finish must be called to create a new version. Unless finish was successfully returned, no data will be written to the file.

  Internally, a transaction is created when writing to the file first time and calling finish will commit that transaction. If any errors happened during write, that transaction will be aborted. Thus, you should not call finish after any failed write.

  Because transactions is thread local, multi-part write should be done in one transaction.

  Examples

  use std::io::prelude::*;
  use std::io::SeekFrom;
  
  let mut file = OpenOptions::new()
      .create(true)
      .open(&mut repo, "/foo.txt")?;
  file.write_all(b"foo ")?;
  file.write_all(b"bar")?;
  file.finish()?;
  
  let mut content = String::new();
  file.seek(SeekFrom::Start(0))?;
  file.read_to_string(&mut content)?;
  assert_eq!(content, "foo bar");
  

• Single-part Write

  This can be done by calling write_once, which will call finish internally to create a new version. Unless this method was successfully returned, no data will be written to the file.

  Examples

  use std::io::{Read, Seek, SeekFrom};
  
  let mut file = OpenOptions::new()
      .create(true)
      .open(&mut repo, "/foo.txt")?;
  file.write_once(b"foo bar")?;
  
  let mut content = String::new();
  file.seek(SeekFrom::Start(0))?;
  file.read_to_string(&mut content)?;
  assert_eq!(content, "foo bar");
  

To gurantee atomicity, ZboxFS uses transaction when updating file so the data either be wholly persisted or nothing has been written.

• For multi-part write, the transaction begins in the first-time write and will be committed in finish. Any failure in write will abort the transaction, thus finish should not be called after that. If error happened during finish, the transaction will also be aborted.
• For single-part write, write_once itself is transactional. The transaction begins and will be committed inside this method.

Keep in mind of those characteristics, especially when writing a large amount of data to file, because any uncomitted transactions will abort and data in those transactions won't be persisted.

Reading

As File can contain multiple versions, Read operation can be associated with different versions. By default, reading on File object is always bound to the latest version. To read a specific version, a VersionReader, which supports Read trait as well, can be used.

Examples

Read the file content while it is in writing, notice that reading is always bound to latest content version.

use std::io::prelude::*;
use std::io::SeekFrom;

// create a file and write data to it
let mut file = OpenOptions::new().create(true).open(&mut repo, "/foo.txt")?;
file.write_once(&[1, 2, 3, 4, 5, 6])?;

// read the first 2 bytes
let mut buf = [0; 2];
file.seek(SeekFrom::Start(0))?;
file.read_exact(&mut buf)?;
assert_eq!(&buf[..], &[1, 2]);

// create a new version, now the file content is [1, 2, 7, 8, 5, 6]
file.write_once(&[7, 8])?;

// notice that reading is on the latest version
file.seek(SeekFrom::Current(-2))?;
file.read_exact(&mut buf)?;
assert_eq!(&buf[..], &[7, 8]);

Read multiple versions using VersionReader.

use std::io::prelude::*;

// create a file and write 2 versions
let mut file = OpenOptions::new()
    .version_limit(4)
    .create(true)
    .open(&mut repo, "/foo.txt")?;
file.write_once(b"foo")?;
file.write_once(b"bar")?;

// get latest version number
let curr_ver = file.curr_version()?;

// create a version reader and read latest version of content
let mut rdr = file.version_reader(curr_ver)?;
let mut content = String::new();
rdr.read_to_string(&mut content)?;
assert_eq!(content, "foobar");

// create another version reader and read previous version of content
let mut rdr = file.version_reader(curr_ver - 1)?;
let mut content = String::new();
rdr.read_to_string(&mut content)?;
assert_eq!(content, "foo");

Methods

impl File

pub fn metadata(&self) -> Result<Metadata>

Queries metadata about the file.

pub fn history(&self) -> Result<Vec<Version>>

Returns a list of all the file content versions.

pub fn curr_version(&self) -> Result<usize>

Returns the current content version number.

pub fn version_reader(&self, ver_num: usize) -> Result<VersionReader>

Get a reader of the specified version.

The returned reader implements Read trait. To get the version number, first call history to get the list of all versions and then choose the version number from it.

pub fn finish(&mut self) -> Result<()>

Complete multi-part write to file and create a new version.

This method will try to commit the transaction internally, no data will be persisted if it failed. Do not call this method if any previous write failed.

Errors

Calling this method without writing data before will return Error::NotWrite error.

pub fn write_once(&mut self, buf: &[u8]) -> Result<()>

Single-part write to file and create a new version.

This method provides a convenient way of combining Write and finish.

This method is atomic.

pub fn set_len(&mut self, len: usize) -> Result<()>

Truncates or extends the underlying file, create a new version of content which size to become size.

If the size is less than the current content size, then the new content will be shrunk. If it is greater than the current content size, then the content will be extended to size and have all of the intermediate data filled in with 0s.

This method is atomic.

Errors

This method will return an error if the file is not opened for writing or not finished writing.

Trait Implementations

impl Debug for File

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

Formats the value using the given formatter.

impl Read for File

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

unsafe fn initializer(&self) -> Initializer

🔬 This is a nightly-only experimental API. (read_initializer)

Determines if this Reader can work with buffers of uninitialized memory.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Read all bytes until EOF in this source, placing them into buf.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

Transforms this Read instance to an [Iterator] over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R> where
    R: Read, 

Creates an adaptor which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

Creates an adaptor which will read at most limit bytes from it.

impl Seek for File

fn seek(&mut self, pos: SeekFrom) -> Result<u64>

Seek to an offset, in bytes, in a stream.

fn stream_len(&mut self) -> Result<u64, Error>

🔬 This is a nightly-only experimental API. (seek_convenience)

Returns the length of this stream (in bytes).

fn stream_position(&mut self) -> Result<u64, Error>

🔬 This is a nightly-only experimental API. (seek_convenience)

Returns the current seek position from the start of the stream.

impl Write for File

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<()>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

fn write_vectored(&mut self, bufs: &[IoSlice]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_fmt(&mut self, fmt: Arguments) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

Creates a "by reference" adaptor for this instance of Write.