Struct queue_file::QueueFile

pub struct QueueFile { /* fields omitted */ }

QueueFile is a lightning-fast, transactional, file-based FIFO.

Addition and removal from an instance is an O(1) operation and is atomic. Writes are synchronous by default; data will be written to disk before an operation returns.

The underlying file. Uses a ring buffer to store entries. Designed so that a modification isn't committed or visible until we write the header. The header is much smaller than a segment. So long as the underlying file system supports atomic segment writes, changes to the queue are atomic. Storing the file length ensures we can recover from a failed expansion (i.e. if setting the file length succeeds but the process dies before the data can be copied).

Example

use queue_file::QueueFile;

let mut qf = QueueFile::open("example.qf")
    .expect("cannot open queue file");
let data = "Welcome to QueueFile!".as_bytes();

qf.add(&data).expect("add failed");

if let Ok(Some(bytes)) = qf.peek() {
    assert_eq!(data, bytes.as_ref());
}

qf.remove().expect("remove failed");

File format

  16-32 bytes      Header
  ...              Data

This implementation supports two versions of the header format.

Versioned Header (32 bytes):
  1 bit            Versioned indicator [0 = legacy, 1 = versioned]
  31 bits          Version, always 1
  8 bytes          File length
  4 bytes          Element count
  8 bytes          Head element position
  8 bytes          Tail element position

Legacy Header (16 bytes):
  1 bit            Legacy indicator, always 0
  31 bits          File length
  4 bytes          Element count
  4 bytes          Head element position
  4 bytes          Tail element position

Each element stored is represented by:

Element:
  4 bytes          Data length
  ...              Data

Methods

impl QueueFile

pub fn open<P: AsRef<Path>>(path: P) -> Result<QueueFile>

pub fn open_legacy<P: AsRef<Path>>(path: P) -> Result<QueueFile>

pub fn get_overwrite_on_remove(&self) -> bool

Returns true if removing an element will also overwrite data with zero bytes.

pub fn set_overwrite_on_remove(&mut self, value: bool)

If set to true removing an element will also overwrite data with zero bytes.

pub fn get_sync_writes(&self) -> bool

Returns true if every write to file will be followed by sync_data() call.

pub fn set_sync_writes(&mut self, value: bool)

If set to true every write to file will be followed by sync_data() call.

pub fn is_empty(&self) -> bool

Returns true if this queue contains no entries.

pub fn size(&self) -> usize

Returns the number of elements in this queue.

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

Adds an element to the end of the queue.

pub fn peek(&mut self) -> Result<Option<Box<[u8]>>>

Reads the eldest element. Returns OK(None) if the queue is empty.

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

Removes the eldest element.

pub fn remove_n(&mut self, n: usize) -> Result<()>

Removes the eldest n elements.

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

Clears this queue. Truncates the file to the initial size.

Important traits for Iter<'a>

impl<'a> Iterator for Iter<'a> type Item = Box<[u8]>;

pub fn iter(&mut self) -> Iter

Returns an iterator over elements in this queue.

Trait Implementations

impl Debug for QueueFile

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

Formats the value using the given formatter.